BuildKit --secret 是唯一官方推荐的构建时密钥注入机制，因它通过内存挂载（tmpfs）实现临时可见、进程退出即销毁，不残留任何镜像层；而 ARG/ENV/COPY 等方式均会将密钥固化在历史层中，可通过 docker history 或镜像解包还原。
BuildKit --secret 是目前 Docker 官方唯一推荐的、能在构建阶段临时注入敏感凭证且不残留进镜像层的安全机制。它不是“可选方案”，而是硬性要求——其他方式（如 ARG、COPY、环境变量）都会导致密钥固化在历史层中，一查即得。
为什么必须用 BuildKit + --secret，而不是 ARG 或 ENV？
因为 ARG 和 ENV 的值会完整保留在构建层的元数据或文件系统中。哪怕你后续 RUN rm -f ~/.ssh/id_rsa，该层仍存有原始私钥内容，执行 docker history --no-trunc your-image 或解包镜像就能还原。而 --secret 通过内存挂载（tmpfs）实现，仅在 RUN --mount=type=secret 进程生命周期内可见，进程退出后自动销毁，不会写入任何镜像层。
常见错误现象包括：
- CI 日志里明文打印出
SSH_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----... -
docker inspect your-image中看到Env或Args字段含密钥片段 - 用
trivy image --scanners secret your-image扫出私钥格式字符串
Dockerfile 中正确使用 RUN --mount=type=secret
关键点是：不能直接读取 secret 文件路径，必须显式挂载并指定目标路径；且挂载仅对当前 RUN 有效。
示例（克隆 GitHub 私有仓库）：
# 启用 BuildKit 模式（Dockerfile 开头无需写，但构建时需开启） FROM alpine:latest RUN apk add --no-cache git openssh-client <h1>挂载 secret 并配置 SSH</h1><p>RUN --mount=type=secret,id=ssh_key,uid=0,gid=0,mode=0600 \ mkdir -p /root/.ssh && \ cp /run/secrets/ssh_key /root/.ssh/id_rsa && \ chmod 600 /root/.ssh/id_rsa && \ ssh-keyscan github.com >> /root/.ssh/known_hosts && \ git clone git@github.com:your-org/private-repo.git /app </p>
说明：
-
id=ssh_key必须与构建命令中的--secret id=ssh_key一致 -
mode=0600强制设置权限，避免因默认挂载权限被拒绝 -
uid=0,gid=0确保 root 用户可读（alpine 默认无非 root 用户） - 挂载路径固定为
/run/secrets/，不可自定义
构建命令必须显式启用 BuildKit 并传入 --secret
旧版 Docker 默认禁用 BuildKit，必须手动开启，否则 --mount=type=secret 会被忽略且无报错。
正确命令：
DOCKER_BUILDKIT=1 docker build \ --secret id=ssh_key,src=$HOME/.ssh/id_rsa \ -t myapp .
注意：
-
src=指向宿主机上的私钥文件，**不能是目录或通配符** - 若用 CI 环境（如 GitHub Actions），应从 secrets 上下文读取，而非硬编码路径：
--secret id=ssh_key,src=/dev/stdin - 不要混用
--build-arg和--secret：前者用于非敏感构建参数（如版本号），后者专用于凭证 - 多个 secret 需重复写多个
--secret参数，不能合并
常见陷阱与验证方式
最容易被忽略的是「构建缓存污染」和「权限继承」问题。
比如：
- 第一次构建用了
--secret，第二次没传但缓存命中，RUN --mount行仍会静默跳过，看似成功实则没挂载 —— 解决办法是加--no-cache或确保每次构建都带完整--secret - 基础镜像中已有
/root/.ssh目录且权限宽松，挂载后id_rsa文件可能被覆盖但父目录权限未改，导致 SSH 拒绝连接 —— 应在挂载前RUN mkdir -p /root/.ssh && chmod 700 /root/.ssh - 验证是否生效：构建后运行容器，检查
/run/secrets/是否为空（应该空），再确认构建阶段是否真能完成git clone（最直接）
真正安全的构建，不是“看起来删了密钥”，而是“密钥根本没机会落盘”。--secret 是唯一做到这点的官方机制，其余都是掩耳盗铃。
