---

name: docker-ops description: "Docker 容器化模式、Dockerfile 最佳实践、多阶段构建和 Docker Compose。适用于：docker、Dockerfile、docker-compose、container、image、multi-stage build、docker build、docker run、.dockerignore、health check、distroless、scratch image、BuildKit、layer caching、container security。" license: MIT allowed-tools: "Read Write Bash" metadata: author: claude-mods related-skills: container-orchestration, go-ops, rust-ops, ci-cd-ops

Docker 操作

用于构建、运行和编排容器化应用的全面 Docker 模式。

Dockerfile 最佳实践

| 实践 | 应该做 | 不应该做 | |----------|------|-------| | 基础镜像 | FROM node:20-slim | FROM node:latest | | 层缓存 | 先复制依赖文件，再复制源码 | 在 RUN install 前 COPY . . | | 包安装 | apt-get update && apt-get install -y ... && rm -rf /var/lib/apt/lists/* | 分开 RUN update 和 install | | 用户 | USER nonroot（需要时创建） | 在生产环境以 root 运行 | | 多阶段 | 分离构建和运行阶段 | 发布编译工具链 | | 密钥 | --mount=type=secret（BuildKit） | COPY .env . 或 ARG PASSWORD | | ENTRYPOINT vs CMD | ENTRYPOINT 用于固定二进制，CMD 用于默认值 | 依赖 shell 形式处理信号 | | WORKDIR | WORKDIR /app | RUN cd /app && ... | | .dockerignore | 包含 .git、node_modules、__pycache__ | 完全没有 .dockerignore | | 标签 | LABEL org.opencontainers.image.* | 无元数据 |

多阶段构建决策树

按语言选择运行时基础镜像：

Go ──────────── CGO disabled? ──── Yes ──► scratch or distroless/static
                                   No ───► distroless/base or alpine

Rust ─────────── Static musl? ──── Yes ──► scratch or distroless/static
                                   No ───► distroless/cc or debian-slim

Node.js ──────── Need native? ──── Yes ──► node:20-slim
                                   No ───► node:20-alpine (smaller)

Python ────────── Need C libs? ─── Yes ──► python:3.12-slim
                                   No ───► python:3.12-slim (still slim)

Java ──────────── JRE only ──────────────► eclipse-temurin:21-jre-alpine

层缓存规则

Docker 缓存每一层。第 N 层缓存失效会使所有后续层失效。

什么会使缓存失效

| 触发条件 | 效果 | |---------|--------| | COPY/ADD 中的文件变更 | 使本层及后续所有层失效 | | RUN 命令文本变更 | 使本层及后续所有层失效 | | ARG 值变更 | 从 ARG 声明处开始失效 | | --no-cache 标志 | 全部失效 | | 基础镜像更新 | 全部失效 |

最优层顺序

# 1. Base image (changes rarely)
FROM python:3.12-slim

# 2. System dependencies (changes rarely)
RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# 3. Dependency files (changes occasionally)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 4. Application code (changes frequently)
COPY src/ ./src/

# 5. Runtime config (changes frequently)
CMD ["python", "-m", "app"]

经验法则： 按变更频率从低到高排列层。

.dockerignore 要点

# Version control
.git
.gitignore

# Dependencies (rebuilt in container)
node_modules
__pycache__
*.pyc
.venv
vendor/

# Build artifacts
dist/
build/
target/
*.egg-info

# IDE and editor
.vscode
.idea
*.swp

# Docker files
Dockerfile*
docker-compose*
.dockerignore

# Environment and secrets
.env
.env.*
*.pem
*.key

# Documentation and tests
docs/
tests/
*.md
LICENSE

重要性： 没有 .dockerignore，docker build 会将整个上下文目录发送给守护进程。仅 .git 文件夹就可能增加数百 MB。

Docker Compose 快速参考

服务定义

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    image: myapp:latest
    ports:
      - "8080:8000"
    environment:
      DATABASE_URL: postgres://db:5432/app
    env_file:
      - .env
    volumes:
      - ./src:/app/src
      - app-data:/app/data
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
    restart: unless-stopped
    networks:
      - backend