如何在两个镜像仓库之间迁移 Docker 跨平台镜像

Docker 跨平台镜像迁移：从理论到实战的完整指南

在云原生和混合架构日益普及的今天，Docker 镜像迁移——尤其是跨平台迁移——已成为一项常见却颇为关键的运维操作。无论是为了提升国内访问速度，还是为了将公共镜像纳入私有化资产管理，你都需要一套可靠且高效的迁移方案。今天，我们就来深入聊聊，如何将 Docker Hub 等源站的跨平台镜像，稳妥地迁移到自建或云上的私有镜像仓库。

免费影视、动漫、音乐、游戏、小说资源长期稳定更新！ 👉 点此立即查看 👈

单平台镜像迁移

如果目标环境架构单一，事情会简单得多。传统的「拉取-重命名-推送」三板斧，依然是最直观的策略。

第一步：拉取源镜像。通过 docker pull 命令，将所需镜像拉到本地或中转主机。

第二步：重命名标签。使用 docker tag ，为镜像打上符合目标仓库地址的新标签。

第三步：推送到目标仓库。执行 docker push ，完成上传。

操作完成后，别忘了用 docker rmi 清理一下本地缓存，毕竟磁盘空间也是宝贵资源。

一个关键提示：在执行推送前，务必通过 docker login 完成对目标仓库的身份验证。对于生产环境，强烈建议在标签中明确使用版本号，避免依赖默认的、可能发生变化的 latest 标签。

这个方案在处理单架构镜像时确实高效，但其局限性也显而易见：docker pull 默认只会拉取与当前主机 CPU 架构匹配的单一镜像。

随着 ARM64 架构在服务器、边缘计算乃至开发机上的广泛应用，这种「本地中转」模式已经跟不上节奏了。想想看，如果仅在 x86 机器上操作，最终得到的镜像根本无法在 ARM 节点上运行。为了解决这一痛点，我们需要一种能够同时迁移多种架构（如 amd64、arm64），并保持其清单列表（Manifest List）关联性的方案。于是，跨平台镜像迁移的需求便浮出水面。

跨平台镜像迁移

接下来，我们以 Docker Hub 上的 golang:1.25-alpine 镜像为例，演示如何将其完整迁移至阿里云私有镜像仓库。

方案一：使用 Docker Buildx

Docker Buildx 是官方力推的下一代构建工具，处理跨平台镜像堪称得心应手。

1. 初始化构建器（若尚未配置）

$ docker buildx create --name mybuilder --use
$ docker buildx inspect --bootstrap

2. 执行一键迁移命令

# 变量定义，私有仓库地址
TARGET="crpi-1ql0kmu5z0c9xt5q.cn-hangzhou.personal.cr.aliyuncs.com/jianghushinian/golang:1.25-alpine"
# 使用 buildx 同时构建并推送 amd64 和 arm64 架构
$ echo "FROM golang:1.25-alpine" | docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t ${TARGET} \
  --push -

只需一行命令，就能同时构建并推送 amd64 和 arm64 架构的镜像到私有仓库。这里用了个小技巧：通过标准输入传入内容，省去了创建物理 Dockerfile 的步骤。

当然，还有更极简的方式：

# 变量定义
SOURCE="golang:1.25-alpine"
TARGET="crpi-1ql0kmu5z0c9xt5q.cn-hangzhou.personal.cr.aliyuncs.com/jianghushinian/golang:1.25-alpine"
# 直接创建并推送新的 manifest
$ docker buildx imagetools create --tag ${TARGET} ${SOURCE}

你甚至无需创建构建器，就能直接将完整的跨平台镜像从一个仓库「逻辑复制」到另一个仓库，镜像数据不经过本地，非常轻量。

那么，docker buildx build 和 docker buildx imagetools 有什么区别呢？简单来说，前者会经过构建过程（可能触发构建缓存和层创建），适合需要重新封装或注入变化的场景；后者更像是纯粹的元数据搬运工，效率更高，但对源站和目标站的兼容性要求也更高。

如果你的 Docker 版本比较老旧，没有 buildx 支持，别担心，更底层的命令组合依然能完成任务。

方案二：使用传统 Docker Pull/Push

在某些环境下，最原始的方法反而最可靠。通过 docker pull/push 命令结合 docker manifest，我们同样能实现跨平台迁移。

具体步骤如下：

# 变量定义
VERSION="1.25-alpine"
SOURCE_IMAGE="golang:${VERSION}"
TARGET_REPO="crpi-1ql0kmu5z0c9xt5q.cn-hangzhou.personal.cr.aliyuncs.com/jianghushinian/golang"

# 1. 处理 amd64 架构
$ docker pull --platform=linux/amd64 ${SOURCE_IMAGE}
$ docker tag ${SOURCE_IMAGE} ${TARGET_REPO}:${VERSION}-amd64
$ docker push ${TARGET_REPO}:${VERSION}-amd64

# 2. 处理 arm64 架构
$ docker pull --platform=linux/arm64 ${SOURCE_IMAGE}
$ docker tag ${SOURCE_IMAGE} ${TARGET_REPO}:${VERSION}-arm64
$ docker push ${TARGET_REPO}:${VERSION}-arm64

# 3. 创建多架构 Manifest
# 这会将 amd64 和 arm64 两个镜像关联到同一个标签 ${VERSION} 下
$ docker manifest create \
  ${TARGET_REPO}:${VERSION} \
  ${TARGET_REPO}:${VERSION}-amd64 \
  ${TARGET_REPO}:${VERSION}-arm64

# 4. 推送 Manifest 到阿里云
$ docker manifest push ${TARGET_REPO}:${VERSION}

这个过程步骤清晰，就是纯手工操作，有点像「体力活」，但它能让你对整个镜像的层次和清单结构有最透彻的理解。

方案选型

到底该用哪种方式？答案是：看场景。能够达到目的的都是好工具，但封装程度更高的工具，有时也会遇到限制。

例如，使用 docker buildx imagetools 时，你可能会遇到类似错误：

ERROR: failed commit on ref "layer-sha256:4bd07550e32f74fc2f29bbf38b34a2138634737d53907ad72ea1f4f7923129de": unexpected size 0, expected 126

这通常与目标镜像仓库的实现细节有关。此时，docker buildx build 或者传统的 docker manifest 方案就成了可靠的备选。

甚至，你还可以考虑 Skopeo、Crane 等第三方工具，它们通常设计得更适合集成到 CI/CD 流水线中，用一行命令就能完成迁移。

说到底，没有一种工具是万能的。自动化工具是提升效率的利器，但深入理解 docker manifest 这类底层逻辑，才是你在面对复杂环境或突发故障时，能够从容应对、确保交付的底气所在。

总结

回顾一下，我们探讨了实现跨平台镜像迁移的三条主要路径：

• 追求极致效率：首选 docker buildx imagetools，它利用「逻辑同步」实现近乎秒级的迁移，且不占用本地资源。

• 确保物理落地：使用 docker buildx build 通过 BuildKit 重新封装，是应对复杂网络和仓库兼容性问题的强力手段。

• 回归底层原理：通过传统的 pull/push 结合 docker manifest 手动操作。步骤虽繁，却是理解镜像分发机制的基石，堪称故障排查时的终极「保底方案」。

至于第三方软件，它们提供了更多样的选择，你可以根据自身技术栈和偏好进行尝试。希望这份梳理，能帮你找到最适合自己当前场景的那把钥匙。