• 文档
• 教程
• 后端

构建 Docker 镜像时，我们常常需要临时使用 npm 私有源令牌等敏感信息，而一个不经意的ARG传参就可能让令牌永久残留在镜像历史层中。本文对应 nodebestpractices 仓库「Docker 实践」规范第 8.11 条「Clean-out build-time secrets, avoid secrets in args」（规范原文见 sections/docker/avoid-build-time-secrets.french.md，README 汇总见 README.md 第 1553-1561 行）。读完本文，你将理解 Docker 镜像分层机制为什么会让构建期秘密"无处遁形"，并掌握两种经过验证的安全注入方案——BuildKit--secret文件挂载与多阶段构建——可直接复制到你的 Dockerfile 中落地。

一、问题根源：Docker 镜像是"分层历史簿"，构建期秘密无处遁形

原文档开篇就给出了一条容易被忽视的核心事实：Docker 镜像并非一堆文件的简单集合，而是由多层（layers）构成，每一层都会忠实地记录构建期间发生的事情。下图直观展示了这一机制：

图中的image layer: COPY package.json、image layer: COPY ./usr/src/app等标签表明：Dockerfile 中的每一条指令都会生成一个只读镜像层，层的内容在构建结束后被持久保留。这带来一个致命推论：即使你在某个RUN指令中写入秘密文件后又将其删除，该层快照里依然残留着秘密字节；任何人只要对镜像执行docker history，就能像翻历史簿一样逐层还原构建过程。

在 Node.js 最常见的场景中，开发者需要为私有 npm registry 提供认证令牌（npm token）来完成构建期安装。一个看似无害的常规做法是：把令牌作为构建参数（build-time args）传给 Dockerfile。原文档明确指出，这种做法会让令牌可以被以下三类环境轻易提取：

• 开发者本机的 Docker 历史（docker history逐层检索）；
• Docker 镜像仓库（registry）（镜像被推送共享后，任何有权拉取镜像的人都能读取历史层）；
• CI 构建环境（--build-arg通常会出现在 CI 的构建命令与日志中）。

一旦攻击者拿到这个令牌，就相当于获得了向组织私有 npm registry 持续写入的长期权限——而镜像本身可能早已过了需要令牌的阶段，令牌却"留驻"在镜像里遥遥无期。README 对该反模式风险的概括一针见血：

Otherwise:Everyone with access to the CI and docker registry will also get access to some precious organization secrets as a bonus（否则，任何能访问 CI 与 Docker registry 的人，都会顺带拿到一些珍贵的组织秘密）。

作为第一道防线，仓库还配套了「用 .dockerignore 防止秘密泄漏」规范（见 sections/docker/docker-ignore.md，README 第 8.4 条）：开发目录与 CI 目录中常驻.npmrc、.aws、.env等敏感文件，构建上下文会把它们一并拷入镜像。建议把.npmrc、.env、.aws、.git、node_modules等明确列入.dockerignore，让 Dockerfile 只拷贝真正需要的内容。

二、反模式剖析：把 npm token 当作构建参数（ARG）

先看规范中明确标注为 Anti-Pattern 的 Dockerfile，这正是绝大多数团队"看起来没问题"的写法：

FROM node:12-slim ARG NPM_TOKEN WORKDIR /usr/src/app COPY . /dist RUN echo "//registry.npmjs.org/:\_authToken=\$NPM_TOKEN" > .npmrc && \ npm ci --production && \ rm -f .npmrc CMD ["node", "index.js"]

这段 Dockerfile 的两个"陷阱"细节值得逐层拆解：

1. ARG NPM_TOKEN声明本身会进入镜像元数据：ARG指令与ENV、COPY一样会被记录进镜像历史层，通过docker history --no-trunc <image>可以直接看到ARG NPM_TOKEN这条记录；
2. echo写入.npmrc与rm -f .npmrc发生在同一条RUN指令内：正如原文档注释所说，"在同一个 COPY/RUN 指令内删除.npmrc并不会把它从这一层中移除"——RUN层创建时，先执行 echo 写出包含令牌的.npmrc，再执行 rm 删除，但该层最终的快照（layer snapshot）已经包含了写入令牌的那一刻的状态；即便文件被删除，令牌字节依然留在该 RUN 层的文件系统变更记录中。

因此，npm ci --production虽然只安装了生产依赖，但令牌的"幽灵"依然残留在镜像历史中，攻击者用一条docker history命令配合docker export/docker save就能将其还原。这条反模式同时泄漏到三个环境（开发机、registry、CI），属于规范要求坚决规避的做法。

三、方案一：BuildKit--secret文件挂载（零痕迹）

原文档给出的首选方案是 Docker 的--secret构建期秘密特性：秘密以文件形式在构建期间临时挂载，既不会进入最终镜像，也不会进入任何中间镜像与提交历史。该特性在文档撰写时（2020 年 7 月）仍被标记为 experimental，但已足够稳定（"experimental but stable"），如今 BuildKit 已是 Docker 默认构建器，可直接使用。

# syntax = docker/dockerfile:1.0-experimental FROM node:12-slim WORKDIR /usr/src/app COPY package.json package-lock.json ./ RUN --mount=type=secret,id=npm,target=/root/.npmrc npm ci # The rest comes here

逐行要点：

• # syntax = docker/dockerfile:1.0-experimental：声明使用支持RUN --mount的 BuildKit 前端解析器（syntax directive）。该行必须放在 Dockerfile 第一行，并保证构建时启用了 BuildKit（较旧版本 Docker 需设置DOCKER_BUILDKIT=1环境变量）；
• COPY package.json package-lock.json ./：先只拷贝依赖清单再安装，充分利用层缓存（与仓库 sections/examples/dockerfile/Dockerfile 中的缓存策略一致）；
• RUN --mount=type=secret,id=npm,target=/root/.npmrc npm ci：--mount=type=secret表示构建该 RUN 层时临时挂载一个秘密文件；id=npm是秘密标识；target=/root/.npmrc指定挂载位置——npm 默认读取用户主目录下的.npmrc（此处对应 root 用户的~/.npmrc），npm ci会自然使用其中配置的认证令牌。

对应的构建命令需要以--secret传入秘密文件的真实路径：

docker build --secret id=npm,src=.npmrc -t my-node-app .

src=.npmrc指定了宿主机上秘密文件的来源；挂载只在构建该 RUN 层的短暂过程中有效，构建结束后秘密文件从构建环境中消失。规范中引用的博客作者 Alexandra Ulsh 对这一机制给出了权威描述：

In November 2018 Docker 18.09 introduced a new--secretflag fordocker build. This allows us to pass secrets from a file to our Docker builds. These secrets aren't saved in the final Docker image, any intermediate images, or the image commit history. With build secrets, you can now securely build Docker images with private npm packages without build arguments and multi-stage builds.

（2018 年 11 月，Docker 18.09 为docker build引入了新的--secret标志，允许把秘密以文件形式传入构建；这些秘密不会保存在最终镜像、任何中间镜像或镜像提交历史中。有了构建秘密，无需构建参数和多阶段构建即可安全地构建包含私有 npm 包的 Docker 镜像。）

使用该方案时注意：若 Dockerfile 切换到非 root 用户（如USER node），需相应调整target路径为对应用户主目录（如/home/node/.npmrc），确保 npm 能读到挂载的配置文件。

四、方案二：多阶段构建 + ARG（不进最终镜像，本地 history 需清理）

如果构建环境不便启用 BuildKit 特性，原文档提供了第二个安全方案：多阶段构建（multi-stage build）。思路是：在构建阶段使用ARG传入令牌完成依赖安装，然后将仅构建产物与运行所需文件拷贝进最终阶段，令牌与.npmrc均不进入最终镜像。

FROM node:12-slim AS build ARG NPM_TOKEN WORKDIR /usr/src/app COPY . /dist RUN echo "//registry.npmjs.org/:\_authToken=\$NPM_TOKEN" > .npmrc && \ npm ci --production && \ rm -f .npmrc FROM build as prod COPY --from=build /dist /dist CMD ["node", "index.js"]

逐段解读：

• FROM node:12-slim AS build：为构建阶段命名build，ARG NPM_TOKEN在该阶段内声明并生效——注意ARG的作用域仅限声明它的那个阶段，后续prod阶段无法再引用$NPM_TOKEN；
• 构建阶段内：echo将令牌写入.npmrc→npm ci --production完成生产依赖安装 →rm -f .npmrc删除配置文件。这里与原文档反模式的差异在于：之后还有一个独立的最终阶段，最终阶段只通过COPY --from=build /dist /dist拷走构建产物，令牌所在的构建阶段层被丢弃，不会进入最终镜像层；
• FROM build as prod：这是对既有阶段的重命名引用，随后的COPY --from=build从build阶段取文件。最终镜像的层只包含/dist与运行时配置，不含.npmrc，也不含ARG NPM_TOKEN的元数据。

构建命令依然常规使用--build-arg：

docker build --build-arg NPM_TOKEN=<token> -t my-node-app .

需要特别强调的是原文档注释中的一句警示："ARG 与 .npmrc 不会出现在最终镜像中，但可以在 Docker daemon 的未标记（untagged）镜像列表里找到——务必删除这些镜像"。这是因为构建阶段的中间镜像（含令牌的层）会以悬空镜像（dangling/un-tagged image）的形式暂存在本机 Docker daemon 中：

# 查看构建产生的悬空/未标记镜像 docker images -f dangling=true # 清理悬空镜像 docker image prune

规范对该方案的定位是"通常足以满足大多数组织的安全要求"（"typically considered as secured enough for most organizations"）：秘密不会随镜像分发到 registry 与 CI 环境，但会在开发者本机的 Docker 历史中短暂残留，因此构建后及时清理本地中间镜像是该方案不可省略的收尾步骤。

五、仓库落地样板：从真实 Dockerfile 看多阶段构建的完整姿态

仓库在 sections/examples/dockerfile/Dockerfile 中提供了可直接对照的真实多阶段 Dockerfile，展示了"构建阶段安装全部依赖 → 运行时阶段只保留产物与生产依赖"的完整姿态：

# This is a multistage Dockerfile. # In the first stage we install system build dependencies, copy project files and build them # In the second stage, we start fresh and only copy necessary files. We also purge node_modules devDependencies. #### Build stage #### FROM node:14.8.0-alpine AS build # Install system build dependencies (if needed) at the top ✅ See bullet point #8.8 about caching RUN apk add --update --no-cache bash make gcc g++ lcms2-dev libpng-dev autoconf automake # Only copy node dependency information and install all dependencies first COPY --chown=node:node package.json package-lock.json ./ # Install packages using the lockfiles as source of truth ✅ See bullet point #8.5 about npm ci RUN npm ci # Copy source code (and all other relevant files) COPY --chown=node:node src ./src # Build code RUN npm run build #### Run-time stage #### FROM node:14.8.0-alpine as app # Set non-root user and expose port 3000 USER node EXPOSE 3000 WORKDIR /home/node/app # Copy dependency information and build output from previous stage COPY --chown=node:node --from=build package.json package-lock.json ./ COPY --chown=node:node --from=build node_modules ./node_modules COPY --chown=node:node --from=build dist ./dist # Clean dev dependencies ✅ See bullet point #8.5 RUN npm prune --production && npm cache clean --force CMD [ "node", "dist/app.js" ]

这份真实样例与规范方案互相印证了几个关键工程要点：

1. 以锁文件为唯一事实源：两阶段都先拷贝package.json与package-lock.json再安装，使用npm ci（而非npm install）——它强制全新安装、严格校验锁文件，更适合 CI 与 Docker 这类自动化环境（详见 sections/docker/install-for-production.md）；
2. 运行时阶段裁剪依赖：npm prune --production剔除 devDependencies，npm cache clean --force清空 npm 本地缓存——开发依赖会显著扩大容器攻击面并增加体积（仓库规范 sections/docker/clean-cache.md 指出清理缓存可削减通常 10%-50% 的镜像体积）；
3. 非 root 用户运行：USER node降低容器内权限；
4. 最终阶段不携带任何构建秘密：令牌、.npmrc、源码构建工具链均留在构建阶段，最终镜像只含dist、node_modules与依赖清单。

上述依赖裁剪逻辑同样适用于规范中的"多阶段 + ARG"方案——把第 2 条替换为带--secret或ARG的安装步骤，即可在安全注入令牌的同时获得最小化镜像。多阶段构建的更多展开（含 yarn 生态中yarn install --frozen-lockfile的等价做法）可继续阅读 sections/docker/multi_stage_builds.md。

六、三种方案横向对比与选用建议

选用建议：优先使用 BuildKit--secret——它同时消灭了最终镜像与本地历史两个泄漏面，是"无懈可击"（flawless）的方案；在无法启用 BuildKit 的环境中，退而求其次使用多阶段构建，并把"构建后清理本地悬空镜像"写进 CI 收尾步骤；无论如何都不要使用裸ARG传递 npm token。

七、总结

本规范（nodebestpractices 第 8.11 条）给出了一个清晰的安全分级：Docker 镜像分层机制决定了"构建期发生过的一切"都会被层历史记录；因此，构建期需要的 npm token 等秘密应遵循以下原则：

1. 能不用就不用：用.dockerignore隔离.npmrc、.env、.aws等敏感文件，从源头上不让秘密进入构建上下文；
2. 要用就走挂载：首选 BuildKit--secret文件挂载，零痕迹完成npm ci私有源认证；
3. 挂载不可用才用多阶段：ARG+ 多阶段构建确保秘密不进入最终镜像，但务必清理本机 daemon 中残留的悬空中间镜像；
4. 配合最小化运行环境：npm ci+npm prune --production+npm cache clean --force+ 非 root 用户，让最终镜像既无秘密又瘦身。

规范原文与仓库配套资源可供继续深挖：规范原文、README 第 8.11 条（第 1553-1561 行）、多阶段构建展开、真实多阶段 Dockerfile 样例、生产依赖裁剪与.dockerignore 防线。

• 文档
• 教程
• 后端