BuildKit 与 Buildx

1. 角色与版本

BuildKit：执行构建图、缓存、source、frontend 和 exporter 的后端。
Buildx：Docker CLI 插件，用于创建和管理 BuildKit builder，提供多平台、Bake、高级缓存等能力。

截至 2026-08-12，独立稳定版为 BuildKit 0.32.2、Buildx 0.36.1；Engine 29.7.2 打包 BuildKit 0.32.2。实际版本：

bash

docker buildx version
docker buildx ls
docker buildx inspect --bootstrap

2. Builder 与 driver

bash

docker buildx ls
docker buildx inspect default

常见 driver：

driver	BuildKit 在哪里	典型特点
`docker`	Engine 内置	配置简单，能力受 Engine 配置影响
`docker-container`	专用容器	隔离 builder，支持高级缓存和多平台
`kubernetes`	Kubernetes Pod	集群级构建
`remote`	远端 BuildKit	统一构建服务

创建：

bash

docker buildx create \
  --name team-builder \
  --driver docker-container \
  --bootstrap \
  --use

docker buildx inspect team-builder

切换：

bash

docker buildx use team-builder
docker buildx use default

删除：

bash

docker buildx rm team-builder

删除 builder 可能删除其本地构建缓存；先检查缓存策略。

3. 输出类型

bash

# 单平台构建并加载本地 Engine
docker buildx build \
  --load \
  -t team-api:dev .

# 构建并推送 Registry
docker buildx build \
  --push \
  -t registry.example.internal/team/api:2026.08.12 .

# 导出 OCI archive
docker buildx build \
  --output type=oci,dest=team-api.oci.tar .

# 仅导出文件系统结果
docker buildx build \
  --output type=local,dest=./out .

docker-container driver 的结果不会自动进入本地 image store；需要 --load、--push 或 --output。多平台结果通常直接 --push，因为传统本地 image store 无法加载完整多平台 index。

4. 多平台构建

bash

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t registry.example.internal/team/api:2026.08.12 \
  --push .

验证：

bash

docker buildx imagetools inspect \
  registry.example.internal/team/api:2026.08.12

三种策略：

QEMU 仿真：设置简单，编译和测试可能较慢。
多个原生节点：速度和兼容性好，管理复杂。
语言交叉编译：高效，但不能替代目标架构运行测试。

Engine 29 新安装默认 containerd image store，原生支持多平台镜像存储；升级机器仍应通过 docker info 核对。

5. 平台参数

Dockerfile 自动提供：

dockerfile

# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM golang:1.26-alpine AS build
ARG BUILDPLATFORM
ARG TARGETPLATFORM
ARG TARGETOS
ARG TARGETARCH
RUN echo "builder=$BUILDPLATFORM target=$TARGETPLATFORM"

不要在 FROM 中强制 linux/amd64 来“解决” ARM 构建；这可能让整个构建一直走仿真。

6. 缓存

查看与清理：

bash

docker buildx du
docker buildx du --verbose
docker buildx prune

警告： prune 会删除 builder 缓存，后续构建显著变慢。共享 builder 上应先确认其他流水线没有依赖。

6.1 Registry cache

bash

docker buildx build \
  --cache-from type=registry,ref=registry.example.internal/team/api:buildcache \
  --cache-to type=registry,ref=registry.example.internal/team/api:buildcache,mode=max \
  -t registry.example.internal/team/api:2026.08.12 \
  --push .

cache tag 与发布镜像分离。对不可信 PR 不应写入受信任主干 cache，避免 cache poisoning 和权限扩大。

6.2 GitHub Actions cache

在 GitHub Actions 中可使用 type=gha；其他 CI 选择其支持的 cache backend。缓存不是发布产物，不应成为唯一可恢复来源。

6.3 Inline cache

bash

docker buildx build \
  --cache-to type=inline \
  --cache-from type=registry,ref=registry.example.internal/team/api:stable \
  -t registry.example.internal/team/api:stable \
  --push .

大规模多阶段构建通常更适合独立 registry cache 的 mode=max。

7. Cache mount

dockerfile

RUN --mount=type=cache,target=/root/.cache/go-build \
    --mount=type=cache,target=/go/pkg/mod,sharing=locked \
    go build -o /out/server ./cmd/server

缓存内容不进入最终 layer，但可能跨构建复用。不要把 Secret 放入 cache mount。

APT：

dockerfile

RUN rm -f /etc/apt/apt.conf.d/docker-clean \
    && echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' \
       > /etc/apt/apt.conf.d/keep-cache

RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && apt-get install -y --no-install-recommends gcc

8. Secret mount

Dockerfile：

dockerfile

RUN --mount=type=secret,id=npmrc,target=/root/.npmrc,required=true \
    npm ci

构建：

bash

docker buildx build \
  --secret id=npmrc,src="$HOME/.npmrc" .

环境变量：

bash

export API_TOKEN='temporary-token'
docker buildx build --secret id=API_TOKEN,env=API_TOKEN .
unset API_TOKEN

Dockerfile：

dockerfile

RUN --mount=type=secret,id=API_TOKEN \
    token="$(cat /run/secrets/API_TOKEN)" \
    && ./download-private-dependency "$token"

不要在命令输出中打印 token。即使使用 secret mount，构建步骤自身也可能把 Secret 写入最终 layer或日志。

9. SSH mount

Dockerfile：

dockerfile

RUN --mount=type=ssh,required=true \
    git clone git@github.com:example/private-repo.git

构建：

bash

docker buildx build --ssh default .

必须预先固定可信 known_hosts；不要用 StrictHostKeyChecking=no。

10. Git 构建上下文

bash

docker buildx build \
  'https://github.com/example/repo.git?tag=v1.2.3&checksum=FULL_COMMIT_SHA'

对可移动 tag/branch 搭配 checksum，避免构建期间引用变化。私有仓库通过受控 SSH 或 token Secret 访问。

11. SBOM 与 provenance

推送时生成证明材料：

bash

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --sbom=true \
  --provenance=mode=max \
  -t registry.example.internal/team/api:2026.08.12 \
  --push .

检查：

bash

docker buildx imagetools inspect \
  registry.example.internal/team/api:2026.08.12

注意：

Registry 必须支持 OCI referrers/attestations。
provenance 可能记录构建参数和仓库信息；不能把 Secret 放在 build args。
SBOM 是软件清单，不等于漏洞扫描，也不证明镜像安全。

12. Build checks

bash

docker build --check .
docker buildx build --check .

检查可发现 Dockerfile 中的部分错误和不推荐写法。它不能替代：

单元测试与集成测试；
镜像启动和健康检查；
漏洞扫描；
非 root/只读文件系统验证；
目标平台运行测试。

13. Bake

docker-bake.hcl：

hcl

variable "REGISTRY" {
  default = "registry.example.internal"
}

variable "TAG" {
  default = "dev"
}

group "default" {
  targets = ["api"]
}

target "api" {
  context = "."
  dockerfile = "Dockerfile"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["${REGISTRY}/team/api:${TAG}"]
  cache-from = ["type=registry,ref=${REGISTRY}/team/api:buildcache"]
  cache-to = ["type=registry,ref=${REGISTRY}/team/api:buildcache,mode=max"]
}

预览：

bash

REGISTRY=registry.example.internal TAG=git-a1b2c3d \
  docker buildx bake --print

构建：

bash

REGISTRY=registry.example.internal TAG=git-a1b2c3d \
  docker buildx bake --push

先 --print 可发现 tag、platform 和 cache 变量错误。

14. 多节点 builder

bash

docker context create node-amd64 \
  --docker 'host=ssh://builder-amd64.example.internal'
docker context create node-arm64 \
  --docker 'host=ssh://builder-arm64.example.internal'

docker buildx create --name native --use node-amd64
docker buildx create --name native --append node-arm64
docker buildx inspect native --bootstrap

构建节点属于高权限供应链基础设施，需隔离不可信任务、限制网络、清理 Secret、打补丁并审计产物来源。

15. 调试构建

bash

docker buildx build --progress=plain --no-cache .
docker buildx history ls
docker buildx inspect --bootstrap
docker buildx du --verbose

常见问题：

现象	原因	处理
构建成功但本地无镜像	`docker-container` driver 未 `--load`	单平台加 `--load` 或直接 `--push`
多平台 `--load` 失败	本地 store/输出不支持完整 index	使用 containerd store 或 `--push`
cache miss	上下文、ARG、依赖文件变化	`--progress=plain` 检查层
`exec format error`	构建/运行平台不匹配	检查 manifest 与 `--platform`
Secret 泄露	用 ARG/COPY 或命令打印	撤销凭据并改 secret mount
push attestation 失败	Registry OCI 支持不足	升级/配置 Registry，验证兼容

16. CI 基线

bash

docker buildx create --driver docker-container --use --bootstrap

docker buildx build \
  --pull \
  --platform linux/amd64,linux/arm64 \
  --cache-from type=registry,ref="$CACHE_REF" \
  --cache-to type=registry,ref="$CACHE_REF",mode=max \
  --sbom=true \
  --provenance=mode=max \
  --tag "$IMAGE_REF" \
  --push \
  .

变量应由 CI 安全配置注入；在运行前校验 Registry host、repository、tag 和 Git SHA，防止拼接错误推送到意外位置。

BuildKit 与 Buildx

1. 角色与版本

2. Builder 与 driver

3. 输出类型

4. 多平台构建

5. 平台参数

6. 缓存

6.1 Registry cache

6.2 GitHub Actions cache

6.3 Inline cache

7. Cache mount

8. Secret mount

9. SSH mount

10. Git 构建上下文

11. SBOM 与 provenance

12. Build checks

13. Bake

14. 多节点 builder

15. 调试构建

16. CI 基线

17. 官方参考

继续阅读

BuildKit 与 Buildx ​

1. 角色与版本 ​

2. Builder 与 driver ​

3. 输出类型 ​

4. 多平台构建 ​

5. 平台参数 ​

6. 缓存 ​

6.1 Registry cache ​

6.2 GitHub Actions cache ​

6.3 Inline cache ​

7. Cache mount ​

8. Secret mount ​

9. SSH mount ​

10. Git 构建上下文 ​

11. SBOM 与 provenance ​

12. Build checks ​

13. Bake ​

14. 多节点 builder ​

15. 调试构建 ​

16. CI 基线 ​

17. 官方参考 ​

继续阅读

BuildKit 与 Buildx

1. 角色与版本

2. Builder 与 driver

3. 输出类型

4. 多平台构建

5. 平台参数

6. 缓存

6.1 Registry cache

6.2 GitHub Actions cache

6.3 Inline cache

7. Cache mount

8. Secret mount

9. SSH mount

10. Git 构建上下文

11. SBOM 与 provenance

12. Build checks

13. Bake

14. 多节点 builder

15. 调试构建

16. CI 基线

17. 官方参考