Docker 多平台镜像构建与推送教程（arm64 主机示例）

---

准备条件

• Docker >= 20.10
• Docker Hub 账号
• 主机架构示例：arm64
• 已有 Dockerfile

确保 Docker 可以正常运行：

docker version

---

安装并配置 Buildx

1. 查看当前 buildx：

docker buildx ls

1. 创建多平台 builder（如果已存在可跳过）：

docker buildx create --name multiarch --use

1. 启动并初始化 builder：

docker buildx inspect --bootstrap

确保输出包含 Platforms: linux/amd64, linux/arm64, ...

---

启用 QEMU 支持跨平台构建

在 arm64 主机上构建 amd64 镜像，需要 QEMU 模拟：

docker run --rm --privileged tonistiigi/binfmt --install all

再次 bootstrap builder：

docker buildx inspect --bootstrap

输出 Platforms 应包含 linux/amd64 和 linux/arm64

---

检查本地镜像（可选）

确保你的单平台镜像 metadata 正确：

docker inspect <镜像ID或名称> | grep -A5 -i Architecture

示例：

"Architecture": "arm64",
"Os": "linux"

---

构建多平台镜像并推送

假设镜像名为 koalalove/moodle:5.1.1：

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t koalalove/moodle:5.1.1 \
  --push .

解释：

• --platform linux/amd64,linux/arm64：构建 amd64 和 arm64
• -t koalalove/moodle:5.1.1：生成的镜像 tag
• --push：构建完成直接推送到 Docker Hub
• 构建完成后，Docker Hub 上的 tag 5.1.1 会自动生成 multi-arch manifest

如果想只构建本地当前平台，可加 --load，但多架构必须使用 --push

---

验证多架构镜像

1. 查看 Hub 上 manifest：

docker manifest inspect koalalove/moodle:5.1.1

输出示例：

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    { "platform": {"architecture": "amd64", "os": "linux"} },
    { "platform": {"architecture": "arm64", "os": "linux"} }
  ]
}

1. 拉取镜像时，Docker 会根据客户端架构自动选择：

docker pull koalalove/moodle:5.1.1
docker images

• arm64 客户端拉 arm64 镜像
• amd64 客户端拉 amd64 镜像

---

总结

• 使用 buildx + QEMU 可以在 arm64 主机上构建 amd64 镜像
• 使用 --platform 指定目标架构
• 使用 --push 可以直接在 Docker Hub 上生成 multi-arch 镜像
• 验证 docker manifest inspect 确认镜像支持多架构

---

💡 推荐实践

• 对于多平台镜像，尽量使用 一条命令直接构建并推送
• 避免手动 merge manifest list
• 确保 Hub 上旧 tag 已删除，避免生成 "architecture": "unknown"

---