tonistiigi/dockerfile

BuildKit

![asciicinema 示例]([***]

镜像概述和主要用途

BuildKit 是一个工具包，用于以高效、可扩展且可重复的方式将源代码转换为构建产物。它提供了强大的构建能力，支持多种前端格式（如 Dockerfile）和后端执行引擎，旨在优化构建流程的性能、可缓存性和灵活性。

核心功能和特性

• 自动垃圾回收：自动管理构建过程中产生的临时资源，释放存储空间
• 可扩展的前端格式：支持多种构建定义语言（如 Dockerfile），并允许自定义前端
• 并发依赖解析：并行处理构建依赖，提高构建效率
• 高效指令缓存：智能缓存构建步骤，避免重复执行
• 构建缓存导入/导出：支持缓存的导入和导出，加速跨环境构建
• 嵌套构建任务调用：支持在构建过程中嵌套调用其他构建任务
• 分布式工作节点：支持分布式构建，工作节点可跨环境部署
• 多种输出格式：支持导出为容器镜像、本地文件、OCI 镜像格式等
• 可插件化架构：支持通过插件扩展功能
• 无 root 权限执行：支持在非 root 权限下运行构建任务，增强安全性

使用场景和适用范围

适用场景

• 容器镜像构建（替代传统 Docker 构建流程）
• CI/CD 流水线中的自动化构建任务
• 需要高效缓存和并行处理的复杂构建流程
• 跨平台、分布式构建环境
• 非容器化产物的构建（如二进制文件、静态资源等）

被广泛使用的项目

• https://github.com/moby/moby/pull/37151%EF%BC%9ADocker 引擎的核心项目
• https://github.com/genuinetools/img%EF%BC%9A%E8%BD%BB%E9%87%8F%E7%BA%A7%E5%AE%B9%E5%99%A8%E9%95%9C%E5%83%8F%E6%9E%84%E5%BB%BA%E5%B7%A5%E5%85%B7
• https://github.com/openfaas/openfaas-cloud%EF%BC%9AServerless 平台的构建系统
• https://github.com/containerbuilding/cbi%EF%BC%9A%E5%AE%B9%E5%99%A8%E6%9E%84%E5%BB%BA%E6%8E%A5%E5%8F%A3%E6%A0%87%E5%87%86

详细使用方法和配置说明

依赖项

• https://github.com/opencontainers/runc%EF%BC%9AOCI 运行时，用于执行容器
• https://github.com/containerd/containerd%EF%BC%9A%E5%AE%B9%E5%99%A8%E8%BF%90%E8%A1%8C%E6%97%B6%E7%AE%A1%E7%90%86%EF%BC%88%E5%A6%82%E9%9C%80%E4%BD%BF%E7%94%A8 containerd 工作节点）

安装步骤

源码编译安装

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

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

# 如需仅构建特定工作节点版本，可使用
$ make binaries-all  # 生成 buildkitd.containerd_only 和 buildkitd.oci_only

启动 buildkitd 守护进程

基本启动命令

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

工作节点后端配置

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

• OCI（runc）：默认启用，依赖 runc
• containerd：需手动启用，依赖 containerd

配置示例：

bash
# 使用 containerd 后端（禁用 OCI 后端）
buildkitd --debug --root /var/lib/buildkit --oci-worker=false --containerd-worker=true

探索 LLB

LLB（Low-Level Build）是 BuildKit 的二进制中间格式，用于定义构建过程中进程的依赖图。类比：LLB 之于 Dockerfile，如同 LLVM IR 之于 C 语言。

LLB 特性

• 基于 Protobuf 消息序列化
• 支持并发执行
• 高效缓存
• 厂商中立（可轻松实现非 Dockerfile 语言的前端）

LLB 高级语言支持

目前已实现的 LLB 高级语言前端：

• Dockerfile（详见下文“探索 Dockerfiles”）
• 自定义语言（可通过 PR 扩展）

探索 Dockerfiles

BuildKit 通过前端组件将 Dockerfile 转换为 LLB。默认使用 dockerfile.v0 前端，未来将支持外部镜像提供的前端。

使用 buildctl 构建 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 context=.：将当前目录作为构建上下文暴露给构建器
• --local dockerfile=.：指定 Dockerfile 所在目录

兼容 docker build 的包装工具

对于熟悉 docker build 命令的用户，可使用示例包装工具 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 .  # 构建并标记镜像 myimage

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

# 构建结果自动加载到 Docker
$ docker inspect myimage  # 查看构建后的镜像

构建产物导出

默认情况下，构建结果仅保存在 BuildKit 内部，需通过导出器指定输出方式。

导出到 containerd

需使用 containerd 工作节点：

bash
buildctl build ... --exporter=image --exporter-opt name=docker.io/username/image

# 查看导出的镜像
ctr --namespace=buildkit images ls

推送到镜像仓库

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

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

导出到本地文件系统

适用于构建非容器镜像产物：

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

导出到 Docker 引擎

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

导出为 OCI 镜像格式

bash
# 导出到本地文件
buildctl build ... --exporter=oci --exporter-opt output=path/to/output.tar

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

其他常用操作

查看构建缓存

bash
buildctl du -v  # -v 显示详细信息

查看启用的工作节点

bash
buildctl debug workers -v  # 显示工作节点类型、状态等信息

Docker 容器化部署方案

运行容器化 buildkitd 守护进程

可通过 Docker 容器运行 buildkitd，并远程访问。客户端 buildctl 支持 macOS 和 Windows。

启动容器化守护进程

bash
# 启动容器，映射端口 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 本地构建：

bash
docker build -f ./hack/dockerfiles/test.Dockerfile -t local-buildkit .

配置参数说明

buildkitd 守护进程参数

buildctl 客户端参数

环境变量

OpenTracing 支持

BuildKit 支持 OpenTracing，用于追踪 buildkitd gRPC API 和 buildctl 命令。以 Jaeger 为例：

启动 Jaeger 追踪服务

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

配置 BuildKit 追踪

bash
# 设置追踪地址
export JAEGER_TRACE=0.0.0.0:6831

# 重启 buildkitd 和 buildctl，构建操作将被追踪
# 访问 http://127.0.0.1:16686 查看追踪数据

无 root 权限运行

BuildKit 支持无 root 权限运行，详细配置见 https://github.com/moby/buildkit/blob/master/docs/rootless.md%E3%80%82

支持的 runc 版本

开发过程中，BuildKit 测试基于 containerd 仓库使用的 runc 版本。详见 https://github.com/containerd/containerd/blob/v1.1.0/RUNC.md%E3%80%82

贡献指南

运行测试

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

# 测试指定包
make test TESTPKGS=./client

# 运行特定测试（带详细日志）
make test TESTPKGS=./client TESTFLAGS="--run /TestCallDiskUsage -v"

# 指定工作节点运行集成测试（支持：oci、oci-rootless、containerd、containerd-1.0）
make test TESTPKGS=./client TESTFLAGS="--run //worker=containerd -v"

更新依赖项

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

提交前验证

bash
# 执行代码格式、lint、测试等全量验证
make validate-all