Claude Code容器化实战：Docker到DevContainer全流程

flowchart TD
    A[项目代码库] --> B{Claude Code 分析项目结构}
    B --> C[生成 Dockerfile]
    B --> D[生成 docker-compose.yml]
    B --> E[生成 .dockerignore]
    C --> F[多阶段构建优化]
    D --> G[多服务编排]
    E --> H[排除不必要文件]
    F --> I[镜像体积验证]
    G --> I
    H --> I
    I --> J{镜像 < 200MB?}
    J -->|是| K[配置 DevContainer]
    J -->|否| L[Claude Code 优化层缓存]
    L --> I
    K --> M[容器内运行 Claude Code]
    M --> N[团队标准化环境]

cd my-project
claude

分析这个项目的结构和技术栈，然后生成一个生产级的 Dockerfile。
要求：
1. 多阶段构建，最终镜像尽量小
2. 非 root 用户运行
3. 合理利用 Docker 层缓存
4. 包含健康检查

# ---- 阶段1: 依赖安装 ----
FROM node:20-alpine AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci --only=production

# ---- 阶段2: 构建应用 ----
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

ENV NEXT_TELEMETRY_DISABLED=1
RUN npm run build

# ---- 阶段3: 生产镜像 ----
FROM node:20-alpine AS runner
WORKDIR /app

ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1

RUN addgroup --system --gid 1001 nodejs \
    && adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/ || exit 1

CMD ["node", "server.js"]

基于刚才生成的 Dockerfile，生成 .dockerignore 文件，排除所有不必要的文件

node_modules
.next
.git
.gitignore
README.md
Dockerfile
docker-compose*.yml
.dockerignore
npm-debug.log*
.env*.local
.vscode
.idea
*.md
coverage
.nyc_output

docker build -t my-app:latest .
docker images my-app:latest

当前镜像大小是 XXX MB，帮我进一步优化：
1. 检查是否有不必要的依赖被拷贝
2. 评估是否可以用 distroless 基础镜像
3. 分析层缓存命中情况

为这个项目生成 docker-compose.yml，包含：
1. nextjs-frontend 服务（端口 3000）
2. fastapi-backend 服务（端口 8000）
3. postgres 数据库（持久化存储）
4. redis 缓存
5. 所有服务在同一网络中
6. 添加健康检查
7. 使用 .env 文件管理环境变量

version: "3.9"

services:
  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NEXT_PUBLIC_API_URL=http://backend:8000
    depends_on:
      backend:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3000"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://appuser:${DB_PASSWORD}@postgres:5432/appdb
      - REDIS_URL=redis://redis:6379/0
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 20s
      timeout: 5s
      retries: 3
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=appuser
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=appdb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:

# 数据库密码 - 生产环境请使用强密码
DB_PASSWORD=change_me_in_production

# API 密钥等敏感信息
# ANTHROPIC_API_KEY=sk-ant-xxx

graph LR
    A[Frontend :3000] -->|depends_on| B[Backend :8000]
    B -->|depends_on| C[PostgreSQL :5432]
    B -->|depends_on| D[Redis :6379]

    style A fill:#4FC3F7,color:#000
    style B fill:#81C784,color:#000
    style C fill:#7986CB,color:#fff
    style D fill:#FF8A65,color:#000

docker compose up 启动后 backend 服务报以下错误：
[粘贴错误日志]
请分析原因并修复 docker-compose.yml

为这个项目生成 VS Code DevContainer 配置，要求：
1. 基于 Docker Compose（使用前面生成的 docker-compose.yml）
2. 在 backend 服务中安装 Claude Code CLI
3. 挂载 Claude Code 配置目录（~/.claude）
4. 配置 Node.js 20 + Python 3.12 双运行时
5. 安装必要的 VS Code 扩展
6. 配置 postCreateCommand 自动安装依赖

.devcontainer/
├── devcontainer.json    # 主配置
├── docker-compose.yml   # DevContainer 专用 compose
└── post-create.sh       # 初始化脚本

{
  "name": "My Project Dev",
  "dockerComposeFile": ["../docker-compose.yml", "docker-compose.yml"],
  "service": "backend",
  "workspaceFolder": "/workspace",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "20",
      "pnpm": true
    },
    "ghcr.io/devcontainers/features/python:1": {
      "version": "3.12"
    }
  },
  "forwardPorts": [3000, 8000, 5432, 6379],
  "postCreateCommand": "bash .devcontainer/post-create.sh",
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "ms-python.python",
        "ms-python.black-formatter",
        "bradlc.vscode-tailwindcss",
        "ms-azuretools.vscode-docker"
      ],
      "settings": {
        "python.defaultInterpreterPath": "/usr/local/bin/python",
        "python.linting.enabled": true,
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "esbenp.prettier-vscode"
      }
    }
  },
  "mounts": [
    "source=my-project-cli,target=/home/vscode/.claude,type=volume"
  ],
  "remoteEnv": {
    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}"
  }
}

#!/bin/bash
set -e

echo "==> Installing dependencies..."

# 前端依赖
cd /workspace/frontend && npm install

# 后端依赖
cd /workspace/backend && pip install -r requirements.txt

# 安装 Claude Code CLI
npm install -g @anthropic-ai/claude-code

echo "==> DevContainer setup complete!"
echo "==> Run 'claude' to start Claude Code"

# .devcontainer/docker-compose.yml
version: "3.9"

services:
  backend:
    build:
      context: ../backend
      dockerfile: Dockerfile.dev
      args:
        - NODE_VERSION=20
    volumes:
      - ..:/workspace:cached
      - backend_node_modules:/workspace/backend/node_modules
    command: sleep infinity
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}

volumes:
  backend_node_modules:

FROM node:20-alpine

# 安装 Python 和常用工具
RUN apk add --no-cache \
    python3 \
    py3-pip \
    git \
    curl \
    bash \
    libc6-compat

WORKDIR /workspace

# 安装 Claude Code CLI（全局）
RUN npm install -g @anthropic-ai/claude-code

# 配置 shell
RUN echo 'export PS1="\[\033[01;32m\]\u@devcontainer\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\$ "' >> /etc/bash.bashrc

CMD ["sleep", "infinity"]

# 启动 Claude Code
claude

# 或者使用非交互模式生成文件
claude -p "分析这个项目并生成 REST API 接口文档"

# 检查 Claude Code 版本
claude --version

# CLAUDE.md

## Project Context
- Full-stack app: Next.js 15 frontend + FastAPI backend
- Containerized with Docker Compose
- DevContainer for consistent development environment

## Docker Rules
- Always use multi-stage builds for production Dockerfiles
- Use Alpine or distroless base images
- Never run containers as root in production
- Include HEALTHCHECK in all service Dockerfiles
- Order Dockerfile instructions for optimal layer caching:
  1. Base image
  2. System dependencies
  3. Package files (package.json, requirements.txt)
  4. Dependency installation
  5. Application code COPY
  6. Build commands

## Development Commands
- `docker compose up -d` — Start all services
- `docker compose up --build` — Rebuild and start
- `docker compose logs -f backend` — Follow backend logs
- `docker compose exec backend bash` — Shell into backend
- `docker compose down -v` — Stop and remove volumes

## Testing in Containers
- Run tests inside containers: `docker compose exec backend pytest`
- Integration tests need all services running
- Use test-specific compose override: docker-compose.test.yml

## Architecture

## Docker Generation Priority
When I ask for Docker configuration, follow this priority:
1. Security: non-root user, minimal attack surface
2. Size: multi-stage build, Alpine/distroless base
3. Cache: optimal layer ordering
4. Health: HEALTHCHECK for all services
5. Observability: structured logging, health endpoints

mkdir taskmanager && cd taskmanager
git init
claude

创建一个全栈任务管理应用的项目骨架：
- frontend/ 目录：Next.js 15 App Router + TypeScript + Tailwind
- backend/ 目录：FastAPI + SQLAlchemy 2.0 + Alembic
- 两个目录分别有 package.json / requirements.txt
- 生成所有必要的配置文件（tsconfig, next.config, pyproject.toml 等）

为这个项目生成完整的 Docker 配置：
1. frontend/Dockerfile（多阶段构建，standalone 模式）
2. backend/Dockerfile（多阶段构建，uvicorn 运行）
3. docker-compose.yml（前后端 + PostgreSQL + Redis）
4. .dockerignore（两个目录各一个）
5. docker-compose.override.yml（开发环境热重载）

基于上面的 Docker 配置，生成 DevContainer 配置：
1. 使用 backend 服务作为主开发容器
2. 在容器内安装 Claude Code CLI
3. 挂载项目目录
4. forwardPorts 暴露 3000、8000、5432
5. postCreateCommand 安装前后端依赖

# 构建并启动
docker compose up --build

# 验证服务健康
docker compose ps
curl http://localhost:3000
curl http://localhost:8000/health

# 验证镜像大小
docker images | grep taskmanager

# 测试 DevContainer
# 在 VS Code 中: Ctrl+Shift+P → "Reopen in Container"
# 容器内执行:
claude -p "列出这个项目的所有 API 接口"

taskmanager/
├── .devcontainer/
│   ├── devcontainer.json
│   ├── docker-compose.yml      # DevContainer 覆盖
│   └── post-create.sh
├── frontend/
│   ├── src/
│   ├── Dockerfile               # 生产多阶段构建
│   ├── Dockerfile.dev           # 开发用
│   ├── .dockerignore
│   ├── package.json
│   └── next.config.ts
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   ├── models.py
│   │   └── routers/
│   ├── Dockerfile               # 生产多阶段构建
│   ├── Dockerfile.dev           # 开发用
│   ├── .dockerignore
│   └── requirements.txt
├── docker-compose.yml           # 生产编排
├── docker-compose.override.yml  # 开发覆盖
├── .env                         # 环境变量
├── CLAUDE.md                    # Claude Code 项目配置
└── README.md

version: "3.9"

services:
  frontend:
    build:
      dockerfile: Dockerfile.dev
    volumes:
      - ./frontend/src:/app/src:cached
      - ./frontend/public:/app/public:cached
    command: npm run dev

  backend:
    build:
      dockerfile: Dockerfile.dev
    volumes:
      - ./backend/app:/workspace/app:cached
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

对项目中的所有 Dockerfile 进行安全审计，检查以下方面：
1. 是否以 root 用户运行
2. 是否使用了 latest 标签
3. 是否有 HEALTHCHECK
4. 是否暴露了不必要的端口
5. 是否存在敏感信息硬编码
6. base 镜像是否有已知漏洞

# 修复前（不安全）
FROM node:latest
COPY . .
CMD ["npm", "start"]

# 修复后（安全）
FROM node:20.11-alpine@sha256:xxxx AS runner
RUN addgroup --system --gid 1001 appgroup \
    && adduser --system --uid 1001 appuser
COPY --chown=appuser:appgroup . .
USER appuser
HEALTHCHECK CMD wget --spider -q http://localhost:3000 || exit 1
CMD ["node", "server.js"]

quadrantChart
    title Docker镜像优化策略矩阵
    x-axis "实现复杂度" --> "高"
    y-axis "体积减少" --> "显著"
    quadrant-1 "高价值高成本"
    quadrant-2 "高价值低成本"
    quadrant-3 "低价值低成本"
    quadrant-4 "低价值高成本"
    "使用Alpine基础镜像": [0.2, 0.7]
    "多阶段构建": [0.4, 0.8]
    "Distroless基础镜像": [0.6, 0.6]
    "层缓存优化": [0.3, 0.4]
    "dockerignore排除": [0.1, 0.5]
    " standalone输出": [0.3, 0.75]
    "二进制编译": [0.8, 0.9]
    "合并RUN指令": [0.2, 0.3]

# 安装 Trivy
brew install trivy  # macOS
# 或
sudo apt-get install trivy  # Linux

# 扫描构建好的镜像
trivy image taskmanager-frontend:latest
trivy image taskmanager-backend:latest

## Security
- After generating or modifying Dockerfile, always suggest running `trivy image` scan
- Never use `latest` tag for base images — pin specific versions
- All production containers must run as non-root user

生成 GitHub Actions 工作流，要求：
1. PR 触发时构建并测试所有 Docker 镜像
2. main 分支推送时构建并推送到 Docker Hub/GHCR
3. 包含 Trivy 安全扫描步骤
4. 包含镜像大小检查（超过 300MB 则失败）

name: Docker CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_PREFIX: ${{ github.repository }}

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        service: [frontend, backend]

    steps:
      - uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build ${{ matrix.service }}
        uses: docker/build-push-action@v5
        with:
          context: ./${{ matrix.service }}
          push: false
          load: true
          tags: ${{ matrix.service }}:test
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Check image size
        run: |
          SIZE=$(docker image inspect ${{ matrix.service }}:test --format='{{.Size}}')
          SIZE_MB=$((SIZE / 1024 / 1024))
          echo "Image size: ${SIZE_MB}MB"
          if [ "$SIZE_MB" -gt 300 ]; then
            echo "::error::Image too large: ${SIZE_MB}MB (limit: 300MB)"
            exit 1
          fi

      - name: Run Trivy vulnerability scanner
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: "${{ matrix.service }}:test"
          format: "table"
          exit-code: "1"
          severity: "CRITICAL,HIGH"

  push:
    needs: build-and-test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v4

      - name: Log in to GHCR
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: ./frontend
          push: true
          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_PREFIX }}/frontend:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

flowchart TD
    subgraph 常见陷阱
        T1[陷阱1: 忘记 .dockerignore<br/>node_modules 被拷入镜像]
        T2[陷阱2: COPY . . 放在最前面<br/>每次改代码都重建依赖]
        T3[陷阱3: 开发用 Dockerfile<br/>混入生产环境]
        T4[陷阱4: 敏感信息硬编码<br/>API Key 写在 Dockerfile]
        T5[陷阱5: 健康检查缺失<br/>K8s/Docker 不知道服务状态]
        T6[陷阱6: 容器时区错误<br/>日志时间与实际不符]
    end

    subgraph Claude Code 修复
        F1[自动生成 .dockerignore<br/>排除 node_modules/.git/.env]
        F2[重排指令顺序<br/>先 COPY 依赖文件再 COPY 源码]
        F3[区分 Dockerfile / Dockerfile.dev<br/>docker-compose 区分 prod/dev]
        F4[使用 ENV + .env 文件<br/>运行时注入敏感信息]
        F5[添加 HEALTHCHECK 指令<br/>暴露 /health 端点]
        F6[设置 TZ 环境变量<br/>安装 tzdata 包]
    end

    T1 --> F1
    T2 --> F2
    T3 --> F3
    T4 --> F4
    T5 --> F5
    T6 --> F6

我的 docker compose up 报以下错误，请帮我诊断：

[粘贴完整错误输出]

项目结构如下：
[粘贴 tree 输出或项目结构描述]