docker-best-practices

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 传输时间急剧增加。