容器与云原生 / 系统课时

安全使用构建密钥

安全使用构建密钥

镜像构建经常需要访问私有仓库、包源或下载服务,但凭据不能通过 ARG、ENV 或 COPY 固化进镜像。BuildKit 的 secret mount 会在单个 RUN 步骤中临时挂载密钥,用完即移除,适合处理构建期认证。

学习目标

  • 能使用 docker build --secret 向构建过程传入临时凭据。
  • 能在 Dockerfile 中用 RUN --mount=type=secret 读取密钥而不写入镜像层。
  • 能检查最终文件和镜像历史,确认密钥没有被持久化。

为什么构建参数不是密钥容器

ARG 适合普通构建参数,不适合密码、令牌和私钥。把密钥写进 Dockerfile、构建参数、环境变量声明或构建上下文,都可能被日志、历史记录、缓存或误复制文件暴露。

BuildKit secret 的路径不同:密钥由构建客户端提供,只在指定 RUN 指令执行期间挂载到构建容器,默认位置是 /run/secrets/<id>。该挂载不会作为普通文件提交进镜像层。

BuildKit 构建密钥的临时挂载与消失过程

用 secret mount 完成一次构建

下面的示例不访问外网,而是让构建步骤确认密钥存在并生成非敏感结果,便于直接验证“能读取但不持久化”。真实项目只需把这一步替换为访问私有包源或制品仓库的命令。

创建 Dockerfile:

dockerfile
# syntax=docker/dockerfile:1
FROM alpine:3.24 AS build
RUN --mount=type=secret,id=build_token \
    test -s /run/secrets/build_token && \
    printf 'secret consumed\n' > /result.txt

FROM alpine:3.24
COPY --from=build /result.txt /result.txt
CMD ["cat", "/result.txt"]

在本地示例中用环境变量提供一个无害演示值。真实 CI 中应由平台的 secret store 注入 BUILD_TOKEN,不要把真实令牌硬编码进脚本或仓库。

bash
export BUILD_TOKEN='demo-token'
docker build --secret id=build_token,env=BUILD_TOKEN -t secret-demo .
unset BUILD_TOKEN
docker run --rm secret-demo

预期输出:

text
secret consumed

构建日志中的步骤编号和缓存状态可能不同,但运行容器时只应看到非敏感结果。

验证密钥没有进入镜像

先检查最终容器中是否存在默认 secret 路径,再检查镜像历史中是否出现演示令牌。下面的判断会把可能变化的底层命令结果归一化成固定文本。

bash
docker run --rm --entrypoint sh secret-demo -c 'test ! -e /run/secrets/build_token && echo "secret file absent"'
if docker history --no-trunc secret-demo | grep -Fq 'demo-token'; then
  echo "secret leaked"
else
  echo "secret not found in history"
fi

预期输出:

text
secret file absent
secret not found in history

这两个检查分别验证“挂载文件没有进入最终镜像”和“密钥值没有直接出现在镜像历史中”。真实项目还应扫描最终产物,因为如果构建脚本主动把密钥写进配置、缓存或生成文件,secret mount 无法阻止该文件被后续 COPY --from= 带走。

正确处理认证边界

访问私有包仓库时,应让包管理器在同一个 RUN 中读取 secret,并在该步骤内完成所有需要认证的操作。不要先把 secret 复制到普通路径,再在后续层删除;“删除”只会产生新的文件系统状态,不能把已经进入历史层的敏感内容变成从未存在。

如果认证方式使用 SSH 私钥,应优先考虑 BuildKit 的 SSH mount;如果服务接受令牌或配置文件,则使用 secret mount。两者的共同原则都是让凭据只存在于真正需要它的构建步骤,并确保最终产物本身不携带凭据。

让失败尽早暴露

密钥 ID 写错、未提供或权限不匹配时,构建应该立即失败,而不是悄悄改用匿名访问。示例中的 test -s 就承担了最小前置检查;真实命令也应在认证失败时返回非零状态。

在 CI 中还应避免开启会打印完整命令或环境变量的调试模式。安全构建的目标不是“最后删除密钥”,而是从一开始就不让密钥成为镜像层、普通构建参数或构建上下文的一部分。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

安全使用构建密钥

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通