docker/dockerfile-upstream Docker 镜像 - 轩辕镜像 | Docker 镜像高效稳定拉取服务
docker/dockerfile-upstreamDocker Dockerfile的预发布版本，用于开发和测试阶段的Dockerfile相关功能验证与体验。
docker/dockerfile 暂存版镜像文档
1. 镜像概述
1.1 主要用途
本镜像为 docker/dockerfile 正式发布前的暂存版本（Staging），用于测试和预发布验证。生产环境应使用 Docker Hub 上的正式仓库：docker/dockerfile。
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 最新稳定版
| 标签 | 说明 | Dockerfile 路径 |
|---|---|---|
1.19.0, 1.19, 1, latest | 1.19 系列稳定版 | dockerfile/1.19.0 |
1.18.0, 1.18 | 1.18 系列稳定版 | dockerfile/1.18.0 |
4.2 最新实验版（labs）
| 标签 | 说明 | Dockerfile 路径 |
|---|---|---|
1.19.0-labs, 1.19-labs, 1-labs, labs | 1.19 系列实验版 | dockerfile/1.19.0-labs |
4.3 开发构建版（master 分支）
| 标签 | 说明 | Dockerfile 路径 |
|---|---|---|
master | master 分支稳定开发版 | dockerfile/master |
master-labs | master 分支实验开发版 | dockerfile/master |
5. 使用方法
5.1 启用 BuildKit
5.1.1 Docker 原生支持（v18.09+）
通过环境变量启用 BuildKit 模式：
bashexport DOCKER_BUILDKIT=1 # 客户端设置，仅当前终端生效
5.1.2 Docker Buildx
Docker Buildx 内置启用 BuildKit，无需额外配置：
bashdocker 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 选项启用读写）。
| 参数 | 说明 |
|---|---|
target | 必填，挂载路径 |
source | 源路径，默认值为 from 指定阶段的根目录 |
from | 构建阶段或镜像名称，默认值为构建上下文 |
rw/readwrite | 启用读写模式，写入数据构建后会被丢弃 |
5.3.1.2 type=cache
为编译器、包管理器等提供持久化缓存目录，加速构建。
| 参数 | 说明 |
|---|---|
target | 必填，挂载路径 |
id | 缓存标识，默认值为 target 的路径 |
ro/readonly | 只读模式 |
sharing | 缓存共享模式：shared（多写入者共享）、private（独立缓存）、locked（独占锁），默认 shared |
from | 缓存基础阶段，默认空目录 |
source | from 中的子路径，默认根目录 |
mode | 缓存目录权限（八进制），默认 0755 |
uid/gid | 缓存目录所有者 UID/GID，默认 0 |
示例：缓存 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
挂载临时文件系统，用于临时存储。
| 参数 | 说明 |
|---|---|
target | 必填，挂载路径 |
5.3.1.4 type=secret
安全挂载密钥文件（如 API 密钥、证书），避免密钥嵌入镜像。
| 参数 | 说明 |
|---|---|
id | 密钥标识，默认值为 target 的文件名 |
target | 挂载路径，默认值 /run/secrets/<id> |
required | 密钥不可用时是否报错，默认 false（不报错） |
mode | 密钥文件权限（八进制），默认 0400 |
uid/gid | 密钥文件所有者 UID/GID，默认 0 |
示例：使用 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 .
构建命令：
bashdocker build --secret id=aws,src=$HOME/.aws/credentials .
5.3.1.5 type=ssh
通过 SSH 代理挂载 SSH 密钥，支持带密码的密钥（需通过 ssh-agent 解锁）。
| 参数 | 说明 |
|---|---|
id | SSH 标识，默认 default |
target | SSH 代理套接字路径，默认 /run/buildkit/ssh_agent.${N} |
required | 密钥不可用时是否报错，默认 false |
mode | 套接字权限（八进制），默认 0600 |
uid/gid | 套接字所有者 UID/GID，默认 0 |
示例：访问 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 *** # 验证 SSH 连接
构建命令：
basheval $(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 命令的网络环境。
| 网络模式 | 说明 |
|---|---|
none | 无网络（仅保留 lo 回环接口，与外部隔离） |
host | 使用主机网络（需 network.host 权限，通过 --allow-insecure-entitlement network.host 启用） |
default | 默认网络（与未指定 --network 效果一致） |
示例：隔离外部网络依赖
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），控制命令的安全模式。
| 参数值 | 说明 |
|---|---|
insecure | 禁用沙箱，以特权模式运行（等效于 docker run --privileged），需 security.insecure 权限 |
sandbox | 默认沙箱模式（无实际效果，显式指定用） |
示例：获取特权能力
dockerfile# syntax=docker/dockerfile:1.3-labs FROM ubuntu RUN --security=insecure cat /proc/self/status | grep CapEff # 查看有效能力集
构建命令（需 BuildKitd 启用权限）：
bashbuildctl 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），支持多行命令内联。
语法：
dockerfileRUN <<<分隔符 [命令] 内联内容... 分隔符
- 支持变量展开（
${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 环境变量
| 变量名 | 说明 |
|---|---|
DOCKER_BUILDKIT | Docker 客户端启用 BuildKit：export DOCKER_BUILDKIT=1（v18.09+ 支持） |
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文件不支持密码保护
docker/dockerfile
Docker 官方工具与组件镜像
这些是官方提供的Dockerfile前端镜像，主要功能是支持通过BuildKit构建Dockerfile，作为构建流程中的关键前端工具，能够有效配合BuildKit提升Dockerfile的构建效率、安全性与灵活性，为开发者提供官方认可的标准化构建方案，适用于各类基于Docker的应用开发与部署场景，确保构建过程的稳定可靠及操作便捷性。
125 次收藏5亿+ 次下载
1 个月前更新
docker/dockerfile-copy
Docker 官方工具与组件镜像
此Docker镜像已被弃用。
1 次收藏5000万+ 次下载
7 年前更新
envoyproxy/ai-gateway-testupstream
envoyproxy
暂无描述
5万+ 次下载
26 天前更新
docker/dockerfile-copy-arches
Docker 官方工具与组件镜像
该Docker镜像已弃用
3.1千+ 次下载
7 年前更新
tontcc/bplus_upstream
tontcc
暂无描述
5万+ 次下载
1 年前更新
wyga/php-upstream
wyga
暂无描述
1万+ 次下载
25 天前更新
镜像拉取常见问题
使用与功能问题
错误码与失败问题
manifest unknown 错误：镜像不存在或标签错误
manifest unknown 错误
TLS/SSL 证书验证失败：Docker pull 时 HTTPS 证书错误
TLS 证书验证失败
DNS 解析超时：无法解析镜像仓库地址或连接超时
DNS 解析超时
410 Gone 错误：Docker 版本过低导致协议不兼容
410 错误：版本过低
402 Payment Required 错误：流量耗尽错误提示
402 错误：流量耗尽
401 UNAUTHORIZED 错误：身份认证失败或登录信息错误
身份认证失败错误
429 Too Many Requests 错误：请求频率超出专业版限制
429 限流错误
Docker login 凭证保存错误：Cannot autolaunch D-Bus（不影响登录）
凭证保存错误
账号 / 计费 / 权限
用户好评
来自真实用户的反馈，见证轩辕镜像的优质服务
oldzhang
运维工程师
Linux服务器
5
"Docker访问体验非常流畅，大镜像也能快速完成下载。"