BuildKit / Buildx 镜像加速配置

使用 Docker Buildx 构建镜像时,可以为 BuildKit 单独配置毫秒镜像源,让 FROM alpine:latest 等基础镜像通过毫秒镜像拉取,无需修改 Dockerfile 中的镜像名称。

本文根据 Docker 官方 Registry mirror 配置说明编写,以 docker-container 驱动为例。

适用场景

docker-container 驱动会启动独立的 BuildKit 容器。即使已经在 Docker 的 daemon.json 中配置了 registry-mirrors,仍应为这个构建器配置自己的镜像源。

以下命令适用于 Linux、macOS 或 Windows 的 WSL / Bash 环境。先确认 Docker 已启动,并且可以使用 Buildx:

docker info
docker buildx version

1. 选择镜像加速地址

  • 公共地址:docker.1ms.run。
  • 专属域名:前往专属域名管理,创建加速源为 docker.io 的域名,复制“不带协议”的地址。使用方法见专属域名。

下面先使用公共地址演示。需要使用账号资源包或余额的用户,推荐替换为自己的 docker.io 专属域名;专属域名支持免登录拉取。

2. 创建 BuildKit 配置文件

在执行 Docker CLI 的机器上创建配置文件:

mkdir -p "$HOME/.config/buildkit"
cat > "$HOME/.config/buildkit/1ms.toml" <<'EOF'
debug = true

[registry."docker.io"]
  mirrors = ["docker.1ms.run"]
EOF
  • [registry."docker.io"] 表示为 Docker Hub 配置镜像源。
  • mirrors 填写加速域名,此处不带 https://,也不添加 /v2/。
  • debug = true 用于验证实际请求地址;排查完成后可以关闭,并重新创建构建器使新配置生效。

如果使用专属域名,在创建构建器前,将文件中的 mirrors 改为:

[registry."docker.io"]
  mirrors = ["yourdomain.d.1ms.run"]

yourdomain.d.1ms.run 仅为占位示例,请替换为实际域名。保留文件顶部的 debug = true,并替换原来的配置段,避免重复声明 [registry."docker.io"]。

一个专属域名只对应一个上游仓库。配置 ghcr.io 等其他仓库时,应使用对应仓库的配置段和专属域名,不能混用 Docker Hub 的地址。

3. 创建并启用构建器

docker buildx create \
  --name 1ms-builder \
  --driver docker-container \
  --buildkitd-config "$HOME/.config/buildkit/1ms.toml" \
  --use \
  --bootstrap

--buildkitd-config 指定上一步的文件,--use 将其选为当前 Buildx 构建器,--bootstrap 立即启动 BuildKit。参数说明见 docker buildx create。

检查构建器状态:

docker buildx inspect 1ms-builder --bootstrap
docker buildx ls

确认驱动为 docker-container,节点状态为 running。如果已经存在同名构建器,请使用新名称,并同步替换后续命令中的构建器名和容器名。

4. 构建测试镜像

下面的测试直接从标准输入读取 Dockerfile,不需要创建项目文件:

docker buildx build \
  --builder 1ms-builder \
  --pull \
  --progress=plain \
  --load \
  -t 1ms-buildkit-test:latest - <<'EOF'
FROM alpine:latest
RUN echo "1ms BuildKit mirror test"
EOF

--pull 要求尝试拉取引用的基础镜像,便于验证请求;--load 将构建结果加载到本机 Docker 镜像列表。构建成功后可查看:

docker image inspect 1ms-buildkit-test:latest

实际项目在 Dockerfile 所在目录执行:

docker buildx build --builder 1ms-builder --load -t myapp:latest .

上述示例为单平台构建。构建参数和输出方式见 docker buildx build。

5. 确认镜像源生效

查看 BuildKit 容器内的配置和最近日志:

docker exec buildx_buildkit_1ms-builder0 cat /etc/buildkit/buildkitd.toml
docker logs --since 10m buildx_buildkit_1ms-builder0

确认容器内包含 [registry."docker.io"] 及所选镜像域名,再在调试日志中查找 docker.1ms.run 或实际专属域名,检查对应请求及响应是否成功。

构建输出中仍然出现 docker.io/library/alpine 属于正常现象:它表示镜像的原始名称。判断是否走加速,应结合 BuildKit 日志中的请求地址与响应,不能仅看镜像名称,也不能仅凭构建成功判断。

常见问题

创建构建器时,拉取 moby/buildkit 超时

--bootstrap 需要先启动 BuildKit 容器,这一步由 Docker 拉取 BuildKit 自身的镜像;此时容器内的镜像源配置尚未生效。

可先按 Linux Docker源或 Windows/Mac设备配置步骤配置 Docker 的镜像源。也可以在创建构建器时额外传入:

--driver-opt image=docker.1ms.run/moby/buildkit:buildx-stable-1

使用专属域名时,将 docker.1ms.run 替换为自己的 docker.io 专属域名。此参数设置的是 BuildKit 容器镜像,仍需保留 --buildkitd-config 来加速构建过程中的基础镜像拉取。参见 Docker container driver。

配置完成后,docker build 仍然没有使用新构建器

请使用本文的 docker buildx build --builder 1ms-builder ... 命令显式选择构建器。docker build 默认选择 Docker Engine 自带的构建器,仅执行 docker buildx use 不足以改变它的默认行为。参见 Docker 构建器选择说明。

修改本地 TOML 文件后没有生效

本地文件通过 --buildkitd-config 在创建时传入,并非持续挂载到容器中。修改后,可使用新的构建器名称重新执行第 3 步,再用 --builder 新名称 验证配置。

专属域名返回 403 或访问失败

确认域名对应 docker.io、未暂停或过期,并检查账号资源包 / 余额及 IP 白名单。白名单需要允许实际运行 BuildKit 的机器访问;远程构建器的出口 IP 可能与本机不同。详见专属域名常见问题。