docker-development

Docker 开发

更小的镜像。更快的构建。安全的容器。没有猜测。

有主见的 Docker 工作流，可将臃肿的 Dockerfile 改造为生产级容器。涵盖优化、多阶段构建、Compose 编排与安全加固。

这不是一份 Docker 教程，而是一组关于如何构建容器的具体决策，确保不浪费时间、空间或攻击面。

---

斜杠命令

命令	作用
/docker:optimize	分析并优化 Dockerfile 的体积、速度与层缓存
/docker:compose	生成或改进 docker-compose.yml，遵循最佳实践
/docker:security	审计 Dockerfile 或正在运行的容器的安全问题

---

何时激活此技能

识别用户的以下表达方式：

• "优化这个 Dockerfile"
• "我的 Docker 构建很慢"
• "为这个项目创建一个 docker-compose"
• "这个 Dockerfile 安全吗？"
• "减小我的 Docker 镜像体积"
• "设置多阶段构建"
• "[语言/框架] 的 Docker 最佳实践"
• 任何涉及以下内容的请求：Dockerfile、docker-compose、容器、镜像体积、构建缓存、Docker 安全

如果用户有 Dockerfile，或想要容器化某个应用 → 此技能适用。

---

工作流

/docker:optimize — Dockerfile 优化

1. 分析当前状态

   • 读取 Dockerfile
   • 识别基础镜像及其体积
   • 统计层数（每个 RUN/COPY/ADD = 1 层）
   • 检查常见反模式

2. 应用优化清单

   BASE IMAGE
   ├── Use specific tags, never :latest in production
   ├── Prefer slim/alpine variants (debian-slim > ubuntu > debian)
   ├── Pin digest for reproducibility in CI: image@sha256:...
   └── Match base to runtime needs (don't use python:3.12 for a compiled binary)
   
   LAYER OPTIMIZATION
   ├── Combine related RUN commands with && \
   ├── Order layers: least-changing first (deps before source code)
   ├── Clean package manager cache in the same RUN layer
   ├── Use .dockerignore to exclude unnecessary files
   └── Separate build deps from runtime deps
   
   BUILD CACHE
   ├── COPY dependency files before source code (package.json, requirements.txt, go.mod)
   ├── Install deps in a separate layer from code copy
   ├── Use BuildKit cache mounts: --mount=type=cache,target=/root/.cache
   └── Avoid COPY . . before dependency installation
   
   MULTI-STAGE BUILDS
   ├── Stage 1: build (full SDK, build tools, dev deps)
   ├── Stage 2: runtime (minimal base, only production artifacts)
   ├── COPY --from=builder only what's needed
   └── Final image should have NO build tools, NO source code, NO dev deps
   

3. 生成优化后的 Dockerfile

   • 应用所有相关优化
   • 添加行内注释说明每项决策
   • 报告预估的体积缩减

4. 验证

   python3 scripts/dockerfile_analyzer.py Dockerfile
   

/docker:compose — Docker Compose 配置

1. 识别服务

   • 应用（Web、API、Worker）
   • 数据库（postgres、mysql、redis、mongo）
   • 缓存（redis、memcached）
   • 队列（rabbitmq、kafka）
   • 反向代理（nginx、traefik、caddy）

2. 应用 Compose 最佳实践

   SERVICES
   ├── Use depends_on with condition: service_healthy
   ├── Add healthchecks for every service
   ├── Set resource limits (mem_limit, cpus)
   ├── Use named volumes for persistent data
   └── Pin image versions
   
   NETWORKING
   ├── Create explicit networks (don't rely on default)
   ├── Separate frontend and backend networks
   ├── Only expose ports that need external access
   └── Use internal: true for backend-only networks
   
   ENVIRONMENT
   ├── Use env_file for secrets, not inline environment
   ├── Never commit .env files (add to .gitignore)
   ├── Use variable substitution: ${VAR:-default}
   └── Document all required env vars
   
   DEVELOPMENT vs PRODUCTION
   ├── Use compose profiles or override files
   ├── Dev: bind mounts for hot reload, debug ports exposed
   ├── Prod: named volumes, no debug ports, restart: unless-stopped
   └── docker-compose.override.yml for dev-only config
   

3. 生成 Compose 文件

   • 输出包含健康检查、网络与卷的 docker-compose.yml
   • 生成包含所有必需变量说明的 .env.example
   • 添加 dev/prod 配置文件（profile）注释

/docker:security — 容器安全审计

1. Dockerfile 审计

   检查项	严重程度	修复方法
   以 root 身份运行	严重	创建用户后添加 USER nonroot
   使用 :latest 标签	高	固定到特定版本
   ENV/ARG 中的密钥	严重	使用 BuildKit 密钥：--mount=type=secret
   使用过宽的 COPY 通配符	中	使用具体路径，并添加 .dockerignore
   不必要的 EXPOSE	低	仅暴露应用实际使用的端口
   没有 HEALTHCHECK	中	添加带有合适间隔的 HEALTHCHECK
   特权指令	高	避免 --privileged，移除不必要的权限能力
   保留了包管理器缓存	低	在同一 RUN 层中清理

2. 运行时安全检查

   检查项	严重程度	修复方法
   容器以 root 身份运行	严重	在 Dockerfile 或 Compose 中设置用户
   根文件系统可写	中	在 Compose 中使用 read_only: true
   保留所有能力	高	全部移除，仅添加需要的：cap_drop: [ALL]
   没有资源限制	中	设置 mem_limit 与 cpus
   主机网络模式	高	使用 bridge 或自定义网络
   敏感挂载	严重	生产环境中切勿挂载 /etc、/var/run/docker.sock
   未配置日志驱动	低	设置带大小限制的 logging:

3. 生成安全报告

   SECURITY AUDIT — [Dockerfile/Image name]
   Date: [timestamp]
   
   CRITICAL: [count]
   HIGH:     [count]
   MEDIUM:   [count]
   LOW:      [count]
   
   [Detailed findings with fix recommendations]
   

---

工具

scripts/dockerfile_analyzer.py

用于对 Dockerfile 进行静态分析的命令行工具。

功能特性：

• 层数统计与优化建议
• 基础镜像分析及体积估算
• 反模式检测（15 条以上规则）
• 安全问题标记
• 多阶段构建检测与验证
• JSON 与文本输出

用法：

# Analyze a Dockerfile
python3 scripts/dockerfile_analyzer.py Dockerfile

# JSON output
python3 scripts/dockerfile_analyzer.py Dockerfile --output json

# Analyze with security focus
python3 scripts/dockerfile_analyzer.py Dockerfile --security

# Check a specific directory
python3 scripts/dockerfile_analyzer.py path/to/Dockerfile

scripts/compose_validator.py

用于校验 docker-compose 文件的命令行工具。

功能特性：

• 服务依赖校验
• 健康检查配置检测
• 网络配置分析
• 卷挂载校验
• 环境变量审计
• 端口冲突检测
• 最佳实践评分

用法：

# Validate a compose file
python3 scripts/compose_validator.py docker-compose.yml

# JSON output
python3 scripts/compose_validator.py docker-compose.yml --output json

# Strict mode (fail on warnings)
python3 scripts/compose_validator.py docker-compose.yml --strict

---

多阶段构建模式

模式 1：编译型语言（Go、Rust、C++）

# Build stage
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

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

模式 2：Node.js / TypeScript

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

# Build stage
FROM deps AS builder
COPY . .
RUN npm run build

# Runtime stage
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"]

模式 3：Python

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

# Runtime stage
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"]

---

基础镜像决策树

Is it a compiled binary (Go, Rust, C)?
├── Yes → distroless/static or scratch
└── No
    ├── Need a shell for debugging?
    │   ├── Yes → alpine variant (e.g., node:20-alpine)
    │   └── No → distroless variant
    ├── Need glibc (not musl)?
    │   ├── Yes → slim variant (e.g., python:3.12-slim)
    │   └── No → alpine variant
    └── Need specific OS packages?
        ├── Many → debian-slim
        └── Few → alpine + apk add

---

主动触发项

无需用户提问，主动标记以下问题：

• Dockerfile 使用 :latest → 建议固定到具体的版本标签。
• 没有 .dockerignore → 创建一个。至少包含：.git、node_modules、__pycache__、.env。
• 在安装依赖之前执行 COPY . . → 会导致缓存失效。调整顺序，先安装依赖。
• 以 root 身份运行 → 添加 USER 指令。生产环境中没有例外。
• 在 ENV 或 ARG 中存放密钥 → 使用 BuildKit 密钥挂载。切勿将密钥写入镜像层。
• 镜像超过 1GB → 必须使用多阶段构建。生产镜像没有理由大到这种程度。
• 没有健康检查 → 添加一个。编排工具（Compose、K8s）需要它来正确管理生命周期。
• apt-get 未在同一层清理 → 在同一个 RUN 中执行 rm -rf /var/lib/apt/lists/*。

---

安装

一行命令（适用于任意工具）

git clone https://github.com/alirezarezvani/claude-skills.git
cp -r claude-skills/engineering/docker-development ~/.claude/skills/

多工具安装

./scripts/convert.sh --skill docker-development --tool codex|gemini|cursor|windsurf|openclaw

OpenClaw

clawhub install cs-docker-development

---

相关 Skills

• senior-devops — 覆盖范围更广的 DevOps（CI/CD、IaC、监控）。二者互补：容器相关工作用 docker-development，流水线和基础设施用 senior-devops。
• senior-security — 应用安全。二者互补：docker-development 覆盖容器安全，senior-security 覆盖应用层威胁。
• autoresearch-agent — 可以将优化 Docker 构建时间或镜像体积作为可量化的实验来进行。
• ci-cd-pipeline-builder — 流水线搭建。二者互补：docker-development 构建容器，ci-cd-pipeline-builder 负责部署它们。