Docker构建阶段使用secret mount

Docker 构建阶段如果要下载私有 npm 包、读取云服务配置或使用内部证书，最容易踩的坑是把令牌写进 ARG、ENV 或普通文件层。这样做会让敏感值出现在构建历史、缓存或最终镜像的可追踪信息里。

更合适的做法是使用 BuildKit 的 secret mount：客户端通过 --secret 提供一个 secret，Dockerfile 只在需要的 RUN 指令中用 --mount=type=secret 临时读取它。指令结束后，挂载点不作为最终镜像内容保留。

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

本文使用虚构的 npmrc 文件名和占位值演示，不放入真实令牌。文章中的界面图是原创操作说明图，不是 Docker Desktop 或终端截图。

一、先确认 secret mount 解决的是什么问题

ARG 和 ENV 适合传递普通构建参数，例如版本号或目标平台；它们不适合承载密码、API Token、私有仓库配置等敏感信息。构建命令中的 --secret 负责把来源交给构建器，Dockerfile 中的 RUN --mount=type=secret 负责决定哪一条指令可以看见它。

二、准备 secret 来源并绑定 id

先在构建客户端准备一个只用于示例的文件。文件内容可以是私有包管理器需要的配置，但不要把真实凭据提交到代码仓库。下面的命令只创建占位内容，注释说明了它与后续 id=npmrc 的对应关系。

# 创建仅供本地示例使用的占位配置，不要写入真实令牌
printf '%s\n' '//registry.example.invalid/:_authToken=placeholder' > ./build-npmrc.example

# 通过 id 把来源文件命名为 npmrc，再把当前目录作为构建上下文
docker buildx build \
  --secret id=npmrc,src=./build-npmrc.example \
  -t demo/private-dependency:local .

这里的 id=npmrc 是构建器内部的标识，不要求和本地文件名相同；src 才是客户端上的来源文件。若使用环境变量作为来源，也可以显式写成 --secret id=npmrc,env=NPMRC_CONTENT，避免把内容写入命令行参数。

三、在 Dockerfile 的 RUN 中使用 secret mount

Dockerfile 需要使用支持 RUN --mount 的语法，并在需要读取私有配置的那一个 RUN 上声明 secret。下面的例子把 secret 挂载到 npm 默认读取的位置，安装过程结束后再复制业务源码。

# syntax=docker/dockerfile:1
FROM node:20-alpine

# 固定工作目录，避免命令在未知目录中读取文件
WORKDIR /app

# 先复制依赖清单，减少普通依赖层的重复构建
COPY package*.json ./

# secret 只在 npm ci 这条 RUN 指令中可见，不复制到镜像层
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc,required=true \
    npm ci

# 业务源码不应包含凭据文件
COPY . .
RUN npm run build

重点有三个：id=npmrc 必须与构建命令的 id 一致；target 决定容器内的读取路径；required=true 会在 secret 没有被提供时直接让这条指令失败，避免构建误用匿名源。

如果工具默认读取 /run/secrets/，也可以不写 target。只有在程序要求固定文件名时，才把它映射到 /root/.npmrc 这样的目标路径。

四、在 Compose 中把 secret 授权给指定服务

如果项目通过 Compose 统一描述构建过程，可以在顶层声明 secret 的来源，再在具体服务的 build.secrets 中授权。顶层声明本身不等于所有服务都能读取，服务级配置仍然要明确写出。

services:
  frontend:
    build:
      context: .
      # 只把 server-npmrc 授权给 frontend 的构建阶段
      secrets:
        - server-npmrc

secrets:
  # 示例文件不含真实凭据，生产环境请使用受控的密钥文件来源
  server-npmrc:
    file: ./build-npmrc.example

Dockerfile 侧的 id 要和 Compose 传入的 secret 名称保持一致。例如上面的 Compose 配置对应 RUN --mount=type=secret,id=server-npmrc,target=/root/.npmrc,required=true npm ci。不要只改 Compose 的名字而忘记同步 Dockerfile。

五、非 root 用户和环境变量挂载怎么处理

secret 文件默认通常以 root 可读的权限挂载。如果 RUN 指令已经切换到非 root 用户，需要设置挂载文件的 uid、gid 或 mode，或者把读取动作放在仍有权限的构建阶段。

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

# node 用户的 UID/GID 需要能读取临时 secret 文件
USER node
RUN --mount=type=secret,id=npmrc,target=/home/node/.npmrc,uid=1000,gid=1000,mode=0400,required=true \
    npm ci

某些工具不读取配置文件，而是从环境变量读取凭据，可以使用 env 把 secret 映射为一次性的环境变量。若同时指定 target 和 env，同一个 secret 可以同时以文件和环境变量形式提供。

# 把 id 为 registry-token 的 secret 映射为本条 RUN 的环境变量
RUN --mount=type=secret,id=registry-token,env=REGISTRY_TOKEN,required=true \
    ./scripts/fetch-private-package.sh

六、常见问题与排查顺序

1. 报 secret not found 或构建没有读取到值

先对照三处名称：命令行 --secret id=...、Dockerfile 的 id=...、Compose 的服务级 secret 名称。然后确认 src 文件路径是相对于当前执行目录解析的，且构建命令确实使用了支持 BuildKit 的构建器。

2. 文件存在但非 root 用户读不到

检查 target 是否落在当前用户可访问的目录，再给挂载选项设置匹配的 uid、gid 和 mode。不要为了绕过权限把 secret 复制到普通工作目录，复制会破坏临时挂载的边界。

3. 构建成功但仍然担心密钥泄漏

检查脚本是否把 secret 内容写入生成物、日志、缓存目录或构建产物。secret mount 只控制挂载本身，不会替应用脚本清理它主动写出的文件；不要在 RUN 中执行会打印令牌的调试命令。

4. 把 secret 写进 ARG 为什么不推荐

Docker 官方的构建检查会把疑似敏感的 ARG 或 ENV 标记为不安全模式。构建参数的值可能出现在历史或证明信息中，因此应改成 secret mount，并把 secret 只授权给需要的指令。

七、最后确认配置是否完整

可以用下面这份清单做配置确认：来源文件不在仓库中；构建命令提供了 secret；Dockerfile 的 id 与来源一致；真正读取密钥的只有目标 RUN；非 root 场景设置了访问权限；构建脚本没有把内容打印或复制到产物。

一句话记忆：客户端用 --secret 提供，Dockerfile 用 RUN --mount=type=secret 消费，Compose 用服务级 build.secrets 控制授权。 这三个位置的名称和路径对齐后，构建密钥就能保持在构建阶段的最小可见范围内。

相关问题

• Docker secret mount 和 SSH mount 有什么区别？前者适合临时文件或环境变量，后者更适合把 SSH agent 或私钥能力交给构建过程。
• secret mount 可以用于 COPY 吗？普通 Dockerfile 的 secret 消费点是带 mount 的 RUN；需要远程私有上下文时应按 Docker 官方的 Git 认证 secret 方案处理。
• 为什么不用 ENV TOKEN=...？因为环境变量会进入镜像配置或构建链路，不适合作为构建期敏感信息通道。