BuildKit 技术文档

镜像概述和主要用途

BuildKit 是一个工具包，用于以高效、可表达且可重复的方式将源代码转换为构建产物。它提供了先进的构建能力，支持复杂的依赖管理、高效缓存和多格式输出，旨在替代传统构建工具，优化容器镜像及其他构建产物的构建流程。

核心功能和特性

• 自动垃圾回收：自动管理构建过程中产生的临时资源，释放存储空间
• 可扩展的前端格式：支持多种构建定义格式（如 Dockerfile、自定义语言）
• 并发依赖解析：并行处理构建依赖，提升构建效率
• 高效指令缓存：智能缓存构建步骤，避免重复计算
• 构建缓存导入/导出：支持缓存的跨环境迁移，加速多环境构建
• 嵌套构建任务调用：支持在构建过程中嵌套执行其他构建任务
• 分布式工作节点：支持分布式构建，可将任务分配到多个工作节点
• 多输出格式：支持导出为容器镜像、本地文件、OCI 规范 tar 包等多种格式
• 可插拔架构：支持扩展工作节点后端、前端解析器等组件
• 无 root 权限执行：支持在非 root 用户环境下运行构建任务

使用场景和适用范围

适用场景

• 容器镜像构建（替代传统 docker build）
• CI/CD 流水线中的自动化构建流程
• 复杂依赖项目的多阶段构建
• 需要高效缓存和并行构建的场景
• 自定义构建流程（如非 Dockerfile 定义的构建逻辑）

被广泛使用的项目

• Moby：Docker 引擎的核心组件
• img：轻量级容器镜像构建工具
• OpenFaaS Cloud：Serverless 平台的构建系统
• container build interface：容器构建接口标准

安装与依赖

依赖项

• runc：OCI 容器运行时（默认工作节点依赖）
• containerd：容器运行时（如需使用 containerd 工作节点）

安装步骤

从源码编译安装

以下命令将 buildkitd（守护进程）和 buildctl（客户端工具）安装到 /usr/local/bin：

bash
# 编译并安装
$ make && sudo make install

# 如需仅构建特定工作节点版本（如仅 containerd 或仅 OCI）
$ make binaries-all  # 生成 buildkitd.containerd_only 和 buildkitd.oci_only

配置与启动

启动 buildkitd 守护进程

基本启动命令

bash
buildkitd --debug --root /var/lib/buildkit

核心参数说明

• --debug：启用调试日志
• --root：指定构建数据存储根目录（默认：/var/lib/buildkit）
• --oci-worker：启用/禁用 OCI (runc) 工作节点（默认：true）
• --containerd-worker：启用/禁用 containerd 工作节点（默认：false）

工作节点后端选择

BuildKit 支持两种工作节点后端：

• OCI (runc)：默认后端，依赖 runc
• containerd：需手动启用，依赖 containerd

切换至 containerd 后端：

bash
buildkitd --oci-worker=false --containerd-worker=true

基本使用方法

LLB 简介

BuildKit 构建基于名为 LLB（Low-Level Build）的二进制中间格式，用于定义构建过程中进程的依赖图。LLB 类似于 "Dockerfile 的 LLVM IR"，具有以下特性：

• 基于 Protobuf 消息序列化
• 支持并发执行
• 高效缓存
• 厂商中立（支持非 Dockerfile 构建定义）

LLB 格式定义见 solver/pb/ops.proto。目前支持的 LLB 高级语言包括 Dockerfile 及自定义语言（可通过 PR 添加）。

探索 LLB 示例

通过示例脚本生成并查看 LLB 构建图：

bash
# 生成 LLB 定义并通过 jq 格式化输出
go run examples/buildkit0/buildkit.go | buildctl debug dump-llb | jq .

# 执行构建（示例脚本支持 --with-containerd 标志添加 containerd 支持）
go run examples/buildkit0/buildkit.go | buildctl build

示例脚本说明：

• buildkit0：仅使用 exec 操作，为每个组件定义完整阶段
• buildkit1：分离 git 克隆步骤以提升并发度
• buildkit2：直接使用 git 源而非 git clone，优化性能和缓存
• buildkit3：支持本地源码路径（如 --runc=local）
• dockerfile2llb：将 Dockerfile 转换为 LLB（调试用）
• gobuild：演示嵌套调用生成 Go 包依赖的 LLB

使用 Dockerfile 构建

直接使用 buildctl 构建

通过 dockerfile.v0 前端解析 Dockerfile：

bash
# 基本构建（上下文和 Dockerfile 均为当前目录）
buildctl build --frontend=dockerfile.v0 --local context=. --local dockerfile=.

# 指定构建目标和构建参数
buildctl build \
  --frontend=dockerfile.v0 \
  --local context=. \
  --local dockerfile=. \
  --frontend-opt target=foo \  # 指定构建目标阶段
  --frontend-opt build-arg:foo=bar  # 传递构建参数

参数说明：

• --frontend=dockerfile.v0：使用 Dockerfile 前端
• --local <name>=<path>：将本地路径暴露给构建器（context 为构建上下文，dockerfile 为 Dockerfile 路径）

使用 build-using-dockerfile 工具

为简化 Dockerfile 构建，可使用 build-using-dockerfile 包装工具（语法类似 docker build）：

bash
# 编译并安装工具
go build ./examples/build-using-dockerfile && sudo install build-using-dockerfile /usr/local/bin

# 基本构建
build-using-dockerfile -t myimage .

# 指定 Dockerfile 路径和标签
build-using-dockerfile -t mybuildkit -f ./hack/dockerfiles/test.Dockerfile .

# 构建后自动加载到 Docker
docker inspect myimage

构建产物导出

BuildKit 需通过导出器（Exporter）获取构建结果，支持以下导出方式：

1. 导出到 containerd

需使用 containerd 工作节点：

bash
# 导出镜像到 containerd
buildctl build ... --exporter=image --exporter-opt name=docker.io/username/image

# 查看 containerd 中的镜像
ctr --namespace=buildkit images ls

2. 推送到镜像仓库

bash
buildctl build ... \
  --exporter=image \
  --exporter-opt name=docker.io/username/image \  # 镜像名称（含仓库地址）
  --exporter-opt push=true  # 启用推送

注：如需认证，buildctl 会自动读取 Docker 配置文件（~/.docker/config.json）。

3. 导出到本地目录

将构建产物直接复制到客户端本地目录（适用于非容器镜像构建）：

bash
buildctl build ... --exporter=local --exporter-opt output=path/to/output-dir

4. 导出到 Docker

通过 tarball 导出并加载到 Docker：

bash
# 导出为 Docker 兼容 tarball 并加载
buildctl build ... --exporter=docker --exporter-opt name=myimage | docker load

5. 导出为 OCI 镜像格式 tarball

bash
# 导出到指定路径
buildctl build ... --exporter=oci --exporter-opt output=path/to/output.tar

# 导出到标准输出
buildctl build ... --exporter=oci > output.tar

容器化部署

BuildKit 可通过容器运行 buildkitd 守护进程，并通过远程客户端访问。

启动容器化 buildkitd

bash
# 启动 buildkitd 容器（特权模式，暴露 1234 端口）
docker run -d --privileged -p 1234:1234 tonistiigi/buildkit --addr tcp://0.0.0.0:1234

# 配置客户端连接地址
export BUILDKIT_HOST=tcp://0.0.0.0:1234

# 验证客户端连接
buildctl build --help

注：tonistiigi/buildkit 镜像可通过本地构建生成，Dockerfile 路径：./hack/dockerfiles/test.Dockerfile。

高级配置

查看构建缓存

bash
buildctl du -v  # 查看缓存使用情况（-v 显示详细信息）

显示启用的工作节点

bash
buildctl debug workers -v  # 查看工作节点状态（-v 显示详细信息）

OpenTracing 支持

BuildKit 支持通过 OpenTracing 追踪构建过程，以 Jaeger 为例：

1. 启动 Jaeger 容器：

bash
docker run -d -p 6831:6831/udp -p ***:*** jaegertracing/all-in-one:latest

2. 配置追踪地址：

bash
export JAEGER_TRACE=0.0.0.0:6831  # Jaeger 收集器地址

3. 重启 buildkitd 和 buildctl，构建任务将被追踪，可通过 [***] 查看追踪结果。

支持的 runc 版本

BuildKit 测试使用的 runc 版本与 containerd 项目一致，详情参考 containerd 的 RUNC.md。

非 root 权限运行

详情参考 docs/rootless.md。

开发与贡献

运行测试

bash
make test  # 容器化环境中运行所有单元和集成测试

测试选项

• 测试特定包：

  bash
  make test TESTPKGS=./client  # 仅测试 client 包
  

• 运行特定测试（含工作节点组合）：

  bash
  make test TESTPKGS=./client TESTFLAGS="--run /TestCallDiskUsage -v"
  

• 指定工作节点后端测试：

  bash
  # 支持的后端：oci, oci-rootless, containerd, containerd-1.0
  make test TESTPKGS=./client TESTFLAGS="--run //worker=containerd -v"
  

更新依赖

bash
# 修改 vendor.conf 后更新依赖
make vendor

提交前验证

bash
make validate-all  # 验证代码格式、依赖等