Docker BuildKit 的 --secret 机制是官方唯一推荐的构建阶段安全消费密钥方式，通过内存挂载 /run/secrets/ 实现临时可见、进程退出即销毁，不写入镜像层、不暴露于日志或 history。

用 Docker BuildKit 的 `--secret` 机制，是在构建阶段安全消费私密密钥的唯一官方推荐方式。它不把密钥写进镜像，也不出现在构建日志或历史里，只在指定 `RUN` 命令运行时，以内存文件形式挂载（路径固定为 `/run/secrets/`），进程一结束就自动销毁。

确保 BuildKit 已启用

从 Docker 20.10 起默认支持，但需显式开启：

• 设置环境变量：export DOCKER_BUILDKIT=1
• 或在构建命令中加前缀：DOCKER_BUILDKIT=1 docker build ...
• 验证是否生效：执行 docker build --help，若看到 --secret 选项即已就绪

准备本地凭据文件

密钥必须存为本地普通文件（不能是环境变量或硬编码），权限严格设为 600：

• 例如 GitHub SSH 私钥：~/.ssh/id_rsa_github
• 例如私有 PyPI 凭据：~/.netrc，内容格式为：
  machine pypi.example.com login myuser password mypass
• 执行：chmod 600 ~/.ssh/id_rsa_github，否则挂载会失败

在 Dockerfile 中挂载并使用

不能用 COPY、ARG 或 ENV，必须用 RUN --mount=type=secret 显式挂载：

Docker Desktop 4.96.1

下载

• 挂载路径固定为 /run/secrets/，不可自定义
• 每个需要密钥的 RUN 都得单独挂载，不能跨指令复用
• 示例（克隆私有 Git 仓库）：
  RUN --mount=type=secret,id=ssh_key,dst=/tmp/id_rsa,mode=0600 \
mkdir -p /root/.ssh && \
cp /tmp/id_rsa /root/.ssh/id_rsa && \
chmod 600 /root/.ssh/id_rsa && \
ssh-keyscan github.com >> /root/.ssh/known_hosts && \
git clone git@github.com:org/repo.git /app

构建时绑定密钥文件

执行构建命令，把本地文件映射到 secret ID：

• docker buildx build \
• --secret id=ssh_key,src=$HOME/.ssh/id_rsa_github \
• -t myapp:latest .
• 构建完成后可验证安全性：
  • docker history myapp:latest 不应出现密钥相关操作
  • docker run --rm myapp:latest ls /run/secrets/ 应报错 “No such file or directory”