Wade-DevCode Docker 最佳实践
何时用
- 新写或修改任何 Dockerfile。
- 把现有应用容器化时做方案设计。
- 发现镜像体积异常大、构建反复拉依赖、容器以 root 身份运行时。
- 做镜像安全扫描前的自查。
核心规则
1. 多阶段构建 + 锁定基础镜像版本
规则： 用多阶段构建（multi-stage build）将编译工具与运行时分离；最终阶段只保留运行所需；基础镜像使用 slim 或 alpine 变体并固定具体版本标签，不用 latest。
为什么： AI 生成 Dockerfile 时惯用 FROM node:latest 并把构建工具一并打进最终镜像，导致：镜像体积从几十 MB 膨胀到数百 MB，latest 标签在不同时间拉取内容不同使构建不可重复，安全扫描面随之大幅增加。曾见过把 gcc、make、完整 Python 开发头文件留在生产镜像里的真实事故。
怎么做：
FROM node:20-alpine AS builder做编译，FROM node:20-alpine AS runtime只拷产物。- 用
COPY --from=builder /app/dist ./dist跨阶段拷贝，其余一概不带。 - 在 CI 中定期用
docker scout或trivy扫镜像，升版本时同步更新标签。
2. 善用层缓存：先装依赖再拷源码
规则： 把"依赖清单文件"（package.json、requirements.txt、go.mod 等）单独先 COPY 进去并执行安装，再 COPY 源码；源码修改不会使依赖层失效。
为什么： AI 最常见的写法是 COPY . . 然后 RUN npm install——每次改一行业务代码，整个依赖安装层失效，CI 上几分钟的 npm install 变成每次必跑。在依赖上百包的项目里这是显而易见的浪费，但 AI 很少主动意识到。
怎么做：
# 正确顺序：依赖清单 → 安装 → 源码
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY src/ ./src/
- 每次只有
package.json变化才重新跑npm ci，改源码直接命中缓存。 - monorepo 场景先
COPY根package.json与各 workspace 的package.json，再统一安装。
3. 不以 root 运行；密钥不进镜像
规则： 用 USER 指令切换到无特权用户；通过 BuildKit secret 或运行时环境变量传入凭据，不用 ENV/ARG 把密钥固化进镜像层。
为什么： AI 生成的 Dockerfile 几乎从不加 USER 指令，容器进程默认以 root 运行，一旦容器被攻破即获宿主机高权限。同样，AI 会把 ARG NPM_TOKEN=xxx 写进 Dockerfile 并 RUN npm install，虽然 ARG 不出现在 docker inspect 环境变量里，但该层的文件系统快照仍可被 docker history 提取，密钥实质上已泄露。
怎么做：
# 创建专用用户
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser
# 用 BuildKit secret 挂载，不写进层
RUN --mount=type=secret,id=npm_token \
NPM_TOKEN=$(cat /run/secrets/npm_token) npm ci
- 运行时凭据通过
docker run --env-file或 Kubernetes Secret 注入，不烘进镜像。
4. 一容器一职责；用 .dockerignore 瘦身
规则： 单个容器只运行一个主进程（PID 1）；项目根目录维护 .dockerignore，至少排除 .git、node_modules、测试目录、本地配置文件等。
为什么： AI 有时会在同一容器里启动 Nginx + App Server + Cron，把运维复杂度全转移到容器内，违背容器设计原则，日志、健康检查、横向扩展都难以独立处理。同样，AI 不会主动创建 .dockerignore，导致 COPY . . 把几百 MB 的 node_modules 或整个 .git 历史拷入构建上下文，build context 传输时间急剧增加。
怎么做：
.git
node_modules
**/__tests__
**/*.test.ts
.env*
*.log
dist
- 多进程需求用 docker-compose 拆成独立服务，而不是在容器内用 supervisor 启多进程。
5. 健康检查与优雅退出（处理 SIGTERM）
规则： Dockerfile 内声明 HEALTHCHECK；应用代码监听 SIGTERM 并完成正在处理的请求后再退出，不强制杀进程。
为什么： AI 生成的镜像几乎不带 HEALTHCHECK，Kubernetes/Compose 只能靠进程存活判断容器状态，启动期间流量就被打过来导致报错。同样，AI 生成的 Node/Python 应用很少处理 SIGTERM，容器被 docker stop 时直接 SIGKILL，正在处理的请求被强制中断，数据库事务可能未提交。
怎么做：
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
CMD wget -qO- http://localhost:8080/health || exit 1
// Node.js 优雅退出示例
process.on('SIGTERM', async () => {
await server.close(); // 停止接收新连接
await db.end(); // 释放数据库连接池
process.exit(0);
});
- 日志统一输出到 stdout/stderr（
console.log），不写文件，让容器运行时负责收集。
正例 / 反例
反例：单阶段、root 运行、缓存失效、无健康检查
# 反例
FROM node:latest # ❌ 不锁版本
WORKDIR /app
COPY . . # ❌ 先拷所有文件，层缓存极易失效
RUN npm install # ❌ 每次改任意文件都重跑
ENV JWT_SECRET=supersecret123 # ❌ 密钥固化进镜像层
EXPOSE 3000
CMD ["node", "server.js"] # ❌ root 用户运行，无 HEALTHCHECK
正例：多阶段、非 root、缓存友好、健康检查完备
# ---- 构建阶段 ----
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./ # ✅ 先拷清单
RUN npm ci # ✅ 只在依赖变化时重跑
COPY src/ ./src/
RUN npm run build
# ---- 运行阶段 ----
FROM node:20-alpine AS runtime
WORKDIR /app
RUN addgroup -S app && adduser -S app -G app # ✅ 非 root 用户
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
USER app # ✅ 切换到无特权用户
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
CMD wget -qO- http://localhost:3000/health || exit 1 # ✅ 健康检查
EXPOSE 3000
CMD ["node", "dist/server.js"]
自查清单
- 基础镜像使用了具体版本标签（如
node:20-alpine），没有用latest。 - 使用了多阶段构建，最终镜像不含编译工具和开发依赖。
- 依赖清单在源码之前单独
COPY并安装，层缓存策略正确。 - 容器进程以非 root 用户运行（已有
USER指令）。 - 没有通过
ENV/ARG或COPY把密钥固化进任何镜像层。 - 项目根目录有
.dockerignore，排除了.git、node_modules、.env*等无关文件。 - Dockerfile 声明了
HEALTHCHECK，应用代码处理了SIGTERM优雅退出。