1. 迁移场景与整体方案设计做镜像仓库迁移这件事通常不是“把文件拷过去”那么简单。尤其是当你的镜像已经不是单个平台镜像而是一整套多架构 manifest 列表的时候直接docker pull再docker push就有大坑。我在这类迁移上踩过不少坑今天就把用 Docker buildx 完成多架构镜像仓库迁移的完整思路、实操步骤还有排查经验一次说清。先说清楚核心场景。假设你原来有一套镜像中心可能是自建的、也可能是某个云厂商提供的镜像仓库现在因为成本、容量、安全策略或者统一管理需求要把里面的镜像整体搬到另一个仓库。更麻烦的是你的镜像不是单一 amd64 架构而是同时支持 x86_64、ARM64甚至还有 ARMv7比如常见的linux/amd64、linux/arm64、linux/arm/v7。这种情况下如果直接用docker pull某平台镜像再docker tag和docker push你会发现你迁移过去的只是当前平台的单架构镜像整个多架构 manifest 列表丢了。那些拿到 arm64 设备上拉取镜像的用户会直接拉到 amd64 版本运行直接报 exec format error。所以迁移多架构镜像的关键是保留 manifest list 结构。而 Docker buildx 恰好是处理这种场景的核心工具。它的真正价值不只是“跨平台构建”而是围绕 multi-platform 镜像的完整生命周期包括构建、合并、推送。换句话说buildx 不只是拿来build的它是你操作多架构镜像的瑞士军刀。在迁移这条路上我一般会先给方案做一次“体检”。你需要先理清几个问题源仓库里有多少个镜像每个镜像的 namespace 和 tag 结构是什么。这些镜像是原本就带多架构 manifest还是只有单架构。目标仓库是否开放了 OCI 规范的相关接口比如是否支持 manifest list 的 push。是否有海外环境、认证体系、网络带宽限制等外部约束。把这些搞清楚之后再决定迁移策略。我实际使用下来有三条比较成熟的路线如果原镜像本身就是多架构 manifest 列表且你只想迁移而不做任何改动那优先用buildx提供的--platform参数配合imagetools子命令来完成。这是最稳、最快、最不破坏原结构的方式。如果你希望迁移的同时替换基础镜像、调整环境变量、换掉启动命令那就要重新构建。这种情况下docker buildx build --platform是首选因为一条命令就能构建多平台并推送到新仓库。如果源仓库里既有单架构镜像、又有多架构镜像混合在一起那建议先做清单扫描按类型分流再分别处理。我个人的习惯是不管哪种路线迁移之前先在本地写好一份镜像清单包括仓名、标签、平台列表、大小既方便核对也方便后续写脚本批量执行。你千万别嫌这一步麻烦很多迁移失败都发生在“我以为我都知道了”的状态下。2. 核心概念拆解buildx 到底做了什么很多人以为docker buildx只是docker build的升级版会更快。这话只对了一半。buildx 的核心革新在于它把 “构建” 和 “打包” 解耦了。它通过 Builder 实例来管理构建环境可以用 docker driver也可以用 kubernetes driver甚至可以用远程节点。而真正迁移多架构镜像时我们依赖的是其中几个关键能力。2.1 多架构镜像与 manifest list 的核心逻辑在深入命令之前先讲清楚 manifest 这个概念。普通单架构镜像就是一个 manifest 文件加一堆 layer。多架构镜像则是一个 manifest list也叫 Image Index里面记录了一组架构, manifest的映射关系。当客户端去拉取镜像时会根据当前平台自动选择对应的 manifest再拉取相应的 layer。如果你迁移的时候把 manifest list 拆散了只 push 了一个平台那就等于把多架构支持给砍了。更麻烦的是如果源仓库里的镜像格式是 Docker Schema 2目标仓库却只支持 OCI 格式push 的时候还容易遇到格式兼容问题。buildx 内部对于 manifest 的处理非常聪明它并不需要你在本地完整下载所有架构的镜像才可以 push。它可以基于 registry 之间的跨仓库迁移能力或者直接通过imagetools子命令操作远程 manifest做到只复制元数据就可以完成迁移。2.2 buildx 构建器类型选择的关键权衡docker buildx默认会创建一个 builder但其实它底层是经典的 docker driver。docker driver 不支持多平台构建构建 arm64 镜像时会在模拟环境里跑性能差。真正要用的往往是docker-containerdriver。这个 driver 会在本地启动一个 buildkit 容器支持多平台并发构建也支持本地缓存。如果你要迁移的镜像基本都是现成的不需要重新构建那其实不需要很重型的 builder。但如果你要走“重新构建再迁移”这条路那我强烈建议你创建一个docker-containerdriver并把缓存目录挂载到宿主机。这样不仅构建速度快后期迭代也方便。创建方式如下在我实际操作中会先查看现有 builder再创建专用 builderdocker buildx ls docker buildx create --name multiarch-builder --driver docker-container --use docker buildx inspect --bootstrap指定挂载缓存目录的话可以加--driver-opt参数但注意不同版本的 buildx 支持的 driver-opt 略有差异。我一般会在规模较大的迁移场景里加上这个docker buildx create --name multiarch-builder --driver docker-container \ --driver-opt networkhost \ --buildkitd-config /etc/buildkitd.toml其实这个 builder 的生命周期管理也是坑点之一。你要是用临时容器做迁移完成后记得docker buildx rm避免残留 builder 占用磁盘或端口。2.3 imagetools 是迁移的秘密武器docker buildx imagetools是很多人容易忽略的子命令但它对镜像迁移来说非常关键。它可以像操作本地镜像一样直接操作远程仓库中的 manifest 列表。最常用的三个操作docker buildx imagetools inspect image查看远程镜像的 manifest 信息包括平台列表和架构详情。docker buildx imagetools create将多个单平台镜像合并为一个多平台镜像。docker buildx imagetools push把本地构建的 index 推送到远程。在迁移场景里我经常先用inspect确认源镜像的平台列表再用create构建一个新的 manifest list 直接推送到目标仓库整个过程完全不需要在本地落盘任何完整的镜像层。这个方法尤其适合那种“原仓库镜像已经按照单平台拆分存放目标仓库想要一个多平台镜像”的情况。3. 实操过程与核心环节实现下面进入完整实操环节。我以“从旧仓库 A 迁移到新仓库 B镜像都带多架构 manifest”为例用最通用、最好复现的步骤来讲。3.1 环境准备与登录配置迁移前先确认两个仓库的登录权限。很多迁移卡在认证尤其是目标仓库带有特定前缀的时候容易因为 docker config 里的多个 credentials 相互覆盖导致 push 失败。确保 Docker CLI 和 buildx 插件都是较新版本docker --version docker buildx version登录源仓库和目标仓库docker login old-registry.example.com docker login new-registry.example.com如果你用的是云厂商提供的临时凭证务必确认凭证是否在有效期内且 notary 或签名校验相关的配置不会干扰正常 push。有些私有仓库开了内容信任Docker Content Trust迁移时需要显式跳过签名校验否则 push 会报“未签名”错误。这种场景下我一般会加环境变量规避export DOCKER_CONTENT_TRUST03.2 用 imagetools 直连迁移现有 manifest如果你的源镜像已经是多架构镜像且没有内容改造需求最稳的是直接复制 index 和 manifest。这里有一个非常实用的技巧先用 imagetools inspect 看你是否能直接从远程读取源仓库的 manifest 列表docker buildx imagetools inspect old-registry.example.com/team/app:v1.0输出结果里会清楚列出每个平台对应的 digest以及该 index 中引用的 manifest。确认源镜像没问题后你可以选择直接使用imagetools create的方式构造目标镜像。具体来说我会先解析出各平台的 digest然后按 digest 直接创建新 indexdocker buildx imagetools create \ --tag new-registry.example.com/team/app:v1.0 \ old-registry.example.com/team/appsha256:amd64-digest \ old-registry.example.com/team/appsha256:arm64-digest \ old-registry.example.com/team/appsha256:armv7-digest这种方式本质上是“复用原 manifest 层”做一次转发不需要重复上传 layer只要你推送到目标仓库时对应的 registry 支持和源仓库之间的 digest 互通。可惜的是大多数时候目标仓库无法直接引用源仓库的 digest因为 registry 之间默认不共享 blob。所以实际大部分场景还要走本地中转。3.3 本地中转迁移的完整链路本地中转的基本思路是先拉取多架构镜像的 manifest 列表然后通过--platform参数把每个平台镜像 pull 下来重新 tag 后 push 到新仓库再用imagetools create合并到一起。以迁移old.at.com/app/web:v1到new.b.com/app/web:v1为例docker pull --platform linux/amd64 old.at.com/app/web:v1 docker tag old.at.com/app/web:v1 new.b.com/app/web:tmp-amd64 docker push new.b.com/app/web:tmp-amd64 docker pull --platform linux/arm64 old.at.com/app/web:v1 docker tag old.at.com/app/web:v1 new.b.com/app/web:tmp-arm64 docker push new.b.com/app/web:tmp-arm64 docker buildx imagetools create \ --tag new.b.com/app/web:v1 \ new.b.com/app/web:tmp-amd64 \ new.b.com/app/web:tmp-arm64完成之后把临时 tag 清理掉docker rmi old.at.com/app/web:v1 docker rmi new.b.com/app/web:tmp-amd64 docker rmi new.b.com/app/web:tmp-arm64但这里有个问题docker pull --platform之后本地镜像的 manifest 依然是单平台的直接 push 到新仓库就是单平台镜像。所以我用imagetools create把它们合并回一个 index这很关键。还有一个更聪明的做法pull 时不要加--platform它会拉取整个 manifest list但在本地 docker driver 下它只会把当前平台镜像解包其他平台的 manifest 依然保留在本地 store 中这样反而方便后续重新 tag 和 push。具体来说就是docker pull old.at.com/app/web:v1 docker tag old.at.com/app/web:v1 new.b.com/app/web:v1 docker push new.b.com/app/web:v1这种情况下push 的其实是完整的 manifest list 吗在 Docker 较老版本中并不一定由于本地存储对多平台元数据的保留策略不同容易出现 push 上去的还是单架构。所以我更推荐明确使用buildx imagetools链路至少在关键场景下不要依赖默认行为。3.4 多架构镜像重新构建迁移方案如果镜像需要改东西比如换掉入口脚本、调整环境变量那就不能只做 manifest 合并必须走“构建推送”。这个场景用 buildx 一条命令就能完成。以构建并推送多架构镜像为例docker buildx build \ --platform linux/amd64,linux/arm64,linux/arm/v7 \ --tag new.b.com/app/web:v2.0 \ --push \ -f ./Dockerfile .这里有几个需要理解的点。--platform后面的列表不是漂亮话它指定了实际构建的每套目标平台。buildx 会针对每个平台分别拉取各自的 base 镜像、分别执行指令。虽然每个平台跑的命令相同但如果 Dockerfile 里用了RUN并且安装包有架构相关差异那每个平台的 layer 是完全独立的不会互相覆盖。--push会直接在构建结束后把整个 index push 到目标仓库。如果你是第一次接触 buildx可能会遇到构建进程卡住多半是网络原因导致构建节点无法拉取 base 镜像。这里我建议给 builder 设置上游 DNS 或者用镜像加速。但注意不要引到任何敏感技术的思路只提常规网络配置即可。3.5 批量化迁移脚本的设计思路一个仓库可能包含几十甚至几百个镜像手动处理不现实。我通常会在迁移前生成一份镜像清单保存为images.txt格式如下app/web:v1 app/api:v2 lib/base:v3然后写一个 bash 脚本循环处理。脚本的核心逻辑包含阶段标记文件和错误重试确保中断后可以续跑。脚本示例如下#!/bin/bash SRCold.at.com DSTnew.b.com IMAGES_FILEimages.txt FAILED_FILEfailed.txt while IFS read -r img; do echo migrate $img # pull 全平台 docker pull $SRC/$img || { echo $img pull failed $FAILED_FILE; continue; } # tag 到新仓库 docker tag $SRC/$img $DST/$img || { echo $img tag failed $FAILED_FILE; continue; } # push docker push $DST/$img || { echo $img push failed $FAILED_FILE; continue; } echo $img done migrated.log done $IMAGES_FILE但注意这段脚本只适用于那种“源仓库本来就有完整 manifest list并且 Docker 默认 push 会保留 manifest list 元数据”的情况。更稳妥的批处理方式是结合docker buildx imagetools先把每个平台镜像 push 上去再 create index。不过那个流程复杂得多我倾向于在脚本里区分两类操作A 类纯 index 转发直接用imagetools。B 类单平台逐推再用imagetools合并。自动化程度高之后验证环节也必须跟上。我迁移完一批镜像就会随手跑一个平台列表校验命令docker buildx imagetools inspect new.b.com/app/web:v1看到输出里包含 linux/amd64 和 linux/arm64甚至 linux/arm/v7我才放心地把旧仓库镜像清掉。4. 常见问题与排查技巧实录迁移过程中会遇到各种问题我整理了一些最典型、最磨人的希望你能少走弯路。4.1 平台不匹配导致拉取失败一条报错信息“no matching manifest for linux/amd64 in the manifest list entries”。这种报错在迁移后特别常见意味着你的目标 index 里没有对应平台。原因大概率是合并 manifest 时少加了某个架构 digest或者源镜像本身就是单架构。排查思路先确认源镜像里到底有哪些平台再确认你imagetools create时引用的 digest 是否来自同一份镜像而不是误用了旧 digest。还有一种非常隐蔽的情况你在 Dockerfile 里用了FROM --platform$BUILDPLATFORM这种写法构建时会动态变化平台但实际输出镜像的平台集合却不是你希望的。这时候建议先buildx imagetools inspect确认构建产物再针对性修改。4.2 认证与权限导致的 push 失败最典型的是“denied: requested access to the resource is denied”。这种问题通常不是 buildx 的问题而是 push 目标的命名空间权限没配好。我遇到过几次同一个账号在旧仓库是管理员在新仓库却只有只读权限结果 pull 没问题、push 不行。排查看三点一是本地 Docker config 里是否同时存在多个仓库的 credential是否因为 key 顺序被覆盖二是目标仓库名中 namespace 是否拼写正确三是网络代理是否干扰了 registry 请求。很多手动屏蔽或限制场景里你可能还需要把 Docker daemon 配上--insecure-registry但这里不展开你自己按实际环境处理即可。4.3 磁盘空间不足与缓存膨胀迁移大批量镜像时本地 Docker store 很容易被撑爆。因为你要拉多个平台镜像每个平台镜像都会占全部的包体。比如一个应用镜像 200MB三个平台就是 600MB如果有一百个镜像就是几十 GB。一个很好的解决方案是使用buildx imagetools直连复制不落盘做不到的就合理规划批量大小分批次加载和清理。我在脚本里会实时清理docker rmi $(docker images -f danglingtrue -q)但注意不要误删还在使用的镜像。另外buildkit 的构建缓存目录也可能膨胀很快。用docker-containerdriver 时缓存默认存放在容器里容器停止后缓存可能残留占用宿主磁盘。我通常会在迁移任务结束后做一次干净的清理docker buildx prune docker builder prune -af4.4 Manifest 合并后的 digest 引用错误使用imagetools create时最常见的坑是 tag 了错误的 manifest。比如你从旧仓库拉了两个平台镜像重新 push 到新仓库时 tag 名写成了两个不同的临时 tag结果 create 后新 index 里的 digest 指向的是本地镜像的 digest而本地镜像是基于旧仓库的原始 digest。这个过程没问题怕的是你 create 后再次 push 的时候两个临时 tag 还在本地残留下次构建改动后 digest 就变了导致 index 中记录的 digest 已经不存在。解决办法create 之后立刻校验并且脚本里做好临时 tag 的清理。不要依赖手工记忆一定要自动化记录 digest。4.5 网络抖动导致 push 中断大批量推送镜像最怕的就是传到一半连接断开。buildx 本身没有断点续传但 Docker push 的 blob 上传会在 registry 内部做去重校验如果 push 失败重跑已经上传的部分 layer 会直接跳过。所以遇到网络问题时最简单的策略就是“重跑脚本”。为了让重跑更高效我会用failed.txt收集失败镜像只漂移重试失败的。另外如果你的 pod 或机器内存不够并发 push 会导致 Docker 守护进程达到资源上限我建议并发数控制在 2 到 3 个以内。你可以用 xargs 控制并发cat images.txt | xargs -P 3 -I {} bash migrate_one.sh {}但注意这里一定要在migrate_one.sh内部进行失败重试并且在脚本开头设置短期锁避免两个进程同时 push 同一个镜像引发 manifest 冲突。5. 验证与收尾检查迁移不能只说“推完了”就算完验证是最重要的环节。我在每次迁移完成后会有一个固定的检查清单按照这个清单逐步确认才能放心切换流量。第一全局扫一遍目标仓库是否真的有多架构 index。你不可能手动检查几百个镜像所以要用脚本批量验证。我写过一个很简单的校验脚本核心是拿镜像名逐个跑imagetools inspect然后 grep 一下是否有期望的平台。echo checking platform list... for img in $(cat images.txt); do echo --- $img --- docker buildx imagetools inspect new.b.com/$img | grep -E Platform:|linux/ done第二随机抽几个镜像做实际的跨架构拉取测试。找一台 ARM64 服务器直接docker pull new.b.com/app/web:v1确认能正常拉取并运行uname -m能回显到目标架构就说明 index 结构没坏。这个测试虽然不能覆盖所有镜像但能暴露通用的配置错误。第三确认旧仓库中不再有流量引用。迁移完成后如果旧仓库要下线必须和业务方沟通特别是那些写死 tag 的第三方服务不会自动跟踪新仓库。所以我习惯在业务流量切换后再保留旧仓库一段时间而不是迁移完立刻清空。6. 实操心得与扩展建议最后分享一点我自己实际控制迁移过程中的体会。用 buildx 做多架构仓库迁移本质上不只是“复制镜像”的技术活还是一个工程化和流程化的问题。你可能面对几十个甚至上百个镜像如果每一步都手动执行很容易出错且效率极低。所以我特别建议你从头就想着写脚本、留日志、做校验哪怕只是最简单的一套 bash 脚本都能救你于水火。关于buildx imagetools这一招我再强调一句它的诞生本来就是为了让你不需要依赖“本地完整拉取”。能直接基于 registry 做迁移的场景尽量别走本地中转省时省力。当然你要是对 OCI 和 Docker 的 registry API 很熟悉还能自己写脚本调/v2/接口做上层迁移但那更适合追求极致自动化的团队一般中小规模用 buildx 就够了。最后一个细节很多人容易忽略多架构镜像迁移后建议顺手更新一下镜像的annotations或者oci元数据避免某些平台在自动回滚时找不到对应 manifest 的备注信息。虽然不影响功能但确实能提升可维护性。总的来说buildx 就是你做多架构镜像迁移的最佳伙伴。把 manifest list 理解透把 imagetools 用熟把脚本和验证逻辑做扎实迁移过程会非常顺。我这个流程在多个迁移项目里都验证过最大的价值就是“可重复、可观测、防呆”。希望这份实战笔记能帮你少踩几个坑一次迁移成功。
1. 迁移场景与整体方案设计做镜像仓库迁移这件事通常不是“把文件拷过去”那么简单。尤其是当你的镜像已经不是单个平台镜像而是一整套多架构 manifest 列表的时候直接docker pull再docker push就有大坑。我在这类迁移上踩过不少坑今天就把用 Docker buildx 完成多架构镜像仓库迁移的完整思路、实操步骤还有排查经验一次说清。先说清楚核心场景。假设你原来有一套镜像中心可能是自建的、也可能是某个云厂商提供的镜像仓库现在因为成本、容量、安全策略或者统一管理需求要把里面的镜像整体搬到另一个仓库。更麻烦的是你的镜像不是单一 amd64 架构而是同时支持 x86_64、ARM64甚至还有 ARMv7比如常见的linux/amd64、linux/arm64、linux/arm/v7。这种情况下如果直接用docker pull某平台镜像再docker tag和docker push你会发现你迁移过去的只是当前平台的单架构镜像整个多架构 manifest 列表丢了。那些拿到 arm64 设备上拉取镜像的用户会直接拉到 amd64 版本运行直接报 exec format error。所以迁移多架构镜像的关键是保留 manifest list 结构。而 Docker buildx 恰好是处理这种场景的核心工具。它的真正价值不只是“跨平台构建”而是围绕 multi-platform 镜像的完整生命周期包括构建、合并、推送。换句话说buildx 不只是拿来build的它是你操作多架构镜像的瑞士军刀。在迁移这条路上我一般会先给方案做一次“体检”。你需要先理清几个问题源仓库里有多少个镜像每个镜像的 namespace 和 tag 结构是什么。这些镜像是原本就带多架构 manifest还是只有单架构。目标仓库是否开放了 OCI 规范的相关接口比如是否支持 manifest list 的 push。是否有海外环境、认证体系、网络带宽限制等外部约束。把这些搞清楚之后再决定迁移策略。我实际使用下来有三条比较成熟的路线如果原镜像本身就是多架构 manifest 列表且你只想迁移而不做任何改动那优先用buildx提供的--platform参数配合imagetools子命令来完成。这是最稳、最快、最不破坏原结构的方式。如果你希望迁移的同时替换基础镜像、调整环境变量、换掉启动命令那就要重新构建。这种情况下docker buildx build --platform是首选因为一条命令就能构建多平台并推送到新仓库。如果源仓库里既有单架构镜像、又有多架构镜像混合在一起那建议先做清单扫描按类型分流再分别处理。我个人的习惯是不管哪种路线迁移之前先在本地写好一份镜像清单包括仓名、标签、平台列表、大小既方便核对也方便后续写脚本批量执行。你千万别嫌这一步麻烦很多迁移失败都发生在“我以为我都知道了”的状态下。2. 核心概念拆解buildx 到底做了什么很多人以为docker buildx只是docker build的升级版会更快。这话只对了一半。buildx 的核心革新在于它把 “构建” 和 “打包” 解耦了。它通过 Builder 实例来管理构建环境可以用 docker driver也可以用 kubernetes driver甚至可以用远程节点。而真正迁移多架构镜像时我们依赖的是其中几个关键能力。2.1 多架构镜像与 manifest list 的核心逻辑在深入命令之前先讲清楚 manifest 这个概念。普通单架构镜像就是一个 manifest 文件加一堆 layer。多架构镜像则是一个 manifest list也叫 Image Index里面记录了一组架构, manifest的映射关系。当客户端去拉取镜像时会根据当前平台自动选择对应的 manifest再拉取相应的 layer。如果你迁移的时候把 manifest list 拆散了只 push 了一个平台那就等于把多架构支持给砍了。更麻烦的是如果源仓库里的镜像格式是 Docker Schema 2目标仓库却只支持 OCI 格式push 的时候还容易遇到格式兼容问题。buildx 内部对于 manifest 的处理非常聪明它并不需要你在本地完整下载所有架构的镜像才可以 push。它可以基于 registry 之间的跨仓库迁移能力或者直接通过imagetools子命令操作远程 manifest做到只复制元数据就可以完成迁移。2.2 buildx 构建器类型选择的关键权衡docker buildx默认会创建一个 builder但其实它底层是经典的 docker driver。docker driver 不支持多平台构建构建 arm64 镜像时会在模拟环境里跑性能差。真正要用的往往是docker-containerdriver。这个 driver 会在本地启动一个 buildkit 容器支持多平台并发构建也支持本地缓存。如果你要迁移的镜像基本都是现成的不需要重新构建那其实不需要很重型的 builder。但如果你要走“重新构建再迁移”这条路那我强烈建议你创建一个docker-containerdriver并把缓存目录挂载到宿主机。这样不仅构建速度快后期迭代也方便。创建方式如下在我实际操作中会先查看现有 builder再创建专用 builderdocker buildx ls docker buildx create --name multiarch-builder --driver docker-container --use docker buildx inspect --bootstrap指定挂载缓存目录的话可以加--driver-opt参数但注意不同版本的 buildx 支持的 driver-opt 略有差异。我一般会在规模较大的迁移场景里加上这个docker buildx create --name multiarch-builder --driver docker-container \ --driver-opt networkhost \ --buildkitd-config /etc/buildkitd.toml其实这个 builder 的生命周期管理也是坑点之一。你要是用临时容器做迁移完成后记得docker buildx rm避免残留 builder 占用磁盘或端口。2.3 imagetools 是迁移的秘密武器docker buildx imagetools是很多人容易忽略的子命令但它对镜像迁移来说非常关键。它可以像操作本地镜像一样直接操作远程仓库中的 manifest 列表。最常用的三个操作docker buildx imagetools inspect image查看远程镜像的 manifest 信息包括平台列表和架构详情。docker buildx imagetools create将多个单平台镜像合并为一个多平台镜像。docker buildx imagetools push把本地构建的 index 推送到远程。在迁移场景里我经常先用inspect确认源镜像的平台列表再用create构建一个新的 manifest list 直接推送到目标仓库整个过程完全不需要在本地落盘任何完整的镜像层。这个方法尤其适合那种“原仓库镜像已经按照单平台拆分存放目标仓库想要一个多平台镜像”的情况。3. 实操过程与核心环节实现下面进入完整实操环节。我以“从旧仓库 A 迁移到新仓库 B镜像都带多架构 manifest”为例用最通用、最好复现的步骤来讲。3.1 环境准备与登录配置迁移前先确认两个仓库的登录权限。很多迁移卡在认证尤其是目标仓库带有特定前缀的时候容易因为 docker config 里的多个 credentials 相互覆盖导致 push 失败。确保 Docker CLI 和 buildx 插件都是较新版本docker --version docker buildx version登录源仓库和目标仓库docker login old-registry.example.com docker login new-registry.example.com如果你用的是云厂商提供的临时凭证务必确认凭证是否在有效期内且 notary 或签名校验相关的配置不会干扰正常 push。有些私有仓库开了内容信任Docker Content Trust迁移时需要显式跳过签名校验否则 push 会报“未签名”错误。这种场景下我一般会加环境变量规避export DOCKER_CONTENT_TRUST03.2 用 imagetools 直连迁移现有 manifest如果你的源镜像已经是多架构镜像且没有内容改造需求最稳的是直接复制 index 和 manifest。这里有一个非常实用的技巧先用 imagetools inspect 看你是否能直接从远程读取源仓库的 manifest 列表docker buildx imagetools inspect old-registry.example.com/team/app:v1.0输出结果里会清楚列出每个平台对应的 digest以及该 index 中引用的 manifest。确认源镜像没问题后你可以选择直接使用imagetools create的方式构造目标镜像。具体来说我会先解析出各平台的 digest然后按 digest 直接创建新 indexdocker buildx imagetools create \ --tag new-registry.example.com/team/app:v1.0 \ old-registry.example.com/team/appsha256:amd64-digest \ old-registry.example.com/team/appsha256:arm64-digest \ old-registry.example.com/team/appsha256:armv7-digest这种方式本质上是“复用原 manifest 层”做一次转发不需要重复上传 layer只要你推送到目标仓库时对应的 registry 支持和源仓库之间的 digest 互通。可惜的是大多数时候目标仓库无法直接引用源仓库的 digest因为 registry 之间默认不共享 blob。所以实际大部分场景还要走本地中转。3.3 本地中转迁移的完整链路本地中转的基本思路是先拉取多架构镜像的 manifest 列表然后通过--platform参数把每个平台镜像 pull 下来重新 tag 后 push 到新仓库再用imagetools create合并到一起。以迁移old.at.com/app/web:v1到new.b.com/app/web:v1为例docker pull --platform linux/amd64 old.at.com/app/web:v1 docker tag old.at.com/app/web:v1 new.b.com/app/web:tmp-amd64 docker push new.b.com/app/web:tmp-amd64 docker pull --platform linux/arm64 old.at.com/app/web:v1 docker tag old.at.com/app/web:v1 new.b.com/app/web:tmp-arm64 docker push new.b.com/app/web:tmp-arm64 docker buildx imagetools create \ --tag new.b.com/app/web:v1 \ new.b.com/app/web:tmp-amd64 \ new.b.com/app/web:tmp-arm64完成之后把临时 tag 清理掉docker rmi old.at.com/app/web:v1 docker rmi new.b.com/app/web:tmp-amd64 docker rmi new.b.com/app/web:tmp-arm64但这里有个问题docker pull --platform之后本地镜像的 manifest 依然是单平台的直接 push 到新仓库就是单平台镜像。所以我用imagetools create把它们合并回一个 index这很关键。还有一个更聪明的做法pull 时不要加--platform它会拉取整个 manifest list但在本地 docker driver 下它只会把当前平台镜像解包其他平台的 manifest 依然保留在本地 store 中这样反而方便后续重新 tag 和 push。具体来说就是docker pull old.at.com/app/web:v1 docker tag old.at.com/app/web:v1 new.b.com/app/web:v1 docker push new.b.com/app/web:v1这种情况下push 的其实是完整的 manifest list 吗在 Docker 较老版本中并不一定由于本地存储对多平台元数据的保留策略不同容易出现 push 上去的还是单架构。所以我更推荐明确使用buildx imagetools链路至少在关键场景下不要依赖默认行为。3.4 多架构镜像重新构建迁移方案如果镜像需要改东西比如换掉入口脚本、调整环境变量那就不能只做 manifest 合并必须走“构建推送”。这个场景用 buildx 一条命令就能完成。以构建并推送多架构镜像为例docker buildx build \ --platform linux/amd64,linux/arm64,linux/arm/v7 \ --tag new.b.com/app/web:v2.0 \ --push \ -f ./Dockerfile .这里有几个需要理解的点。--platform后面的列表不是漂亮话它指定了实际构建的每套目标平台。buildx 会针对每个平台分别拉取各自的 base 镜像、分别执行指令。虽然每个平台跑的命令相同但如果 Dockerfile 里用了RUN并且安装包有架构相关差异那每个平台的 layer 是完全独立的不会互相覆盖。--push会直接在构建结束后把整个 index push 到目标仓库。如果你是第一次接触 buildx可能会遇到构建进程卡住多半是网络原因导致构建节点无法拉取 base 镜像。这里我建议给 builder 设置上游 DNS 或者用镜像加速。但注意不要引到任何敏感技术的思路只提常规网络配置即可。3.5 批量化迁移脚本的设计思路一个仓库可能包含几十甚至几百个镜像手动处理不现实。我通常会在迁移前生成一份镜像清单保存为images.txt格式如下app/web:v1 app/api:v2 lib/base:v3然后写一个 bash 脚本循环处理。脚本的核心逻辑包含阶段标记文件和错误重试确保中断后可以续跑。脚本示例如下#!/bin/bash SRCold.at.com DSTnew.b.com IMAGES_FILEimages.txt FAILED_FILEfailed.txt while IFS read -r img; do echo migrate $img # pull 全平台 docker pull $SRC/$img || { echo $img pull failed $FAILED_FILE; continue; } # tag 到新仓库 docker tag $SRC/$img $DST/$img || { echo $img tag failed $FAILED_FILE; continue; } # push docker push $DST/$img || { echo $img push failed $FAILED_FILE; continue; } echo $img done migrated.log done $IMAGES_FILE但注意这段脚本只适用于那种“源仓库本来就有完整 manifest list并且 Docker 默认 push 会保留 manifest list 元数据”的情况。更稳妥的批处理方式是结合docker buildx imagetools先把每个平台镜像 push 上去再 create index。不过那个流程复杂得多我倾向于在脚本里区分两类操作A 类纯 index 转发直接用imagetools。B 类单平台逐推再用imagetools合并。自动化程度高之后验证环节也必须跟上。我迁移完一批镜像就会随手跑一个平台列表校验命令docker buildx imagetools inspect new.b.com/app/web:v1看到输出里包含 linux/amd64 和 linux/arm64甚至 linux/arm/v7我才放心地把旧仓库镜像清掉。4. 常见问题与排查技巧实录迁移过程中会遇到各种问题我整理了一些最典型、最磨人的希望你能少走弯路。4.1 平台不匹配导致拉取失败一条报错信息“no matching manifest for linux/amd64 in the manifest list entries”。这种报错在迁移后特别常见意味着你的目标 index 里没有对应平台。原因大概率是合并 manifest 时少加了某个架构 digest或者源镜像本身就是单架构。排查思路先确认源镜像里到底有哪些平台再确认你imagetools create时引用的 digest 是否来自同一份镜像而不是误用了旧 digest。还有一种非常隐蔽的情况你在 Dockerfile 里用了FROM --platform$BUILDPLATFORM这种写法构建时会动态变化平台但实际输出镜像的平台集合却不是你希望的。这时候建议先buildx imagetools inspect确认构建产物再针对性修改。4.2 认证与权限导致的 push 失败最典型的是“denied: requested access to the resource is denied”。这种问题通常不是 buildx 的问题而是 push 目标的命名空间权限没配好。我遇到过几次同一个账号在旧仓库是管理员在新仓库却只有只读权限结果 pull 没问题、push 不行。排查看三点一是本地 Docker config 里是否同时存在多个仓库的 credential是否因为 key 顺序被覆盖二是目标仓库名中 namespace 是否拼写正确三是网络代理是否干扰了 registry 请求。很多手动屏蔽或限制场景里你可能还需要把 Docker daemon 配上--insecure-registry但这里不展开你自己按实际环境处理即可。4.3 磁盘空间不足与缓存膨胀迁移大批量镜像时本地 Docker store 很容易被撑爆。因为你要拉多个平台镜像每个平台镜像都会占全部的包体。比如一个应用镜像 200MB三个平台就是 600MB如果有一百个镜像就是几十 GB。一个很好的解决方案是使用buildx imagetools直连复制不落盘做不到的就合理规划批量大小分批次加载和清理。我在脚本里会实时清理docker rmi $(docker images -f danglingtrue -q)但注意不要误删还在使用的镜像。另外buildkit 的构建缓存目录也可能膨胀很快。用docker-containerdriver 时缓存默认存放在容器里容器停止后缓存可能残留占用宿主磁盘。我通常会在迁移任务结束后做一次干净的清理docker buildx prune docker builder prune -af4.4 Manifest 合并后的 digest 引用错误使用imagetools create时最常见的坑是 tag 了错误的 manifest。比如你从旧仓库拉了两个平台镜像重新 push 到新仓库时 tag 名写成了两个不同的临时 tag结果 create 后新 index 里的 digest 指向的是本地镜像的 digest而本地镜像是基于旧仓库的原始 digest。这个过程没问题怕的是你 create 后再次 push 的时候两个临时 tag 还在本地残留下次构建改动后 digest 就变了导致 index 中记录的 digest 已经不存在。解决办法create 之后立刻校验并且脚本里做好临时 tag 的清理。不要依赖手工记忆一定要自动化记录 digest。4.5 网络抖动导致 push 中断大批量推送镜像最怕的就是传到一半连接断开。buildx 本身没有断点续传但 Docker push 的 blob 上传会在 registry 内部做去重校验如果 push 失败重跑已经上传的部分 layer 会直接跳过。所以遇到网络问题时最简单的策略就是“重跑脚本”。为了让重跑更高效我会用failed.txt收集失败镜像只漂移重试失败的。另外如果你的 pod 或机器内存不够并发 push 会导致 Docker 守护进程达到资源上限我建议并发数控制在 2 到 3 个以内。你可以用 xargs 控制并发cat images.txt | xargs -P 3 -I {} bash migrate_one.sh {}但注意这里一定要在migrate_one.sh内部进行失败重试并且在脚本开头设置短期锁避免两个进程同时 push 同一个镜像引发 manifest 冲突。5. 验证与收尾检查迁移不能只说“推完了”就算完验证是最重要的环节。我在每次迁移完成后会有一个固定的检查清单按照这个清单逐步确认才能放心切换流量。第一全局扫一遍目标仓库是否真的有多架构 index。你不可能手动检查几百个镜像所以要用脚本批量验证。我写过一个很简单的校验脚本核心是拿镜像名逐个跑imagetools inspect然后 grep 一下是否有期望的平台。echo checking platform list... for img in $(cat images.txt); do echo --- $img --- docker buildx imagetools inspect new.b.com/$img | grep -E Platform:|linux/ done第二随机抽几个镜像做实际的跨架构拉取测试。找一台 ARM64 服务器直接docker pull new.b.com/app/web:v1确认能正常拉取并运行uname -m能回显到目标架构就说明 index 结构没坏。这个测试虽然不能覆盖所有镜像但能暴露通用的配置错误。第三确认旧仓库中不再有流量引用。迁移完成后如果旧仓库要下线必须和业务方沟通特别是那些写死 tag 的第三方服务不会自动跟踪新仓库。所以我习惯在业务流量切换后再保留旧仓库一段时间而不是迁移完立刻清空。6. 实操心得与扩展建议最后分享一点我自己实际控制迁移过程中的体会。用 buildx 做多架构仓库迁移本质上不只是“复制镜像”的技术活还是一个工程化和流程化的问题。你可能面对几十个甚至上百个镜像如果每一步都手动执行很容易出错且效率极低。所以我特别建议你从头就想着写脚本、留日志、做校验哪怕只是最简单的一套 bash 脚本都能救你于水火。关于buildx imagetools这一招我再强调一句它的诞生本来就是为了让你不需要依赖“本地完整拉取”。能直接基于 registry 做迁移的场景尽量别走本地中转省时省力。当然你要是对 OCI 和 Docker 的 registry API 很熟悉还能自己写脚本调/v2/接口做上层迁移但那更适合追求极致自动化的团队一般中小规模用 buildx 就够了。最后一个细节很多人容易忽略多架构镜像迁移后建议顺手更新一下镜像的annotations或者oci元数据避免某些平台在自动回滚时找不到对应 manifest 的备注信息。虽然不影响功能但确实能提升可维护性。总的来说buildx 就是你做多架构镜像迁移的最佳伙伴。把 manifest list 理解透把 imagetools 用熟把脚本和验证逻辑做扎实迁移过程会非常顺。我这个流程在多个迁移项目里都验证过最大的价值就是“可重复、可观测、防呆”。希望这份实战笔记能帮你少踩几个坑一次迁移成功。
