使用 Docker Buildx 构建多架构镜像并推送到私有 HTTP Registry

在日常开发中，我们可能需要将镜像推送到私有 Docker Registry，而且希望支持多平台（如 amd64 和 arm64）。本文介绍一种完整流程，包括 BuildKit 配置、Buildx Builder 创建、multi-arch 构建与推送。

1. 前提条件

• Docker 版本 ≥ 24
• 安装 Docker Buildx
• 私有 Registry（HTTP / 不安全）
• 需要构建的平台：linux/amd64、linux/arm64
• 已设置 HTTP 代理（如公司内网环境）

2. 创建 BuildKit 配置文件

在服务器上创建 BuildKit 配置文件，例如 /root/.docker/buildkitd.toml：

1
2
3
4
5
6
7
8
9

debug = true

# 允许不安全的 entitlements
insecure-entitlements = ["my-private-registry"]

# 配置私有 Registry
[registry."my-private-registry"]
  http = true
  insecure = true

⚠️ my-private-registry 替换为你的私有 Registry 地址（IP 或域名）。

3. 创建 Buildx Builder

使用 docker buildx create 创建 builder，并启用自定义配置和代理：

1
2
3
4
5
6
7
8
9
10

docker buildx create \
  --name multiarch \
  --use \
  --driver docker-container \
  --config /root/.docker/buildkitd.toml \
  --driver-opt network=host \
  --driver-opt env.http_proxy=http://proxy.example.com:10808 \
  --driver-opt env.https_proxy=http://proxy.example.com:10808 \
  --driver-opt env.no_proxy=my-private-registry \
  --driver-opt env.NO_PROXY=my-private-registry

检查 Builder 是否生效：

1
2

docker buildx ls
docker buildx inspect multiarch --bootstrap

4. 构建并推送多架构镜像

使用 Buildx 的 --platform 参数一次构建多平台镜像，并直接推送到私有 Registry：

1
2
3
4
5

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t my-private-registry/my-app:latest \
  --push \
  .

✅ 关键点：

• --platform 指定多平台。
• --push 直接将镜像推送到 Registry。
• 如果 Registry 是 HTTP 不安全的，确保在 BuildKit 配置中设置了 http = true 和 insecure = true。

5. 验证 multi-arch 镜像

1

docker manifest inspect my-private-registry/my-app:latest

你会看到类似的输出，包含 amd64 和 arm64 两个平台信息：

1
2
3
4
5
6

{
  "manifests": [
    { "platform": { "architecture": "amd64", "os": "linux" }, ... },
    { "platform": { "architecture": "arm64", "os": "linux" }, ... }
  ]
}

拉取镜像时，Docker 会根据本机平台自动选择对应架构：

1

docker pull my-private-registry/my-app:latest

6. 总结

通过以上流程，你可以：

1. 支持 HTTP / 不安全的私有 Registry。
2. 一次构建并推送 多平台镜像。
3. 避免手动推送单平台镜像再创建 manifest 的繁琐流程。
4. 支持代理环境与 BuildKit 配置，便于企业内网部署。