# Claude Code容器化实战：Docker到DevContainer全流程
## 概述
本文是一篇面向中高级开发者的实战教程，教你如何用 Claude Code 完成 Docker 容器化开发的全流程——从生成 Dockerfile、编写 docker-compose 编排、配置 DevContainer 隔离环境，到生产级镜像优化与安全加固。学完本文，你将掌握让 Claude Code 在容器内高效工作的完整方法链，实现"一份配置、全团队复用"的开发环境标准化。
**适用人群**：有基础命令行经验、正在使用或准备使用 Claude Code 的开发者，希望将 AI 辅助编码与容器化工作流深度整合。
## 前置条件
| 条件 | 说明 |
|------|------|
| Claude Code | 已安装并完成 API 配置（`claude` 命令可用） |
| Docker | Docker Desktop 4.30+ 或 Docker Engine 27+ |
| VS Code | 安装 Dev Containers 扩展（ms-vscode-remote.remote-containers） |
| 基础知识 | 了解 Dockerfile 基本指令、容器与镜像的概念 |
| 项目准备 | 一个待容器化的项目（本文用 Next.js + Python 混合项目做演示） |
## 第一章：为什么用 Claude Code 做 Docker 容器化
### 1.1 传统 Docker 化的痛点
Docker 容器化看似简单——写个 Dockerfile，跑个 `docker build`。但在实际项目中，开发者面临的问题远比"写个 Hello World 镜像"复杂：
- **镜像体积失控**：默认的 `node:20` 镜像超过 1GB，多阶段构建优化写起来费时
- **层缓存失效**：COPY 指令顺序不对，每次代码改动都触发全量依赖安装
- **多服务编排**：前后端 + 数据库 + Redis 的 docker-compose 配置容易出错
- **DevContainer 配置繁琐**：JSON 文件结构复杂，挂载卷、端口映射、环境变量一堆
- **安全基线缺失**：以 root 运行、暴露不必要的端口、未扫描漏洞
Claude Code 的价值在于：它能理解你的项目结构、技术栈、依赖关系，自动生成**最佳实践级别**的容器配置，而不是"能用就行"的草稿。
### 1.2 Claude Code 容器化工作流总览
```mermaid
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[团队标准化环境]
```
## 第二章：用 Claude Code 生成生产级 Dockerfile
### 2.1 初始化项目分析
首先让 Claude Code 理解你的项目结构。在项目根目录启动 Claude Code：
```bash
cd my-project
claude
```
在对话中发送：
```
分析这个项目的结构和技术栈，然后生成一个生产级的 Dockerfile。
要求：
1. 多阶段构建，最终镜像尽量小
2. 非 root 用户运行
3. 合理利用 Docker 层缓存
4. 包含健康检查
```
### 2.2 预期生成的 Dockerfile（Next.js 示例）
Claude Code 会分析你的 `package.json`、`next.config.js` 等文件后，生成类似如下的 Dockerfile：
```dockerfile
# ---- 阶段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"]
```
**关键优化点解析**：
| 优化策略 | Claude Code 的处理方式 |
|----------|----------------------|
| 多阶段构建 | 自动拆分为 deps → builder → runner 三阶段 |
| 层缓存 | 先 COPY package.json 再 COPY 源码，依赖不变则复用缓存 |
| 非 root 运行 | 创建 nextjs 用户，USER 指令切换 |
| 健康检查 | HEALTHCHECK 指令确保容器可用性 |
| standalone 输出 | 利用 Next.js 独立输出模式减少体积 |
### 2.3 生成 .dockerignore
紧跟 Dockerfile 之后，让 Claude Code 生成 .dockerignore：
```
基于刚才生成的 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
```
### 2.4 验证镜像体积
```bash
docker build -t my-app:latest .
docker images my-app:latest
```
预期结果：最终镜像在 150-200MB 左右（Alpine 基础 + standalone 输出），而非默认的 1GB+。
如果镜像偏大，继续让 Claude Code 优化：
```
当前镜像大小是 XXX MB，帮我进一步优化：
1. 检查是否有不必要的依赖被拷贝
2. 评估是否可以用 distroless 基础镜像
3. 分析层缓存命中情况
```
## 第三章：docker-compose 多服务编排
### 3.1 全栈项目编排
假设你的项目包含 Next.js 前端 + FastAPI 后端 + PostgreSQL + Redis，让 Claude Code 一次性生成编排文件：
```
为这个项目生成 docker-compose.yml，包含：
1. nextjs-frontend 服务（端口 3000）
2. fastapi-backend 服务（端口 8000）
3. postgres 数据库（持久化存储）
4. redis 缓存
5. 所有服务在同一网络中
6. 添加健康检查
7. 使用 .env 文件管理环境变量
```
Claude Code 生成的 docker-compose.yml：
```yaml
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:
```
配套的 `.env` 文件：
```bash
# 数据库密码 - 生产环境请使用强密码
DB_PASSWORD=change_me_in_production
# API 密钥等敏感信息
# ANTHROPIC_API_KEY=sk-ant-xxx
```
### 3.2 依赖管理与启动顺序
```mermaid
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
```
关键点：使用 `condition: service_healthy` 而非简单的 `depends_on`，确保依赖服务的健康检查通过后才启动上游服务。
### 3.3 常见问题与解决
| 问题 | 原因 | Claude Code 修复方案 |
|------|------|---------------------|
| 服务启动报 connection refused | 依赖服务未就绪 | 改用 `condition: service_healthy`，添加等待逻辑 |
| 数据库初始化失败 | volume 权限问题 | 添加 init 脚本，使用正确 UID/GID |
| 环境变量不生效 | .env 文件位置错误 | 确保 .env 与 docker-compose.yml 同目录 |
| 端口冲突 | 宿主机端口被占用 | 让 Claude Code 自动检测并更换端口映射 |
如果遇到问题，直接把错误日志粘贴给 Claude Code：
```
docker compose up 启动后 backend 服务报以下错误：
[粘贴错误日志]
请分析原因并修复 docker-compose.yml
```
## 第四章：DevContainer 配置——在容器内运行 Claude Code
### 4.1 为什么要在 DevContainer 里跑 Claude Code
DevContainer 是将 Claude Code 本身运行在容器内的方案。核心优势：
1. **环境一致性**：所有开发者使用完全相同的运行时和依赖版本
2. **零配置上手**：新成员 clone 项目后 `Ctrl+Shift+P → Reopen in Container` 即可开始开发
3. **隔离安全**：Claude Code 在沙箱环境中运行，不会影响宿主系统
4. **Claude Code 自身可用**：在容器内安装 Claude Code CLI，所有 AI 辅助能力不丢失
### 4.2 用 Claude Code 生成 DevContainer 配置
在项目根目录，让 Claude Code 生成完整的 DevContainer 配置：
```
为这个项目生成 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 自动安装依赖
```
Claude Code 生成的配置文件结构：
```
.devcontainer/
├── devcontainer.json # 主配置
├── docker-compose.yml # DevContainer 专用 compose
└── post-create.sh # 初始化脚本
```
**devcontainer.json**：
```json
{
"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}"
}
}
```
**post-create.sh**：
```bash
#!/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"
```
### 4.3 DevContainer 的 docker-compose 覆盖文件
DevContainer 需要对原始 docker-compose 做一些覆盖配置（如挂载工作区、暴露调试端口）：
```yaml
# .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:
```
注意这里使用 `Dockerfile.dev`（开发用）而非生产 Dockerfile，因为开发环境需要额外的调试工具和热重载支持。
### 4.4 开发用 Dockerfile（Dockerfile.dev）
让 Claude Code 生成一个专门用于开发的 Dockerfile：
```dockerfile
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"]
```
### 4.5 在 DevContainer 内使用 Claude Code
启动 DevContainer 后，在容器内的终端运行：
```bash
# 启动 Claude Code
claude
# 或者使用非交互模式生成文件
claude -p "分析这个项目并生成 REST API 接口文档"
# 检查 Claude Code 版本
claude --version
```
API 密钥通过 `remoteEnv` 从宿主机传递，无需在容器内手动配置。
## 第五章：CLAUDE.md 容器化最佳实践配置
### 5.1 容器化项目的 CLAUDE.md 模板
为容器化项目创建专属的 CLAUDE.md，让 Claude Code 始终遵循容器化最佳实践：
```markdown
# 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
```
frontend/ → Next.js 15 (App Router, TypeScript)
backend/ → FastAPI (Python 3.12, SQLAlchemy 2.0)
docker/ → Shared Docker configurations
```
```
### 5.2 Docker 专用指令集
在 CLAUDE.md 中可以定义 Claude Code 处理 Docker 相关任务的优先规则：
```markdown
## 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
```
## 第六章：实战案例——全栈项目容器化从零到 DevContainer
### 6.1 项目背景
我们要容器化一个任务管理应用：
- **前端**：Next.js 15 + TypeScript + Tailwind CSS + shadcn/ui
- **后端**：FastAPI + SQLAlchemy 2.0 + Alembic
- **数据库**：PostgreSQL 16
- **缓存**：Redis 7
### 6.2 Step-by-Step 实操
**Step 1：项目初始化**
```bash
mkdir taskmanager && cd taskmanager
git init
claude
```
**Step 2：让 Claude Code 搭建项目骨架**
```
创建一个全栈任务管理应用的项目骨架：
- frontend/ 目录：Next.js 15 App Router + TypeScript + Tailwind
- backend/ 目录：FastAPI + SQLAlchemy 2.0 + Alembic
- 两个目录分别有 package.json / requirements.txt
- 生成所有必要的配置文件（tsconfig, next.config, pyproject.toml 等）
```
**Step 3：生成 Docker 配置**
```
为这个项目生成完整的 Docker 配置：
1. frontend/Dockerfile（多阶段构建，standalone 模式）
2. backend/Dockerfile（多阶段构建，uvicorn 运行）
3. docker-compose.yml（前后端 + PostgreSQL + Redis）
4. .dockerignore（两个目录各一个）
5. docker-compose.override.yml（开发环境热重载）
```
**Step 4：生成 DevContainer 配置**
```
基于上面的 Docker 配置，生成 DevContainer 配置：
1. 使用 backend 服务作为主开发容器
2. 在容器内安装 Claude Code CLI
3. 挂载项目目录
4. forwardPorts 暴露 3000、8000、5432
5. postCreateCommand 安装前后端依赖
```
**Step 5：验证全部配置**
```bash
# 构建并启动
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 接口"
```
### 6.3 完整项目结构
```
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
```
### 6.4 docker-compose.override.yml（开发热重载）
```yaml
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
```
这个覆盖文件在 `docker compose up` 时自动合并，开发时源码修改实时反映到容器中，无需重新构建。
## 第七章：镜像安全与优化进阶
### 7.1 让 Claude Code 执行安全审计
```
对项目中的所有 Dockerfile 进行安全审计，检查以下方面：
1. 是否以 root 用户运行
2. 是否使用了 latest 标签
3. 是否有 HEALTHCHECK
4. 是否暴露了不必要的端口
5. 是否存在敏感信息硬编码
6. base 镜像是否有已知漏洞
```
Claude Code 会逐项分析并生成修复建议。常见修复示例：
```dockerfile
# 修复前（不安全）
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"]
```
### 7.2 镜像大小优化策略矩阵
```mermaid
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]
```
### 7.3 使用 Trivy 扫描漏洞
让 Claude Code 帮你集成镜像漏洞扫描：
```bash
# 安装 Trivy
brew install trivy # macOS
# 或
sudo apt-get install trivy # Linux
# 扫描构建好的镜像
trivy image taskmanager-frontend:latest
trivy image taskmanager-backend:latest
```
在 CLAUDE.md 中加入自动扫描指令：
```markdown
## 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
```
## 第八章：CI/CD 中的容器化流水线
### 8.1 GitHub Actions 集成
让 Claude Code 生成 GitHub Actions 工作流：
```
生成 GitHub Actions 工作流，要求：
1. PR 触发时构建并测试所有 Docker 镜像
2. main 分支推送时构建并推送到 Docker Hub/GHCR
3. 包含 Trivy 安全扫描步骤
4. 包含镜像大小检查（超过 300MB 则失败）
```
生成的工作流文件 `.github/workflows/docker-ci.yml`：
```yaml
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
```
## 第九章：常见陷阱与排查手册
### 9.1 六大常见陷阱
```mermaid
flowchart TD
subgraph 常见陷阱
T1[陷阱1: 忘记 .dockerignore
node_modules 被拷入镜像]
T2[陷阱2: COPY . . 放在最前面
每次改代码都重建依赖]
T3[陷阱3: 开发用 Dockerfile
混入生产环境]
T4[陷阱4: 敏感信息硬编码
API Key 写在 Dockerfile]
T5[陷阱5: 健康检查缺失
K8s/Docker 不知道服务状态]
T6[陷阱6: 容器时区错误
日志时间与实际不符]
end
subgraph Claude Code 修复
F1[自动生成 .dockerignore
排除 node_modules/.git/.env]
F2[重排指令顺序
先 COPY 依赖文件再 COPY 源码]
F3[区分 Dockerfile / Dockerfile.dev
docker-compose 区分 prod/dev]
F4[使用 ENV + .env 文件
运行时注入敏感信息]
F5[添加 HEALTHCHECK 指令
暴露 /health 端点]
F6[设置 TZ 环境变量
安装 tzdata 包]
end
T1 --> F1
T2 --> F2
T3 --> F3
T4 --> F4
T5 --> F5
T6 --> F6
```
### 9.2 排查命令速查
| 场景 | 命令 | 说明 |
|------|------|------|
| 容器启动失败 | `docker compose logs --tail=50 backend` | 查看最近 50 行日志 |
| 进入容器调试 | `docker compose exec backend sh` | 进入运行中的容器 |
| 查看层大小 | `docker history my-app:latest` | 分析每层占用空间 |
| 网络连通性 | `docker compose exec frontend wget -qO- backend:8000/health` | 容器间网络测试 |
| 卷数据检查 | `docker volume inspect taskmanager_postgres_data` | 查看持久化卷 |
| 镜像对比 | `dive my-app:latest` | 逐层分析镜像内容 |
### 9.3 让 Claude Code 帮你排查
当遇到容器问题时，最高效的方式是直接让 Claude Code 诊断：
```
我的 docker compose up 报以下错误，请帮我诊断：
[粘贴完整错误输出]
项目结构如下：
[粘贴 tree 输出或项目结构描述]
```
Claude Code 会分析：
- 错误类型（构建失败 / 运行时崩溃 / 网络问题 / 权限问题）
- 根因定位（Dockerfile 指令 / compose 配置 / 环境变量）
- 修复方案（直接修改相关文件）
## 延伸阅读
- [Claude Code + Docker & Dev Containers (2026) — SkillsPlayground](https://skillsplayground.com/guides/claude-code-docker/) — DevContainer 配置全教程
- [Build and Debug Docker Containers with Claude Code — ComputingForGeeks](https://computingforgeeks.com/claude-code-docker-guide/) — Docker 生成与调试实战
- [Development Containers — Claude Code Official Docs](https://code.claude.com/docs/en/devcontainer) — Anthropic 官方 DevContainer 文档
- [Running Claude Code in Docker Sandbox — McConnell Web](https://www.mcconnellweb.com/posts/claude-code-docker-sandbox/) — 安全沙箱方案
- [Claude Code Docker: Running AI Agents in Containers — DataCamp](https://www.datacamp.com/tutorial/claude-code-docker) — DataCamp 深度教程
## 训练营适用性评估
| 维度 | 评估 |
|------|------|
| 适合训练营类型 | DevOps 训练营、全栈开发训练营、AI 工具链训练营 |
| 学员基础要求 | 熟悉基本命令行操作，了解 Docker 基础概念 |
| 预计教学时长 | 4-6 小时（含实操演练） |
| 实操占比 | 70%（大量动手生成 Dockerfile、compose、DevContainer） |
| 推荐分组方式 | 2-3 人一组，每人负责不同服务的容器化 |
| 考核方式 | 提交一个完整的 DevContainer 配置，能在容器内运行 Claude Code |
## 参考来源
1. [Claude Code + Docker & Dev Containers (2026) — SkillsPlayground](https://skillsplayground.com/guides/claude-code-docker/) — DevContainer 完整配置指南，包含 VS Code 集成
2. [Build and Debug Docker Containers with Claude Code — ComputingForGeeks](https://computingforgeeks.com/claude-code-docker-guide/) — Claude Code Docker 生成与调试最佳实践
3. [Development Containers — Claude Code Docs](https://code.claude.com/docs/en/devcontainer) — Anthropic 官方 DevContainer 配置文档
4. [Claude Code Docker: Running AI Agents in Containers — DataCamp](https://www.datacamp.com/tutorial/claude-code-docker) — DataCamp 出品的容器化 AI Agent 教程
5. [Running Claude Code in Docker Sandbox — McConnell Web](https://www.mcconnellweb.com/posts/claude-code-docker-sandbox/) — Docker 沙箱安全运行方案
> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。
