docker buildx 构建多平台镜像工具

安装 buildx

repository 安装

sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

二进制安装

wget https://github.com/docker/buildx/releases/download/v0.27.0/buildx-v0.27.0.linux-amd64

mkdir $HOME/.docker/cli-plugins

mv buildx-v0.27.0.linux-amd64 $HOME/.docker/cli-plugins/docker-buildx && chmod +x $HOME/.docker/cli-plugins/docker-buildx

验证 buildx

docker buildx version

github.com/docker/buildx v0.27.0 bac71def78b077ee6a2607119f88e291861b18ac

Buildx 构建驱动程序

Buildx 配置 Registry mirror

buildkitd.toml 配置文件说明

# debug 启用额外的调试日志记录
debug = true
# trace 启用额外的跟踪日志记录（非常详细，可能影响性能）
trace = true
# root 是存储所有 buildkit 状态的位置
root = "/var/lib/buildkit"
# insecure-entitlements 允许不安全授权，默认禁用
insecure-entitlements = [ "network.host", "security.insecure" ]

[log]
  # 日志格式：json 或 text
  format = "text"

[dns]
  # DNS 名称服务器
  nameservers=["1.1.1.1","8.8.8.8"]
  # DNS 选项
  options=["edns0"]
  # 搜索域
  searchDomains=["example.com"]

[grpc]
  # gRPC 服务地址
  address = [ "tcp://0.0.0.0:1234" ]
  # debugAddress 是附加 Go profiles 和调试器的地址
  debugAddress = "0.0.0.0:6060"
  uid = 0  # 用户 ID
  gid = 0  # 组 ID
  [grpc.tls]
    cert = "/etc/buildkit/tls.crt"  # TLS 证书
    key = "/etc/buildkit/tls.key"   # TLS 密钥
    ca = "/etc/buildkit/tlsca.crt"  # CA 证书

[otel]
  # OTEL 收集器跟踪套接字路径
  socketPath = "/run/buildkit/otel-grpc.sock"

[cdi]
  # 禁用容器设备接口（CDI）支持
  disabled = true
  # CDI 规范文件扫描目录列表
  specDirs = ["/etc/cdi", "/var/run/cdi", "/etc/buildkit/cdi"]

# 构建历史 API 配置，存储已完成构建命令的信息
[history]
  # maxAge 是保留历史条目的最长期限（秒）
  maxAge = 172800  # 48小时
  # maxEntries 是保留的最大历史条目数
  maxEntries = 50

# OCI 工作器配置
[worker.oci]
  enabled = true  # 启用 OCI 工作器
  # platforms 手动配置平台，未设置则自动检测
  platforms = [ "linux/amd64", "linux/arm64" ]
  # 快照器：overlayfs 或 native，默认为 "auto"
  snapshotter = "auto"
  # rootless：是否在 rootless 模式下运行
  rootless = false
  # 是否在主 PID 命名空间中运行子进程
  noProcessSandbox = false

  # gc 启用/禁用垃圾回收
  gc = true
  # reservedSpace 是该工作器保证保留的最小磁盘空间
  reservedSpace = "30%"
  # maxUsedSpace 是该工作器可使用的最大磁盘空间
  maxUsedSpace = "60%"
  # minFreeSpace 是垃圾回收器尝试保留的最小空闲磁盘空间
  minFreeSpace = "20GB"

  # 替代的 OCI 工作器二进制名称
  binary = ""
  # 用于约束构建容器的 AppArmor 配置文件名称
  apparmor-profile = ""
  # 限制可同时运行的并行构建步骤数量
  max-parallelism = 4
  # 维护可重用的 CNI 网络命名空间池的大小
  cniPoolSize = 16

  # 工作器标签
  [worker.oci.labels]
    "foo" = "bar"

  # 垃圾回收策略
  [[worker.oci.gcpolicy]]
    reservedSpace = "512MB"
    maxUsedSpace = "1GB"
    minFreeSpace = "10GB"
    keepDuration = "48h"  # 保留时长
    filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout"]
  
  [[worker.oci.gcpolicy]]
    all = true  # 应用于所有类型
    reservedSpace = 1024000000  # 1024MB

# Containerd 工作器配置
[worker.containerd]
  address = "/run/containerd/containerd.sock"  # Containerd 地址
  enabled = true  # 启用 Containerd 工作器
  platforms = [ "linux/amd64", "linux/arm64" ]
  namespace = "buildkit"  # 命名空间

  # 垃圾回收配置
  gc = true
  reservedSpace = "30%"
  maxUsedSpace = "60%"
  minFreeSpace = "20GB"

  # CNI 网络命名空间池大小
  cniPoolSize = 16
  # 所有容器的默认 cgroup 父级
  defaultCgroupParent = "buildkit"

  # 工作器标签
  [worker.containerd.labels]
    "foo" = "bar"

  # Containerd 运行时配置
  [worker.containerd.runtime]
    name = "io.containerd.runc.v2"  # 运行时名称
    path = "/path/to/containerd/runc/shim"  # 运行时路径
    options = { BinaryName = "runc" }  # 运行时选项

  # 垃圾回收策略
  [[worker.containerd.gcpolicy]]
    reservedSpace = 512000000  # 512MB
    keepDuration = 172800  # 48小时
    filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout"]
  
  [[worker.containerd.gcpolicy]]
    all = true
    reservedSpace = 1024000000  # 1024MB

# 注册表配置用于缓存导入或输出
[registry."docker.io"]
  # 镜像配置（当镜像注册表需要 /project 路径时）
  mirrors = ["yourmirror.local:5000", "core.harbor.domain/proxy.docker.io"]
  # 使用纯 HTTP 连接到镜像
  http = true
  # 使用带自签名证书的 HTTPS（不要与 http 同时启用）
  insecure = true
  ca=["/etc/config/myca.pem"]  # CA 证书路径
  [[registry."docker.io".keypair]]  # 密钥对配置
    key="/etc/config/key.pem"    # 私钥路径
    cert="/etc/config/cert.pem"  # 证书路径

# 可选：通过定义为注册表完成镜像配置
[registry."yourmirror.local:5000"]
  http = true  # 使用 HTTP

# 前端控制
[frontend."dockerfile.v0"]  # Dockerfile 前端
  enabled = true  # 启用

[frontend."gateway.v0"]  # 网关前端
  enabled = true  # 启用
  # 如果 allowedRepositories 为空，则允许所有网关源
  # 否则，仅允许列出的仓库作为网关源
  # 注意：仅比较仓库名称（不含标签）
  allowedRepositories = []  # 允许的仓库列表

[system]
  # BuildKit 扫描支持的模拟平台变化的频率
  platformsCacheMaxAge = "1h"  # 1小时

buildkitd.toml 示例

debug = true
insecure-entitlements = [ "network.host", "security.insecure" ]

[registry."docker.io"]
  mirrors = ["hub.paas:80","hub.paas","192.168.56.101","192.168.56.101:80"]
  http = true

[registry."hub.paas:80"]
  http = true

[registry."hub.paas"]
  http = true

[registry."192.168.56.101"]
  http = true
  
[registry."192.168.56.101:80"]
  http = true

配置 Buildx 使用 QEMU

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

Unable to find image 'multiarch/qemu-user-static:latest' locally
latest: Pulling from multiarch/qemu-user-static
205dae5015e7: Pull complete
816739e52091: Pull complete
30abb83a18eb: Pull complete
0657daef200b: Pull complete
30c9c93f40b9: Pull complete
Digest: sha256:fe60359c92e86a43cc87b3d906006245f77bfc0565676b80004cc666e4feb9f0
Status: Downloaded newer image for multiarch/qemu-user-static:latest
Setting /usr/bin/qemu-alpha-static as binfmt interpreter for alpha
Setting /usr/bin/qemu-arm-static as binfmt interpreter for arm
Setting /usr/bin/qemu-armeb-static as binfmt interpreter for armeb
Setting /usr/bin/qemu-sparc-static as binfmt interpreter for sparc
Setting /usr/bin/qemu-sparc32plus-static as binfmt interpreter for sparc32plus
Setting /usr/bin/qemu-sparc64-static as binfmt interpreter for sparc64
Setting /usr/bin/qemu-ppc-static as binfmt interpreter for ppc
Setting /usr/bin/qemu-ppc64-static as binfmt interpreter for ppc64
Setting /usr/bin/qemu-ppc64le-static as binfmt interpreter for ppc64le
Setting /usr/bin/qemu-m68k-static as binfmt interpreter for m68k
Setting /usr/bin/qemu-mips-static as binfmt interpreter for mips
Setting /usr/bin/qemu-mipsel-static as binfmt interpreter for mipsel
Setting /usr/bin/qemu-mipsn32-static as binfmt interpreter for mipsn32
Setting /usr/bin/qemu-mipsn32el-static as binfmt interpreter for mipsn32el
Setting /usr/bin/qemu-mips64-static as binfmt interpreter for mips64
Setting /usr/bin/qemu-mips64el-static as binfmt interpreter for mips64el
Setting /usr/bin/qemu-sh4-static as binfmt interpreter for sh4
Setting /usr/bin/qemu-sh4eb-static as binfmt interpreter for sh4eb
Setting /usr/bin/qemu-s390x-static as binfmt interpreter for s390x
Setting /usr/bin/qemu-aarch64-static as binfmt interpreter for aarch64
Setting /usr/bin/qemu-aarch64_be-static as binfmt interpreter for aarch64_be
Setting /usr/bin/qemu-hppa-static as binfmt interpreter for hppa
Setting /usr/bin/qemu-riscv32-static as binfmt interpreter for riscv32
Setting /usr/bin/qemu-riscv64-static as binfmt interpreter for riscv64
Setting /usr/bin/qemu-xtensa-static as binfmt interpreter for xtensa
Setting /usr/bin/qemu-xtensaeb-static as binfmt interpreter for xtensaeb
Setting /usr/bin/qemu-microblaze-static as binfmt interpreter for microblaze
Setting /usr/bin/qemu-microblazeel-static as binfmt interpreter for microblazeel
Setting /usr/bin/qemu-or1k-static as binfmt interpreter for or1k
Setting /usr/bin/qemu-hexagon-static as binfmt interpreter for hexagon

使用默认驱动 docker

查看 builder

docker buildx ls

NAME/NODE                DRIVER/ENDPOINT                   STATUS    BUILDKIT   PLATFORMS
default                  docker
 \_ default               \_ default                       running   v0.23.2    linux/amd64 (+3), linux/arm64, linux/arm (+2), linux/ppc64le, (4 more)

使用 Buildx 构建多平台镜像

Dockerfile

# docker pull --platform=linux/arm64 maven:3.9.11-sapmachine-17
FROM maven:3.9.11-sapmachine-17
RUN java -version

构建 arm64 镜像

docker buildx build  --platform linux/arm64 -t wgs-test-maven --builder=default --push .

[+] Building 67.9s (6/6) FINISHED                                                                                                              docker:default
 => [internal] load build definition from Dockerfile                                                                                                     0.0s
 => => transferring dockerfile: 147B                                                                                                                     0.0s
 => [internal] load metadata for docker.io/library/maven:3.9.11-sapmachine-17                                                                            2.2s
 => [internal] load .dockerignore                                                                                                                        0.0s
 => => transferring context: 2B                                                                                                                          0.0s
 => [1/2] FROM docker.io/library/maven:3.9.11-sapmachine-17@sha256:b276372deb8cfc824957e1a98d47224c126aefa6ee27ca1fdf3c2d95d338b3b1                     63.4s
 => => resolve docker.io/library/maven:3.9.11-sapmachine-17@sha256:b276372deb8cfc824957e1a98d47224c126aefa6ee27ca1fdf3c2d95d338b3b1                      0.0s
 => => sha256:49a8ca9a328e179fe07d40f7f2fd5fb2860b5c45463c288b64f05be521173d2e 28.86MB / 28.86MB                                                        15.5s
 => => sha256:01cb87073cab7be62c10d8f4abd3703918c8d54fb38d0426a3e0fd2c2ae8167e 2.31kB / 2.31kB                                                           0.0s
 => => sha256:b8a73935d3cb07838b685d8211788ecf985a8bc2b32297cea174222062ef4256 199.21MB / 199.21MB                                                      57.7s
 => => sha256:ae273cc0ddc64cf958d819f26a345b72479adf653134fa2ac90d5dce7bb6c4ad 25.53MB / 25.53MB                                                         6.6s
 => => sha256:b276372deb8cfc824957e1a98d47224c126aefa6ee27ca1fdf3c2d95d338b3b1 3.92kB / 3.92kB                                                           0.0s
 => => sha256:ef30568fad9d71c536ee83b972612eb6175d8d64e0855715bb74b4fe877ac56b 5.98kB / 5.98kB                                                           0.0s
 => => sha256:bf6ca5d227bec20bf5d3f148eba1853ec3d54903cc2bcdad16a4d8be4a8c67d6 9.24MB / 9.24MB                                                          11.6s
 => => sha256:332c5ec9f0c23701a591ccf3618f85c8a73474dcb2e96f95907e497c102ea25c 852B / 852B                                                              12.2s
 => => sha256:4f4fb700ef54461cfa02571ae0db9a0dc1e0cdb5577484a6d75e68dc38e8acc1 32B / 32B                                                                12.7s
 => => sha256:8cb65c3e2269c5bd4df21fc5fc7fb681da81ce1aef2da39655f72aa93ce746de 154B / 154B                                                              13.2s
 => => extracting sha256:49a8ca9a328e179fe07d40f7f2fd5fb2860b5c45463c288b64f05be521173d2e                                                                2.2s
 => => extracting sha256:b8a73935d3cb07838b685d8211788ecf985a8bc2b32297cea174222062ef4256                                                                3.5s
 => => extracting sha256:ae273cc0ddc64cf958d819f26a345b72479adf653134fa2ac90d5dce7bb6c4ad                                                                1.6s
 => => extracting sha256:bf6ca5d227bec20bf5d3f148eba1853ec3d54903cc2bcdad16a4d8be4a8c67d6                                                                0.2s
 => => extracting sha256:332c5ec9f0c23701a591ccf3618f85c8a73474dcb2e96f95907e497c102ea25c                                                                0.0s
 => => extracting sha256:4f4fb700ef54461cfa02571ae0db9a0dc1e0cdb5577484a6d75e68dc38e8acc1                                                                0.0s
 => => extracting sha256:8cb65c3e2269c5bd4df21fc5fc7fb681da81ce1aef2da39655f72aa93ce746de                                                                0.0s
 => [2/2] RUN java -version                                                                                                                              2.2s
 => exporting to image                                                                                                                                   0.0s
 => => exporting layers                                                                                                                                  0.0s
 => => writing image sha256:11e394c8b1be21c502515da1ba6616e2a5f5e3f91e36ab284d6acc92a8a46475                                                             0.0s
 => => naming to docker.io/library/wgs-test-maven

测试 arm64 平台镜像

docker run --rm -ti wgs-test-maven java -version

WARNING: The requested image's platform (linux/arm64) does not match the detected host platform (linux/amd64/v3) and no specific platform was requested
openjdk version "17.0.16" 2025-07-15 LTS
OpenJDK Runtime Environment SapMachine (build 17.0.16+8-LTS)
OpenJDK 64-Bit Server VM SapMachine (build 17.0.16+8-LTS, mixed mode, sharing)

使用驱动 docker-container

创建并使用构建器

docker buildx create --name container-builder --driver docker-container --buildkitd-config buildkitd.toml --use

container-builder

启动构建器

docker buildx inspect --bootstrap

[+] Building 1.5s (1/1) FINISHED
 => [internal] booting buildkit                                                                                                                          1.5s
 => => pulling image moby/buildkit:buildx-stable-1                                                                                                       1.1s
 => => creating container buildx_buildkit_container-builder0                                                                                             0.4s
Name:          container-builder
Driver:        docker-container
Last Activity: 2025-08-25 08:37:02 +0000 UTC

Nodes:
Name:                  container-builder0
Endpoint:              unix:///var/run/docker.sock
Driver Options:        network="host"
Status:                running
BuildKit daemon flags: --allow-insecure-entitlement=network.host
BuildKit version:      v0.23.2
Platforms:             linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/arm64, linux/riscv64, linux/ppc64, linux/ppc64le, linux/s390x, linux/386, linux/arm/v7, linux/arm/v6
Labels:
 org.mobyproject.buildkit.worker.executor:         oci
 org.mobyproject.buildkit.worker.hostname:         vbox
 org.mobyproject.buildkit.worker.network:          host
 org.mobyproject.buildkit.worker.oci.process-mode: sandbox
 org.mobyproject.buildkit.worker.selinux.enabled:  false
 org.mobyproject.buildkit.worker.snapshotter:      overlayfs
GC Policy rule#0:
 All:            false
 Filters:        type==source.local,type==exec.cachemount,type==source.git.checkout
 Keep Duration:  48h0m0s
 Max Used Space: 488.3MiB
GC Policy rule#1:
 All:            false
 Keep Duration:  1440h0m0s
 Reserved Space: 1.863GiB
 Max Used Space: 13.04GiB
 Min Free Space: 3.725GiB
GC Policy rule#2:
 All:            false
 Reserved Space: 1.863GiB
 Max Used Space: 13.04GiB
 Min Free Space: 3.725GiB
GC Policy rule#3:
 All:            true
 Reserved Space: 1.863GiB
 Max Used Space: 13.04GiB
 Min Free Space: 3.725GiB
 File#buildkitd.toml:
 > debug = true
 > insecure-entitlements = ["network.host", "security.insecure"]
 >
 > [registry]
 >
 >   [registry."docker.io"]
 >     http = true
 >     mirrors = ["hub.paas:80", "hub.paas","192.168.56.101","192.168.56.101:80"]
 >
 >   [registry."hub.paas"]
 >     http = true
 >
 >   [registry."hub.paas:80"]
 >     http = true
 >
 >   [registry."hub.paas"]
 >     http = true
 >
 >   [registry."hub.paas:80"]
 >     http = true
 >
 >   [registry."192.168.56.101"]
 >     http = true
 >
 >   [registry."192.168.56.101:80"]
 >     http = true

验证多平台支持

docker buildx ls

NAME/NODE                DRIVER/ENDPOINT                   STATUS    BUILDKIT   PLATFORMS
container-builder*       docker-container
 \_ container-builder0    \_ unix:///var/run/docker.sock   running   v0.23.2    linux/amd64 (+3), linux/arm64, linux/arm (+2), linux/ppc64le, (4 more)
default                  docker
 \_ default               \_ default                       running   v0.23.2    linux/amd64 (+3), linux/arm64, linux/arm (+2), linux/ppc64le, (4 more)

查看运行的容器

docker ps

CONTAINER ID   IMAGE                           COMMAND                   CREATED          STATUS          PORTS     NAMES
ea19dd7701a6   moby/buildkit:buildx-stable-1   "buildkitd --allow-i…"   49 seconds ago   Up 49 seconds             buildx_buildkit_container-builder0

使用 Buildx 构建多平台镜像

Dockerfile

FROM hub.paas/base/maven:3.9.11-sapmachine-17
RUN java -version

构建多平台镜像

docker buildx build --load --platform linux/arm64 -t hub.paas/base/maven-test-arm64 --push  .

[+] Building 2.2s (9/9) FINISHED                                                                                                    docker-container:container-builder
 => [internal] load build definition from Dockerfile                                                                                                              0.0s
 => => transferring dockerfile: 105B                                                                                                                              0.0s
 => WARN: InvalidBaseImagePlatform: Base image hub.paas/base/maven:3.9.11-sapmachine-17 was pulled with platform "linux/amd64", expected "linux/arm64" for c  0.0s
 => [internal] load metadata for hub.paas/base/maven:3.9.11-sapmachine-17                                                                                     0.1s
 => [internal] load .dockerignore                                                                                                                                 0.0s
 => => transferring context: 2B                                                                                                                                   0.0s
 => [1/2] FROM hub.paas/base/maven:3.9.11-sapmachine-17@sha256:6d4ad00af6aae227118a2e27b641ebf449457c7139e2dd877d66016d6bd57ad3                               0.0s
 => => resolve hub.paas/base/maven:3.9.11-sapmachine-17@sha256:6d4ad00af6aae227118a2e27b641ebf449457c7139e2dd877d66016d6bd57ad3                               0.0s
 => CACHED [2/2] RUN java -version                                                                                                                                0.0s
 => exporting to docker image format                                                                                                                              2.1s
 => => exporting layers                                                                                                                                           0.0s
 => => exporting manifest sha256:454932796194e7f6396a7e8161914eb8a738388827cbdcd3e8c78796bdf1f906                                                                 0.0s
 => => exporting config sha256:d90320a83caf172677f60f57ecaeb0cfeb1cb5d4082c3eccffa7c63d3dc6418c                                                                   0.0s
 => => sending tarball                                                                                                                                            2.1s
 => exporting to image                                                                                                                                            0.7s
 => => exporting layers                                                                                                                                           0.0s
 => => exporting manifest sha256:9a4fe359521d80c9e328de3c6cac53fcfadf69f9160564e4d237593a2418b581                                                                 0.0s
 => => exporting config sha256:d90320a83caf172677f60f57ecaeb0cfeb1cb5d4082c3eccffa7c63d3dc6418c                                                                   0.0s
 => => exporting attestation manifest sha256:30b84d971a06d8dea986c084eee08993e40688dc68910d9021a93b8772a855dd                                                     0.0s
 => => exporting manifest list sha256:998b3e2689d91aaf92f77c6df5f0e161dbe94ce7eb4e8f1f043599957ca47ba0                                                            0.0s
 => => pushing layers                                                                                                                                             0.5s
 => => pushing manifest for hub.paas/base/maven-test-arm64:v2@sha256:998b3e2689d91aaf92f77c6df5f0e161dbe94ce7eb4e8f1f043599957ca47ba0                         0.3s
 => [auth] base/maven-test-arm64:pull,push token for hub.paas                                                                                                 0.0s
 => importing to docker                                                                                                                                           0.0s

 1 warning found (use docker --debug to expand):
 - InvalidBaseImagePlatform: Base image hub.paas/base/maven:3.9.11-sapmachine-17 was pulled with platform "linux/amd64", expected "linux/arm64" for current build (line 1)

测试 arm64 平台镜像

docker run --rm -ti hub.paas/base/maven-test-arm64 java -version

WARNING: The requested image's platform (linux/arm64) does not match the detected host platform (linux/amd64/v3) and no specific platform was requested
openjdk version "17.0.16" 2025-07-15 LTS
OpenJDK Runtime Environment SapMachine (build 17.0.16+8-LTS)
OpenJDK 64-Bit Server VM SapMachine (build 17.0.16+8-LTS, mixed mode, sharing)

卸载 Buildx

删除二进制文件

# 独立二进制
sudo rm /usr/local/bin/docker-buildx

# 插件方式
rm ~/.docker/cli-plugins/docker-buildx

删除构建器

docker buildx rm mybuilder

Buildx 常用命令

参考文档

https://github.com/docker/buildx