Docker development optimizer

何时使用

当用户出现以下意图时使用本技能：

• 优化 Dockerfile（体积大、构建慢、缓存频繁失效）
• 新建或改进 docker-compose 编排
• 落地多阶段构建（multi-stage）
• 审计容器/镜像安全、收敛攻击面
• 任何涉及 Dockerfile、compose、镜像体积、构建缓存、容器安全的请求

只要用户有 Dockerfile 或想把项目容器化，即适用。

不该用的边界：

• Kubernetes / Helm 编排、Pod 调度 → 不在本技能范围。
• CI/CD 流水线搭建与部署 → 转「CI/CD 流水线」类技能；本技能只负责把容器构建好。
• 应用层漏洞（SQL 注入、XSS 等）→ 转应用安全技能；本技能只覆盖容器层安全。
• 不是 Docker 入门教程，而是一套关于「怎么构建不浪费时间、空间、攻击面的容器」的明确决策。

步骤

本技能有三条工作线，按用户诉求选用。

A. Dockerfile 优化

1. 分析现状：读 Dockerfile，识别基础镜像及其体积，统计层数（每个 RUN/COPY/ADD = 1 层），找反模式。
2. 按四类清单优化：
   • 基础镜像：用固定 tag（生产禁用 :latest）；优先 slim/alpine；CI 中可钉 digest image@sha256:...；按运行时实际需要选底座（编译后二进制别用 python:3.12）。
   • 分层：相关 RUN 用 && \ 合并；变更频率低的层放前面（依赖在源码之前）；包管理缓存在同一 RUN 内清理；用 .dockerignore 排除无关文件；构建依赖与运行依赖分离。
   • 构建缓存：先 COPY 依赖清单（package.json / requirements.txt / go.mod）再 COPY 源码；依赖安装独立成层；用 BuildKit 缓存挂载 --mount=type=cache；避免在装依赖前 COPY . .。
   • 多阶段：阶段一构建（完整 SDK/构建工具/dev 依赖），阶段二运行（最小底座、仅生产产物），COPY --from=builder 只取需要的；最终镜像不含构建工具、源码、dev 依赖。
3. 产出优化后的 Dockerfile，对每个关键决策加行内注释，并给出预估体积下降。
4. 校验：python3 scripts/dockerfile_analyzer.py Dockerfile。

B. docker-compose 编排

1. 识别服务：应用（web/API/worker）、数据库、缓存、队列、反向代理。
2. 套用最佳实践：
   • 服务：depends_on 配 condition: service_healthy；每个服务加 healthcheck；设资源上限 mem_limit/cpus；持久数据用命名卷；钉镜像版本。
   • 网络：显式声明网络（别依赖默认）；前后端网络分离；只暴露需外部访问的端口；纯内网用 internal: true。
   • 环境变量：机密用 env_file 而非内联 environment；.env 不入库（加 .gitignore）；用 ${VAR:-default} 变量替换；记录所有必需变量。
   • 开发 vs 生产：用 profiles 或 override 文件区分；开发用 bind mount 热重载、开调试端口；生产用命名卷、关调试端口、restart: unless-stopped。
3. 产出 docker-compose.yml（含 healthcheck/网络/卷）+ 文档化的 .env.example。
4. 校验：python3 scripts/compose_validator.py docker-compose.yml（可加 --strict 把告警视为失败）。

C. 容器安全审计

逐项过 Dockerfile 与运行时清单（见下方注意事项的高危表），按严重级别（Critical/High/Medium/Low）出报告，每条给修复建议，结尾统计各级别数量。

指令

# Dockerfile 静态分析（层数、反模式、安全问题，15+ 规则）
python3 scripts/dockerfile_analyzer.py Dockerfile
python3 scripts/dockerfile_analyzer.py Dockerfile --output json
python3 scripts/dockerfile_analyzer.py Dockerfile --security

# compose 校验（依赖、健康检查、网络、卷、端口冲突、最佳实践评分）
python3 scripts/compose_validator.py docker-compose.yml
python3 scripts/compose_validator.py docker-compose.yml --strict

# 启用 BuildKit（缓存挂载、并行阶段的前提）
export DOCKER_BUILDKIT=1
docker build .

# 用 BuildKit secret 注入机密（不落入镜像层）
docker build --secret id=api_key,src=./api_key.txt .

示例

多阶段构建模板（保留源中三种关键范式）。

Go / Rust / C++（编译型 → distroless）：

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /app/server ./cmd/server

FROM gcr.io/distroless/static-debian12
COPY --from=builder /app/server /server
USER nonroot:nonroot
ENTRYPOINT ["/server"]

Node.js / TypeScript（deps → builder → runtime 三段）：

FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --production=false

FROM deps AS builder
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
COPY --from=builder /app/dist ./dist
COPY --from=deps /app/node_modules ./node_modules
COPY package.json ./
USER appuser
EXPOSE 3000
CMD ["node", "dist/index.js"]

Python（slim，需 glibc 的 C 扩展场景）：

FROM python:3.12-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

FROM python:3.12-slim
WORKDIR /app
RUN groupadd -r appgroup && useradd -r -g appgroup appuser
COPY --from=builder /install /usr/local
COPY . .
USER appuser
EXPOSE 8000
CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

BuildKit 缓存挂载（跨构建复用下载缓存）：

RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

健康检查（HTTP 服务）：

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

注意事项

不待用户开口就主动提示（Proactive Triggers）：

• 用了 :latest → 建议钉到具体版本 tag。
• 没有 .dockerignore → 创建一个，至少含 .git、node_modules、__pycache__、.env。
• 装依赖前就 COPY . . → 缓存被打穿，重排为先装依赖。
• 以 root 运行 → 加 USER 指令，生产无例外。
• 机密写进 ENV / ARG → 改用 BuildKit secret 挂载，绝不把机密烤进层。
• 镜像超过 1GB → 必须多阶段构建，生产镜像没理由这么大。
• 没有 healthcheck → 加上，编排器（Compose、K8s）靠它管理生命周期。
• apt-get 未在同层清理 → 同一个 RUN 内 rm -rf /var/lib/apt/lists/*。

高危安全项（审计速查）：

• 容器以 root 运行（Critical）→ 创建用户后 USER nonroot，或在 compose 设 user。
• 机密在 ENV/ARG（Critical）→ --mount=type=secret。
• 挂载敏感路径（Critical）→ 生产绝不挂载 /etc、/var/run/docker.sock。
• 保留全部 capabilities（High）→ cap_drop: [ALL]，仅按需 cap_add（如绑定 <1024 端口才加 NET_BIND_SERVICE）。
• host 网络模式 / --privileged（High）→ 用 bridge 或自定义网络，避免特权。
• 可写根文件系统（Medium）→ compose 设 read_only: true 并用 tmpfs 挂 /tmp。

基础镜像决策：编译型二进制 → distroless/static 或 scratch；需 shell 调试 → alpine；需 glibc（如 numpy/pandas 的 C 扩展）→ slim；需大量系统包 → debian-slim。体积参考：scratch 0MB、distroless/static 2MB、alpine 7MB、debian-slim 80MB、python:3.12-slim 130MB；python:3.12（900MB）、node:20（1000MB）生产禁用。

互见

• 研发/devops 其他容器与流水线技能：CI/CD 流水线负责部署本技能产出的容器；本技能不做部署。
• 应用安全技能：覆盖应用层威胁；本技能覆盖容器层加固，二者互补。

---

采编自 alirezarezvani/claude-skills（MIT 许可）。