Docker Buildx 构建器：本地配置挂载 + 远程构建

两个方案：

• 方案 A（本地容器）：buildkit 跑在 Docker 容器里，挂载本地 buildkitd.toml（镜像加速）
• 方案 B（远程）：自建 buildkitd 容器，buildx 用 remote 驱动连过去

配置文件统一放：/Users/sunjingliang/buildkit-config/buildkitd.toml

0. 配置文件

# /Users/sunjingliang/buildkit-config/buildkitd.toml
[registry."docker.io"]
  mirrors = ["docker.m.daocloud.io"]
[registry."docker.m.daocloud.io"]
  http = false
[worker.oci]
  snapshotter = "overlayfs"

方案 B 在 Docker Desktop 上需把 snapshotter 改成 "native"，见 B 的注意事项。

方案 A：docker-container + 本地配置挂载

创建

docker buildx rm -f mirror-builder
docker buildx create \
  --name mirror-builder \
  --driver docker-container \
  --driver-opt network=host \
  --buildkitd-config /Users/sunjingliang/buildkit-config/buildkitd.toml \
  --bootstrap --use

验证

docker exec buildx_buildkit_mirror-builder0 cat /etc/buildkit/buildkitd.toml
docker buildx inspect mirror-builder

使用

docker buildx build --platform linux/amd64,linux/arm64 --load -t sun-panel:test .
docker buildx build --platform linux/amd64,linux/arm64 --push -t hslr/sun-panel:1.0.0 .

注意事项

1. 配置在创建时写入构建器，改 toml 后必须 rm + create 重建
2. macOS 需要 /Users 已在 Docker Desktop → Settings → Resources → File Sharing 中共享
3. 需要代理时用 --driver-opt env.HTTP_PROXY=http://192.168.3.10:7897 --driver-opt env.HTTPS_PROXY=http://192.168.3.10:7897

方案 B：remote 驱动 + 自建 buildkitd

1. 启动 buildkitd 容器

docker rm -f remote-buildkitd
docker run -d \
  --name remote-buildkitd \
  --privileged \
  -v buildkit-cache:/var/lib/buildkit \
  -v /Users/sunjingliang/buildkit-config/buildkitd.toml:/etc/buildkit/buildkitd.toml:ro \
  -p 127.0.0.1:1234:1234 \
  moby/buildkit:latest \
  --addr tcp://0.0.0.0:1234

2. 用 remote 驱动绑定

docker buildx rm -f remote-builder
docker buildx create \
  --name remote-builder \
  --driver remote \
  tcp://127.0.0.1:1234 \
  --bootstrap --use

3. 验证

docker buildx inspect remote-builder      # STATUS = running
docker logs remote-buildkitd

注意事项

1. 缓存必须用 named volume（buildkit-cache:/var/lib/buildkit）。macOS host mount 走 virtiofs 不支持 xattrs，会报 failed to list xattrs / failed to create hash for ...
2. 若走 rootless 镜像（moby/buildkit:rootless），snapshotter 只能用 native，overlayfs 在 Docker Desktop 的 virtiofs 上无法创建快照目录
3. 换平台/多机时只需把 tcp://127.0.0.1:1234 换成对应地址即可

常用命令

docker buildx ls                      # 查看所有构建器（* 为当前）
docker buildx use <name>              # 切换当前构建器
docker buildx inspect <name>          # 查看详情
docker buildx inspect --bootstrap     # 启动并查看详情
docker buildx rm -f <name>            # 删除构建器
docker buildx prune -f                # 清理构建缓存

排错