Docker build secrets 怎样避免把凭据写入镜像层

如果构建时需要访问私有 npm 仓库、私有 Git 仓库或云存储，最容易踩的坑是把 Token 写进 ARG、ENV，或者先复制到镜像再删除。删除文件并不等于清掉历史层，后续构建日志也可能把参数打印出来。更稳妥的做法是用 Docker BuildKit 的 secret mount：在命令行传入一个 secret，在 Dockerfile 的单个 RUN 步骤中临时读取，用完后不把它作为镜像文件保存。

官方地址：https://docs.docker.com/build/building/secrets/

记住两件事：凭据从构建客户端传入，Dockerfile 用 RUN --mount=type=secret 消费；挂载范围只覆盖需要它的构建步骤。这样可以避免凭据成为普通构建参数或最终镜像内容，但仍要避免把它打印到日志、复制到产物或写入缓存。

先把会留下痕迹的传参方式排除

ARG 和 ENV 适合普通构建配置，不适合密码、API Token 或私有仓库凭据。Docker 官方文档说明，这些值可能持久存在于最终镜像中；secret mount 则把敏感值以文件或环境变量的形式提供给构建容器。

这个区分决定了后面的操作路径：普通参数是“把值交给镜像构建”，secret mount 是“把值临时交给一个构建动作”。

Dockerfile 里把凭据限制在一个 RUN 步骤

先给需要凭据的指令加上挂载声明。默认情况下，secret id 为 private_token 时，构建容器内的文件路径是 /run/secrets/private_token。下面的示例只把它交给私有包下载动作，不把内容写入新的文件层。

# syntax=docker/dockerfile:1
FROM alpine

# 只让当前 RUN 临时看到 private_token，避免把凭据写成 ENV 或 ARG
RUN --mount=type=secret,id=private_token \
    TOKEN_FILE=/run/secrets/private_token \
    sh -eu -c 'test -s "$TOKEN_FILE" && wget --header="Authorization: Bearer $(cat "$TOKEN_FILE")" https://packages.example.invalid/private.tar.gz -O /tmp/private.tar.gz'

# 只复制构建产物，不能把 /run/secrets 下的内容复制进镜像
COPY app /app

这里的关键不是命令本身，而是边界：private_token 只绑定这条 RUN。如果构建任务必须把凭据作为环境变量交给工具，可以显式使用 env；如果工具要求固定文件名，则使用 target。

# 通过 env 把临时 secret 暴露给当前命令，命令结束后不再提供
RUN --mount=type=secret,id=registry_token,env=REGISTRY_TOKEN \
    sh -eu -c 'test -n "$REGISTRY_TOKEN" && npm ci'

# 通过 target 挂到工具约定的位置，uid/gid 只在非 root 场景按需设置
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    npm ci

从命令行传入文件或环境变量

Dockerfile 里声明了 id，还需要在构建命令中提供同名 secret。文件来源适合本机已有的凭据文件；环境变量来源适合 CI 运行器已经注入的值。两者都不应把真实值直接写在命令行参数里。

# 从本机凭据文件读取，id 必须与 Dockerfile 的 secret id 一致
docker build \
  --secret id=private_token,src="$HOME/.config/example/token" \
  -t demo/private-fetch:dev .

# 从环境变量读取，构建命令本身只暴露变量名
export REGISTRY_TOKEN='请替换为运行环境中的真实凭据'
docker build \
  --secret id=registry_token,env=REGISTRY_TOKEN \
  -t demo/private-build:dev .

如果只在私有 Git 仓库拉取阶段需要 SSH Agent，应改用 --ssh 和 Dockerfile 的 RUN --mount=type=ssh，不要把私钥当普通文本 Secret 复制进镜像。无论使用哪一种挂载，都要让需要凭据的命令在同一条 RUN 内完成。

GitHub Actions 中把仓库 Secret 传给构建

在 GitHub 仓库页面按这个路径进入：Settings → Security → Secrets and variables → Actions → Secrets → New repository secret。Name 填 REGISTRY_TOKEN，Secret 填真实值后点击 Add secret。只有具备相应仓库写入权限的成员才能完成这一步。

然后在工作流中，把 GitHub Secret 映射为 Docker build secret。Docker 的 docker/build-push-action 支持 secrets、secret-envs 和 secret-files；下面使用最直观的 secrets 形式。

name: build-private-dependency
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Build image with a temporary secret
        uses: docker/build-push-action@v7
        with:
          context: .
          push: false
          tags: demo/private-build:ci
          # 只传 secret 的引用关系，不在 YAML 中写真实值
          secrets: |
            registry_token=${{ secrets.REGISTRY_TOKEN }}

Dockerfile 对应写成：

# syntax=docker/dockerfile:1
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./

# 只让 npm 安装步骤读取临时 Token，安装完成后不保存 Token
RUN --mount=type=secret,id=registry_token,env=REGISTRY_TOKEN \
    npm ci

COPY . .

用四个状态确认凭据没有进入镜像层

1. 入口状态：凭据只出现在本机文件、CI Secret 或运行器环境变量中，Dockerfile 和 workflow 不出现真实值。
2. 挂载状态：需要凭据的 RUN 明确写出 --mount=type=secret，且 id 与命令行或 Action 的映射一致。
3. 产物状态：构建步骤只生成需要的依赖或编译产物，不把 /run/secrets、Token 文件或带 Token 的配置复制到最终阶段。
4. 日志状态：不要用 cat、echo 或调试参数输出 Secret；GitHub 文档也提醒命令行进程可能暴露敏感参数，优先使用环境变量或 stdin。

常见的“看起来用了 Secret 但仍然泄露”的情况有三种：把 Secret 拼进下载 URL、在同一个步骤打印完整环境、或者把私有配置生成到最终镜像。Secret mount 只负责提供临时输入，不能替你审查命令输出和构建产物。

常见问题

为什么挂载了 Secret 仍然读不到？

先对照三处名称：命令行的 id、Dockerfile 的 id、GitHub Action 的 secret 映射名。文件模式默认检查 /run/secrets/；如果使用 target 或 env，则应检查自定义路径或环境变量名。

删除凭据文件后就安全了吗？

不能这样假设。如果凭据先通过 COPY、ARG 或普通 RUN 写入层，再在后续层删除，历史层、缓存或日志仍可能保留线索。把凭据改为 secret mount，并让依赖安装和清理在同一条需要凭据的构建步骤中完成。

小结：把 Secret 当作某个构建动作的临时输入；用 RUN --mount=type=secret 或 SSH mount 限定范围；最后同时检查 Dockerfile、workflow、构建日志和最终产物，才能真正避免凭据写入镜像层。