1. 为什么多架构镜像成为刚需
我开始做多架构镜像这件事,起因很实际:公司的生产环境里既有 x86 的 Intel/AMD 服务器,后来又上了一批 ARM 的鲲鹏、飞腾机器,团队里还有一堆用 Apple Silicon 笔记本的同事,客户那边偶尔还要部署到树莓派上。一开始我图省事,各个架构单独打镜像,tag 后面再挂个 -amd64、-arm64 的后缀,结果维护起来非常痛苦。做一个版本要构建三四个镜像,Dockerfile 里还得写一堆平台分支判断,发布脚本越来越长,偶尔还出现忘记推送某个架构镜像导致线上拉取失败的尴尬。
后来我把这套流程整体切换到 Docker Buildx 多架构构建方案,一份 Dockerfile 跑一次构建,就能同时产出 amd64、arm64 等多个平台的镜像,并且通过 Manifest List(镜像索引)合并成一个 tag 推到仓库里。用户在任意架构的机器上执行 docker pull,Docker 会自动拉取对应架构的镜像层,完全不需要手动区分。这套方案解决的核心问题就是:用最低的维护成本,让同一个镜像在任何 CPU 架构上都能开箱即用。
这篇文章我会把这套方案的完整落地过程写出来,包括原理、环境准备、具体命令、Dockerfile 写法、CI 集成、缓存加速,最后附上我实际踩过的坑和排查思路。适合正在做多架构交付、或者刚开始接触 Buildx 的开发和运维同学参考。
1.1 当前主流 CPU 架构的分布情况
在规划多架构方案之前,先得清楚我们要覆盖哪些架构。目前最常见的几个目标平台是:
- linux/amd64:绝大多数 x86 服务器、云主机、传统 PC 服务器,装机量最大,是默认的第一平台。
- linux/arm64:ARM 架构的 64 位服务器,比如华为鲲鹏、AWS Graviton、Ampere Altra,以及苹果 M 系列芯片的 Linux 虚拟机。云厂商近年来大量提供这类实例,性价比优势明显。
- linux/arm/v7:树莓派 2/3、大量 ARM 开发板、部分 NAS 设备,虽然性能弱但存量很大,很多边缘计算场景还在用它。
- linux/arm/v6:树莓派 1 代、Zero 等更老的设备,相对小众,视业务情况决定是否需要。
- linux/ppc64le、linux/s390x、linux/riscv64:Power 服务器、IBM Z、RISC-V 等小众架构,一般只有特定行业才会用到,通常是在基础设施类镜像中才会覆盖。
做方案时我建议分两步走:第一优先级永远先覆盖 linux/amd64 和 linux/arm64,这两者覆盖了 90% 以上的需求;如果业务确实涉及边缘设备,再把 arm/v7 加进来。架构覆盖越多,构建时间越长,QEMU 模拟的性能瓶颈越明显,所以不要一上来就贪全。对我们团队的实际运维状况而言,容器化已经是标准交付方式了,镜像如果只能跑在 x86 上,后续无论是要迁移到 ARM 云主机,还是支持本地 Mac 开发调试,都会非常被动。
1.2 Manifest List 与镜像索引的原理
很多人第一次看到多架构镜像时会有疑问:Docker 是怎么做到一个 tag 对应多个架构的?背后的关键就是 Manifest List,在 OCI 规范里叫 Image Index。
普通单架构镜像的结构是:仓库 tag 指向一个 Manifest,Manifest 里描述了一层层的镜像层和配置信息。而多架构镜像的结构是多了一层索引:tag 指向的不是某个具体的 Manifest,而是一个 Manifest List,列表里记录了每个平台架构对应的 Manifest 引用及其摘要(digest)。当你在某台机器上执行 docker pull 时,Docker 客户端会把自己当前运行时的 os/arch(比如 linux/arm64)发到仓库服务端,服务端从 Manifest List 里找到匹配项,返回对应的 Manifest,然后客户端再按这个 Manifest 去拉取镜像层。
理解这个机制后,很多问题就迎刃而解了:
- 为什么我在 x86 机器上拉多架构镜像,实际下载的层还是 amd64 的?因为客户端自动选择了对应平台的层,其它架构的层不会被下载。
- 为什么有些比较老的镜像仓库工具显示的信息不完整?因为有些工具不支持 OCI Image Index 这种新格式,需要升级或开启实验特性。
- 为什么不能用
docker tag简单地把两个架构的镜像合并?因为 Manifest List 必须由 Buildx 或docker manifest命令创建,普通 tag 操作不涉及这个层面的元数据。
另外要注意,Manifest List 不是把两个镜像简单打包在一起,而是对每个架构单独构建镜像,然后把它们的引用和平台信息记录到索引里。所以多架构构建的本质是先构建多个架构的真实镜像,最后再合并索引。
1.3 三种常见多架构构建方案的取舍
我调研和实际试过的方案大体有三种,各有适用场景:
方案一:使用 Buildx + QEMU 用户态模拟构建。 这是目前最主流、维护成本最低的方式。在构建机上注册 QEMU 的 binfmt 处理器,让 BuildKit 在需要执行 arm64 程序时自动通过模拟器运行。好处是只需要一台机器就能构建所有平台镜像,缺点是 arm64 等非本机架构的构建速度明显偏慢,尤其是编译型语言和安装大量软件包时。
方案二:多台原生架构构建机组成构建矩阵。 比如我在公司内部就见过有的团队准备了两套环境,x86 机器上构建 amd64 镜像,ARM 机器上构建 arm64 镜像,最后再把索引合并。优点是每台机器都是原生速度,构建效率高,缺点是要维护多套构建环境,CI 流水线的复杂度会上升,也因此比较适合对构建速度敏感、且基础设施本身就有多架构机器可用的团队。
方案三:在构建脚本里做交叉编译。 比如 Go 语言可以通过设置 GOARCH 和 CGO_ENABLED=0 直接在一个平台上产出其他架构的二进制,然后打进镜像。这个方案构建速度最快,但对语言和编译工具链有严格要求。C/C++ 依赖比较多、或者需要依赖系统原生库的场景就不太适用,Node.js 里带原生模块的场景也会比较麻烦。
从通用性和可维护性角度,我最终选了方案一作为主流程,方案三作为某些特定语言的性能优化手段。这也是绝大多数开源项目在推出的多架构镜像时实际采用的方式,社区验证充分,遇到问题也容易找到参考案例。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与工具链选型
这套方案对环境的要求其实不高,但有几个前置条件必须提前确认好,否则后面构建时会出现各种莫名其妙的错误。我按自己踩坑的顺序来梳理。
2.1 版本要求与 Buildx 插件启用
首先确认 Docker 版本。Buildx 作为 Docker CLI 的插件功能完整可用,一般要求 Docker 20.10 以上,新版本基本开箱即用。如果你本机装的是 Do
