如何构建自适应架构的镜像

目标

我有一个服务叫xxx，一开始它运行在x86架构的机器上，所以最开始有个xxx:stable-amd64的镜像，后来它又需要运行在arm64架构的机器上，所以又重新打了个xxx:stable-arm64的镜像
但是对于安装脚本来说，我不希望我在拉取镜像时还有根据服务器架构去区分arm64和amd64两个tag，是否可以用一个tag让docker pull命令根据当前执行的机器的架构自动区分不同的tag呢？

实现

要实现用户通过docker pull xxx:stable自动根据其系统架构拉取对应的镜像（xxx:stable-arm64或xxx:stable-amd64），你需要创建一个 多架构镜像清单（Manifest List）。以下是详细步骤：

---

前提条件

1. 已安装 Docker CLI 18.03+（建议使用最新版本）
2. 确保已登录 Docker Hub 或其他镜像仓库：

   docker login
   

3. 两个镜像已推送到镜像仓库：

   docker push xxx:stable-arm64
   docker push xxx:stable-amd64
   

---

步骤 1：创建多架构 Manifest List

使用 docker manifest 命令（需启用 Docker CLI 实验性功能）：

# 启用 Docker CLI 实验性功能（Linux/macOS）
export DOCKER_CLI_EXPERIMENTAL=enabled

# 创建 Manifest List
docker manifest create xxx:stable \
  xxx:stable-arm64 \
  xxx:stable-amd64

---

步骤 2：为每个架构指定平台

# 为 arm64 镜像添加架构信息
docker manifest annotate xxx:stable xxx:stable-arm64 \
  --arch arm64

# 为 amd64 镜像添加架构信息
docker manifest annotate xxx:stable xxx:stable-amd64 \
  --arch amd64

---

步骤 3：推送 Manifest List 到仓库

docker manifest push xxx:stable

---

验证 Manifest List

docker manifest inspect xxx:stable

输出应包含两个架构的镜像信息：

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

---

用户拉取镜像

用户只需运行：

docker pull xxx:stable

Docker 会自动根据用户的系统架构（arm64 或 amd64）拉取匹配的镜像。

---

注意事项

1. 镜像仓库支持：确保使用的镜像仓库（如 Docker Hub、Harbor）支持 Manifest V2。
2. 镜像标签一致性：所有子镜像（如 xxx:stable-arm64）必须存在于仓库中。
3. Buildx 替代方案（推荐）：
   未来构建多架构镜像时，可直接用 docker buildx 一次性构建并推送 Manifest List：

   docker buildx build --platform linux/amd64,linux/arm64 \
     -t xxx:stable \
     --push .
   

---

通过以上步骤，xxx:stable 就成为了一个多架构镜像，Docker 会自动为用户选择正确的架构镜像。