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

---

## 准备条件

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

确保 Docker 可以正常运行：

```bash
docker version
```

---

## 安装并配置 Buildx

1. 查看当前 buildx：

```bash
docker buildx ls
```

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

```bash
docker buildx create --name multiarch --use
```

3. 启动并初始化 builder：

```bash
docker buildx inspect --bootstrap
```

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

---

## 启用 QEMU 支持跨平台构建

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

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

再次 bootstrap builder：

```bash
docker buildx inspect --bootstrap
```

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

---

## 检查本地镜像（可选）

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

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

示例：

```json
"Architecture": "arm64",
"Os": "linux"
```

---

## 构建多平台镜像并推送

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

```bash
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：

```bash
docker manifest inspect koalalove/moodle:5.1.1
```

输出示例：

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

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

```bash
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"`

---