Skip to content

DOCKER_BUILD.md

Latest commit

 

History

History
316 lines (217 loc) · 5.83 KB

DOCKER_BUILD.md

File metadata and controls

316 lines (217 loc) · 5.83 KB

Docker 多平台构建和发布指南

快速指南：使用 Docker Buildx 构建多平台镜像并发布到 Docker Hub。

🚀 快速开始

1. 配置 Docker Hub 访问令牌

# 复制配置模板
cp .env.docker .env.docker.local

# 编辑配置文件
vim .env.docker.local

填入你的信息:

VERSION=v1.0.0
DOCKERHUB_USERNAME=your-username
DOCKERHUB_TOKEN=dckr_pat_xxxxxxxxxxxxx

获取访问令牌:

  1. 访问 https://hub.docker.com/settings/security
  2. 点击 "New Access Token"
  3. 输入描述并选择 "Read, Write, Delete" 权限
  4. 复制生成的令牌

2. 本地构建测试

# 加载环境变量
source .env.docker.local

# 本地构建 (不推送)
./docker-build.sh

3. 推送到 Docker Hub

# 方式一: 使用快速推送脚本 (推荐)
./docker-push.sh v1.0.0

# 方式二: 手动加载配置
source .env.docker.local
./docker-build.sh --push --version v1.0.0

# 方式三: 使用 Makefile
make docker-build-push VERSION=v1.0.0

📋 支持的平台

  • linux/amd64 - x86_64 (服务器、PC)
  • linux/arm64 - ARM64 (Apple Silicon、树莓派 4/5)
  • linux/arm/v7 - ARMv7 (树莓派 2/3)

🛠️ 使用方法

方式一: 使用快速推送脚本 (推荐)

最简单的方式，自动加载配置：

# 推送到 Docker Hub
./docker-push.sh v1.0.0

# 使用默认版本 (latest)
./docker-push.sh

方式二: 使用构建脚本

更多控制选项：

# 先加载配置
source .env.docker.local

# 查看帮助
./docker-build.sh --help

# 本地构建
./docker-build.sh

# 构建并推送
./docker-build.sh --push --version v1.0.0

# 构建特定平台
./docker-build.sh --platforms linux/amd64,linux/arm64

# 不使用缓存
./docker-build.sh --no-cache --push

方式三: 使用 Makefile

集成到开发流程：

# 查看所有命令
make help

# 本地构建
make docker-build

# 构建并推送
make docker-build-push VERSION=v1.0.0

# 完整发布流程 (测试、编译、构建、推送)
make release-docker VERSION=v1.0.0

📝 命令选项

选项 说明
-v, --version VERSION 指定版本号 (默认: latest)
-p, --push 构建并推送到 Docker Hub
-l, --load 构建并加载到本地
--no-cache 不使用缓存
--platforms PLATFORMS 指定目标平台
-h, --help 显示帮助信息

🌟 使用示例

示例 1: 开发测试

# 本地构建单个平台 (快速测试)
./docker-build.sh --platforms linux/amd64 --load

# 运行容器测试
docker run --rm redis-proxy:latest --version

示例 2: 发布新版本

# 1. 加载配置
source .env.docker.local

# 2. 构建并推送
./docker-build.sh --push --version v1.2.3

# 3. 验证
docker pull your-username/redis-proxy:v1.2.3

示例 3: 使用 Git 标签

# 1. 创建 Git 标签
git tag v1.0.0
git push origin v1.0.0

# 2. 使用标签版本构建
VERSION=$(git describe --tags) ./docker-build.sh --push

示例 4: CI/CD 集成

#!/bin/bash
# 在 CI/CD 中使用

# 设置环境变量
export DOCKERHUB_USERNAME=$CI_DOCKERHUB_USERNAME
export DOCKERHUB_TOKEN=$CI_DOCKERHUB_TOKEN
export VERSION=$CI_COMMIT_TAG

# 构建并推送
./docker-build.sh --push --version $VERSION

🔧 故障排查

问题 1: 构建器创建失败

# 删除旧构建器
docker buildx rm multiarch-builder

# 重新运行脚本
./docker-build.sh

问题 2: 跨平台构建失败

# 安装 QEMU
docker run --privileged --rm tonistiigi/binfmt --install all

# 验证
docker buildx ls

问题 3: 认证失败

# 检查环境变量
echo $DOCKERHUB_TOKEN

# 手动登录测试
docker login -u $DOCKERHUB_USERNAME

# 重新加载配置
source .env.docker.local

问题 4: 磁盘空间不足

# 清理未使用的镜像
docker system prune -a

# 清理构建缓存
docker buildx prune -a

📦 拉取镜像

构建完成后，用户可以这样拉取镜像:

# 拉取指定版本
docker pull your-username/redis-proxy:v1.0.0

# 拉取最新版本
docker pull your-username/redis-proxy:latest

# 运行容器
docker run -d \
  --name redis-proxy \
  -p 16379:16379 \
  -e REDIS_HOST=your-redis-host \
  -e REDIS_PORT=6379 \
  -e REDIS_PASSWORD=your-password \
  your-username/redis-proxy:v1.0.0

🔐 安全最佳实践

  1. 不要提交密码

    • 使用 .env.docker.local 存储敏感信息
    • 已在 .gitignore 中排除

  2. 使用访问令牌

    • 不要使用 Docker Hub 密码
    • 使用访问令牌更安全

  3. 定期轮换令牌

    • 建议每 3-6 个月更换一次
    • 如果泄露立即撤销

  4. 最小权限原则

    • 为不同项目创建不同的令牌
    • 只授予必要的权限

📚 相关文档

❓ 常见问题

Q: 为什么要使用 Buildx？
A: Buildx 支持多平台构建，一次构建可以生成多个架构的镜像。

Q: 构建需要多长时间？
A: 首次构建约 5-10 分钟，后续使用缓存约 1-2 分钟。

Q: 可以只构建单个平台吗？
A: 可以，使用 --platforms linux/amd64 指定单个平台。

Q: 如何查看构建日志？
A: 脚本会实时显示构建日志，包括彩色输出。

Q: 支持私有仓库吗？
A: 支持，只要正确配置访问令牌即可。

💡 提示

  • 首次构建建议先不推送，使用 ./docker-build.sh 测试
  • 使用 --load 可以将镜像加载到本地 Docker
  • 版本号建议遵循语义化版本规范 (如 v1.2.3)
  • 每个版本会同时推送 vX.X.X 和 latest 两个标签

祝你构建愉快！ 🎉