docker/dockerfile-upstream

docker/dockerfile 暂存版镜像文档

1. 镜像概述

1.1 主要用途

本镜像为 docker/dockerfile 正式发布前的暂存版本（Staging），用于测试和预发布验证。生产环境应使用 Docker Hub 上的正式仓库：https://hub.docker.com/repository/docker/docker/dockerfile%E3%80%82

1.2 核心定位

作为 BuildKit 的官方 Dockerfile 前端镜像，提供动态加载能力，支持高级 Dockerfile 语法和构建特性，使 Docker 镜像构建更灵活、高效。

2. 核心功能与特性

2.1 BuildKit 前端支持

• 作为 BuildKit 的 Dockerfile 前端实现，支持动态从容器镜像加载前端
• 与 BuildKit 深度集成，提供标准 Dockerfile 语法的增强实现

2.2 多版本通道

• 稳定版（latest）：遵循语义化版本，提供稳定特性
• 实验版（labs）：包含实验性特性，版本号递增，可能不保证向后兼容
• 开发版（master）：基于 master 分支构建，包含最新开发特性

2.3 高级构建特性

• Build Mounts：支持 bind、cache、tmpfs、secret、ssh 五种挂载类型，实现依赖缓存、密钥安全管理等功能
• 网络模式控制：通过 RUN --network 指令控制单条命令的网络环境（none/host/default）
• 安全上下文：支持 --security=insecure 模式，允许特权操作（需 labs 版本）
• Here-Documents：支持多行脚本内联语法，简化复杂命令编写（需 labs 版本）

3. 适用场景

• 高级 Docker 构建需求：需使用缓存优化、密钥管理、SSH 访问等特性的场景
• 特性测试：验证新版本 Dockerfile 语法或实验性特性（如 labs 版本功能）
• 定制化构建流程：需动态控制网络隔离、安全上下文的构建场景

4. 标签说明

4.1 最新稳定版

4.2 最新实验版（labs）

4.3 开发构建版（master 分支）

5. 使用方法

5.1 启用 BuildKit

5.1.1 Docker 原生支持（v18.09+）

通过环境变量启用 BuildKit 模式：

bash
export DOCKER_BUILDKIT=1  # 客户端设置，仅当前终端生效

5.1.2 Docker Buildx

Docker Buildx 内置启用 BuildKit，无需额外配置：

bash
docker buildx build .  # 直接使用 Buildx 构建

5.2 指定外部前端

通过 Dockerfile 首行的 # syntax 指令指定本暂存镜像作为前端，格式：

dockerfile
# syntax=docker/dockerfile:<标签>  # 例如：# syntax=docker/dockerfile:1.19.0-labs

说明：

• 显式指定前端版本可确保所有构建者使用统一版本，避免因内置前端差异导致的兼容性问题
• 暂存版标签需使用本镜像的标签（如 1.19.0-labs），正式版需替换为 docker/dockerfile 仓库标签

5.3 高级构建特性详解

5.3.1 Build Mounts（RUN --mount=...）

需指定 Dockerfile 版本 ≥1.2（如 # syntax=docker/dockerfile:1.3），支持以下挂载类型：

5.3.1.1 type=bind（默认类型）

绑定构建上下文或其他构建阶段的目录（只读，可通过 rw 选项启用读写）。

5.3.1.2 type=cache

为编译器、包管理器等提供持久化缓存目录，加速构建。

示例：缓存 Go 依赖

dockerfile
# syntax=docker/dockerfile:1.3
FROM golang
RUN --mount=type=cache,target=/root/.cache/go-build go build -o app ./main.go

示例：缓存 apt 包

dockerfile
# syntax=docker/dockerfile:1.3
FROM ubuntu
# 配置 apt 保留下载缓存
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
# 挂载 apt 缓存目录
RUN --mount=type=cache,target=/var/cache/apt --mount=type=cache,target=/var/lib/apt \
  apt update && apt-get --no-install-recommends install -y gcc

5.3.1.3 type=tmpfs

挂载临时文件系统，用于临时存储。

5.3.1.4 type=secret

安全挂载密钥文件（如 API 密钥、证书），避免密钥嵌入镜像。

示例：使用 AWS 密钥访问 S3

dockerfile
# syntax=docker/dockerfile:1.3
FROM python:3
RUN pip install awscli
# 挂载 AWS 密钥文件到 /root/.aws/credentials
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials aws s3 cp s3://my-bucket/file.txt .

构建命令：

bash
docker build --secret id=aws,src=$HOME/.aws/credentials .

5.3.1.5 type=ssh

通过 SSH 代理挂载 SSH 密钥，支持带密码的密钥（需通过 ssh-agent 解锁）。

示例：访问 GitLab 私有仓库

dockerfile
# syntax=docker/dockerfile:1.3
FROM alpine
RUN apk add --no-cache openssh-client
RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
RUN --mount=type=ssh ssh -q -T git@gitlab.com  # 验证 SSH 连接

构建命令：

bash
eval $(ssh-agent)  # 启动 SSH 代理
ssh-add ~/.ssh/id_rsa  # 添加密钥（输入密码解锁）
docker build --ssh default=$SSH_AUTH_SOCK .  # 挂载 SSH 代理套接字

5.3.2 网络模式控制（RUN --network=...）

需指定 Dockerfile 版本 ≥1.3（如 # syntax=docker/dockerfile:1.3），控制单条 RUN 命令的网络环境。

示例：隔离外部网络依赖

dockerfile
# syntax=docker/dockerfile:1.3
FROM python:3.6
ADD mypackage.tgz wheels/  # 提前下载依赖包到构建上下文
RUN --network=none pip install --find-links wheels mypackage  # 仅使用本地依赖

5.3.3 安全上下文（RUN --security=...）

需使用 labs 通道（如 # syntax=docker/dockerfile:1.3-labs），控制命令的安全模式。

示例：获取特权能力

dockerfile
# syntax=docker/dockerfile:1.3-labs
FROM ubuntu
RUN --security=insecure cat /proc/self/status | grep CapEff  # 查看有效能力集

构建命令（需 BuildKitd 启用权限）：

bash
buildctl build --frontend=dockerfile.v0 \
  --local context=. --local dockerfile=. \
  --allow-insecure-entitlement security.insecure

5.3.4 Here-Documents（文档内联）

需使用 labs 通道（≥1.3.0-labs，如 # syntax=docker/dockerfile:1.3-labs），支持多行命令内联。

语法：

dockerfile
RUN <<<分隔符 [命令]
  内联内容...
分隔符

• 支持变量展开（${VAR}）和制表符自动剥离（<<-分隔符）
• 若仅指定分隔符，默认使用 shell 执行；可通过 shebang（如 #!/usr/bin/env python）指定解释器

示例 1：多行 Shell 命令

dockerfile
# syntax=docker/dockerfile:1.3-labs
FROM debian
RUN <<eot bash
  apt-get update
  apt-get install -y vim
eot

示例 2：Python 脚本内联

dockerfile
# syntax=docker/dockerfile:1.3-labs
FROM python:3.6
RUN <<eot
#!/usr/bin/env python
print("Hello, Here-Documents!")
eot

示例 3：创建文件

dockerfile
# syntax=docker/dockerfile:1.3-labs
FROM alpine
COPY <<-eot /app/config.txt  # "-" 自动剥离内容中的前导制表符
	server.port=8080
	log.level=info
eot

6. 使用场景与适用范围

6.1 典型场景

• 依赖缓存优化：通过 type=cache 缓存 npm/pip/apt 依赖，加速多阶段构建
• 密钥安全管理：通过 type=secret/ssh 安全挂载密钥，避免硬编码敏感信息
• 网络隔离构建：通过 --network=none 确保构建不依赖外部网络，提升可重复性
• 特权操作测试：通过 --security=insecure 调试需要特权的构建流程（如内核模块加载）
• 复杂脚本简化：通过 Here-Documents 简化多行命令的 Dockerfile 编写

6.2 版本选择建议

• 生产环境：使用正式仓库 docker/dockerfile 的稳定版标签（如 1.19）
• 实验特性测试：使用本暂存版的 labs 标签（如 1.19.0-labs）
• 开发调试：使用 master/master-labs 标签获取最新开发特性

7. 配置参数说明

7.1 环境变量

7.2 syntax 指令格式

dockerfile
# syntax=docker/dockerfile:<标签>

• <标签>：暂存版镜像标签（如 1.19.0-labs、master），需与镜像拉取标签一致

7.3 权限与依赖

• --network=host：需 BuildKitd 启动时添加 --allow-insecure-entitlement network.host，构建时通过 --allow network.host 启用
• --security=insecure：需 BuildKitd 启动时添加 --allow-insecure-entitlement security.insecure，构建时通过 --allow security.insecure 启用
• --ssh：带密码的密钥需通过 ssh-agent 解锁，直接挂载 .pem 文件不支持密码保护