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 version1. 选择镜像加速地址
下面先使用公共地址演示。需要使用账号资源包或余额的用户,推荐替换为自己的 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 可能与本机不同。详见专属域名常见问题。