docker-compose

Docker Compose 技能

安装

该技能会调用 docker compose。最简单的方法是安装 Docker Desktop（包含 Docker Engine 和 Compose）：

• Windows：Windows 版 Docker Desktop（WSL 2 或 Hyper-V）
• Mac：Mac 版 Docker Desktop（Apple Silicon 或 Intel）
• Linux：Linux 版 Docker Desktop 或从 Docker 的仓库安装 Docker Engine + Compose 插件

验证：docker compose version

速查表与最佳实践

命令： docker compose up -d / down；docker compose ps / logs -f <service>；docker compose exec <service> sh；docker compose build --no-cache；docker compose -f compose.prod.yaml config — 验证。

YAML： 为数据库使用具名卷（postgres_data:/var/lib/postgresql/data）。使用健康检查（healthcheck:，包含 test、interval、timeout、retries）。默认使用一个网络；通过名称引用服务（例如 http://api:3000）。使用 env_file 或 environment；将机密信息保存在 secrets: 中。

技巧： -f compose.yaml -f override.yaml 可合并文件（后面的文件会覆盖前面的文件）。使用 --project-name 进行隔离。开发环境优先使用 build: context: . dockerfile: Dockerfile；生产环境固定镜像标签。运行 up 前执行 docker compose config，以便发现错误。

认证与培训

Docker Certified Associate (DCA)： 编排 25%、镜像/注册表 20%、安装/配置 15%、网络 15%、安全 15%、存储 10%。免费资源：官方 DCA 学习指南、Coursera DCA 备考课程（可旁听）。技能数据： Compose YAML（服务、卷、网络、健康检查）、CLI（up/down/ps/logs/exec）。

钩子与工作流

建议的钩子： 启动前：docker compose config（验证）。停止后：可选清理。路由到 devops 或 devops-troubleshooter 时使用。

工作流： 与 devops（主要）、devops-troubleshooter（主要）配合使用。流程：验证 Compose → 根据任务执行 up/down/exec。容器调试请参阅 operations/incident-response。

概述

此技能提供全面的 Docker Compose 管理功能，使 AI Agent 能够编排多容器应用、管理服务、检查日志并排查容器化环境中的问题，同时通过渐进式披露优化上下文使用。

上下文节省： 减少约 92%

• MCP 模式： 始终加载约 25,000 个 token（多个工具 + 架构）
• 技能模式： 约 700 个 token 的元数据 + 按需加载

适用场景

• 管理本地开发环境
• 编排多容器应用
• 调试服务连接与网络
• 监控容器日志和健康状况
• 构建和更新服务镜像
• 测试容器化应用栈
• 排查服务故障
• 管理应用生命周期（启动、停止、重启）

要求

• 已安装并运行 Docker Engine
• Docker Compose V2（docker compose 插件 — V1 docker-compose 已停止维护）
• 项目中有有效的 compose.yaml（首选）或 compose.yml / docker-compose.yml
• 具备访问 Docker socket 的适当权限

快速参考

# List running services
docker compose ps

# View service logs
docker compose logs <service>

# Start services
docker compose up -d

# Stop services
docker compose down

# Rebuild services
docker compose build

# Execute command in container
docker compose exec <service> <command>

# Live development reloading (Compose Watch)
docker compose watch

# Start with a profile active
docker compose --profile debug up -d

# Validate merged config
docker compose config

2026 年功能亮点

compose.yaml — 规范文件名

Docker Compose V2 优先使用 compose.yaml（和 compose.yml），而非旧版 docker-compose.yml。 顶层字段 version: 已弃用，新文件应完全省略该字段。

# compose.yaml  (preferred — no version: field needed)
services:
  web:
    build: .
    ports:
      - '8080:80'
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Compose Watch — 实时开发重载

Compose Watch（Compose 2.22+ 起正式发布）取代了开发期间手动重新构建并重启的流程。为每个服务配置一个 develop.watch 块。可使用以下三种操作：

操作	行为
sync	将更改的文件即时复制到正在运行的容器中
rebuild	触发 docker compose build 并重新创建容器
sync+restart	同步文件后重启容器进程（无需完整重新构建）

services:
  api:
    build: .
    ports:
      - '3000:3000'
    develop:
      watch:
        # Sync source instantly — no rebuild needed for interpreted code
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - node_modules/
        # Rebuild when dependency manifest changes
        - action: rebuild
          path: package.json
        # Restart only when config changes
        - action: sync+restart
          path: ./config
          target: /app/config

使用以下命令启动：

# Watch mode (keeps output in foreground)
docker compose watch

# Or combined with up
docker compose up --watch

各操作的适用场景：

• sync — 适用于运行时会自动加载更改的解释型语言（Node.js、Python、Ruby）
• sync+restart — 适用于需要重启进程但无需完整重新构建的配置或模板文件
• rebuild — 适用于依赖清单发生更改时（package.json、requirements.txt、go.mod）

Profiles — 特定环境的服务

Profiles 允许单个 compose.yaml 服务于多个环境。不带 profile 的服务始终会启动。带有 profile 的服务仅在该 profile 激活时启动。

services:
  # Always starts — no profile
  api:
    build: .
    ports:
      - '3000:3000'
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 5s
      timeout: 3s
      retries: 5
    volumes:
      - db_data:/var/lib/postgresql/data

  # Only with --profile debug
  pgadmin:
    image: dpage/pgadmin4:latest
    profiles: ['debug']
    ports:
      - '5050:80'
    environment:
      PGADMIN_DEFAULT_EMAIL: [email protected]
      PGADMIN_DEFAULT_PASSWORD: admin

  # Only with --profile monitoring
  prometheus:
    image: prom/prometheus:latest
    profiles: ['monitoring']
    ports:
      - '9090:9090'

  grafana:
    image: grafana/grafana:latest
    profiles: ['monitoring']
    ports:
      - '3001:3000'

volumes:
  db_data:

# Default: api + db only
docker compose up -d

# Debug: api + db + pgadmin
docker compose --profile debug up -d

# Monitoring: api + db + prometheus + grafana
docker compose --profile monitoring up -d

# Multiple profiles
docker compose --profile debug --profile monitoring up -d

# Via environment variable
COMPOSE_PROFILES=debug,monitoring docker compose up -d

Profile 命名规则： [a-zA-Z0-9][a-zA-Z0-9_.-]+ — 推荐使用小写连字符格式。

Include — 可组合配置

顶层键 include（在 Compose 2.20 中引入）允许你将大型 compose 文件拆分成模块化、由团队负责维护的部分。每个被包含的文件都会在其自身的项目目录上下文中加载，从而正确解析相对路径。

# compose.yaml (root — application layer)
include:
  - ./infra/compose.yaml # DB, Redis, message broker
  - ./monitoring/compose.yaml # Prometheus, Grafana

services:
  api:
    build: .
    depends_on:
      - db # defined in infra/compose.yaml
      - redis # defined in infra/compose.yaml

# infra/compose.yaml (infrastructure layer — owned by platform team)
services:
  db:
    image: postgres:16-alpine
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 5s
      timeout: 3s
      retries: 5
    volumes:
      - db_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  db_data:

include 支持递归——被包含的文件本身也可以包含其他文件。资源名称冲突会导致错误（不会静默合并）。

健康检查最佳实践

始终为有状态服务定义健康检查，以确保 depends_on: condition: service_healthy 正常工作。如果没有健康检查，依赖服务可能会在其依赖项就绪前启动。

services:
  db:
    image: postgres:16-alpine
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER:-postgres}']
      interval: 10s # How often to check
      timeout: 5s # Time to wait for response
      retries: 5 # Failures before marking unhealthy
      start_period: 30s # Grace period during container startup

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 10s
      timeout: 3s
      retries: 3

  api:
    build: .
    depends_on:
      db:
        condition: service_healthy # waits until db passes healthcheck
      redis:
        condition: service_healthy

健康检查指南：

• 尽可能使用 CMD（数组形式），而不是 CMD-SHELL（字符串形式）——可避免 Shell 注入风险
• 仅在需要 Shell 功能时使用 CMD-SHELL（例如 pg_isready、curl -f 等）
• 对启动缓慢的服务（JVM 应用、首次运行时的迁移）设置 start_period
• 除非明确安装了 curl，否则避免在基于 Alpine 的镜像中使用它；优先使用 wget -q --spider 或原生检查
• 对于 HTTP 服务：test: ["CMD-SHELL", "wget -q --spider http://localhost:3000/health || exit 1"]

多阶段构建模式

使用多阶段 Dockerfile，使生产镜像保持精简且安全。在 compose.yaml 中为开发指定对应的构建阶段。

# Dockerfile
# Stage 1: deps — install dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

# Stage 2: builder — compile/transpile
FROM deps AS builder
COPY . .
RUN npm run build

# Stage 3: runner — minimal production image
FROM node:20-alpine AS runner
RUN addgroup -g 1001 -S appgroup && adduser -S -u 1001 -G appgroup appuser
WORKDIR /app
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
COPY --from=deps    --chown=appuser:appgroup /app/node_modules ./node_modules
USER appuser
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD wget -q --spider http://localhost:3000/health || exit 1
CMD ["node", "dist/index.js"]

# compose.yaml — dev targets the builder stage for faster iteration
services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
      target: builder # Stop at builder stage in dev (includes devDeps)
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - node_modules/
        - action: rebuild
          path: package.json

# compose.prod.yaml — production uses the full runner stage
services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
      target: runner # Minimal, non-root production image
    restart: unless-stopped

资源限制（最佳实践）

始终定义资源限制，以防止容器耗尽资源：

services:
  api:
    image: myapp:latest
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 128M
    restart: unless-stopped

工具

此技能在服务管理、监控、构建操作和故障排除类别中提供 15 个工具：

服务管理（5 个工具）

up

启动 compose.yaml 中定义的服务。

参数	类型	描述	默认值
detached	boolean	以分离模式运行	true
build	boolean	启动前构建镜像	false
force_recreate	boolean	重新创建容器	false
project_name	string	覆盖项目名称	目录名称
services	array	要启动的指定服务	所有服务
profiles	array	要激活的 Profiles	无
watch	boolean	启用 Compose Watch 模式	false

示例：

docker compose up -d
docker compose up --build
docker compose up web api
docker compose --profile debug up -d
docker compose up --watch

安全性：在生产环境中需要确认。

down

停止并移除容器、网络和卷。

参数	类型	描述	默认值
volumes	boolean	移除卷（已阻止）	false
remove_orphans	boolean	移除孤立容器	false
project_name	string	覆盖项目名称	目录名称

示例：

docker compose down
docker compose down --remove-orphans

安全说明：默认情况下，移除卷（-v 标志）已阻止。需要确认。

start

启动现有容器，不重新创建。

参数	类型	描述	默认值
services	array	要启动的特定服务	所有服务
project_name	string	覆盖项目名称	目录名称

示例：

docker compose start
docker compose start web

stop

停止正在运行的容器，但不移除它们。

参数	类型	描述	默认值
timeout	number	关闭超时时间（秒）	10
services	array	要停止的特定服务	所有服务
project_name	string	覆盖项目名称	目录名称

示例：

docker compose stop
docker compose stop --timeout 30 web

restart

重启服务（停止 + 启动）。

参数	类型	描述	默认值
timeout	number	关闭超时时间（秒）	10
services	array	要重启的特定服务	所有服务
project_name	string	覆盖项目名称	目录名称

示例：

docker compose restart
docker compose restart api

状态与日志（3 个工具）

ps

列出容器及其状态信息。

参数	类型	描述	默认值
all	boolean	显示所有容器（包括已停止的容器）	false
services	array	按服务筛选	所有服务
project_name	string	覆盖项目名称	目录名称

示例：

docker compose ps
docker compose ps --all

输出字段：NAME、IMAGE、STATUS、PORTS

logs

查看服务日志，支持流式输出。

参数	类型	描述	默认值
services	array	要查看日志的服务	所有服务
follow	boolean	跟踪日志输出（流式）	false
tail	number	显示的行数	100
timestamps	boolean	显示时间戳	false
since	string	显示指定时间戳/时长之后的日志	无
project_name	string	覆盖项目名称	目录名称

示例：

docker compose logs web
docker compose logs --tail 50 --follow api
docker compose logs --since "2026-01-01T10:00:00"

注意：跟踪模式会在 60 秒后自动终止，以防止无限期流式输出。

top

显示容器中的运行进程。

参数	类型	描述	默认值
services	array	要检查的服务	所有服务
project_name	string	覆盖项目名称	目录名称

示例：

docker compose top
docker compose top web

输出：包含 PID、USER、TIME、COMMAND 的进程列表

构建与镜像（3 个工具）

build

构建或重新构建服务镜像。

参数	类型	说明	默认值
no_cache	boolean	不使用缓存进行构建	false
pull	boolean	拉取较新版本的镜像	false
parallel	boolean	并行构建	true
services	array	要构建的服务	所有服务
project_name	string	覆盖项目名称	目录名称

示例：

docker compose build
docker compose build --no-cache web
docker compose build --pull

安全性：无缓存构建需要确认（资源密集型）。

pull

从注册表拉取服务镜像。

参数	类型	说明	默认值
ignore_pull_failures	boolean	拉取失败时继续	false
services	array	要拉取的服务	所有服务
project_name	string	覆盖项目名称	目录名称

示例：

docker compose pull
docker compose pull web api

安全性：在生产环境中需要确认。

images

列出服务使用的镜像。

参数	类型	说明	默认值
project_name	string	覆盖项目名称	目录名称

示例：

docker compose images

输出字段：CONTAINER、REPOSITORY、TAG、IMAGE ID、SIZE

执行（2 个工具）

exec

在运行中的容器内执行命令。

参数	类型	说明	必填
service	string	服务名称	是
command	array	要执行的命令	是
user	string	执行命令的用户	容器默认值
workdir	string	工作目录	容器默认值
env	object	环境变量	无
project_name	string	覆盖项目名称	目录名称

示例：

docker compose exec web bash
docker compose exec -u root api ls -la /app
docker compose exec db psql -U postgres

安全性：

• 破坏性命令（rm -rf、dd、mkfs）会被阻止
• 以 root 用户身份执行需要确认
• 默认超时：30 秒

run

在新容器中运行一次性命令。

参数	类型	说明	默认值
service	string	要运行的服务	必填
command	array	要执行的命令	服务默认值
rm	boolean	运行后移除容器	true
no_deps	boolean	不启动关联服务	false
user	string	执行命令的用户	容器默认值
env	object	环境变量	无
project_name	string	覆盖项目名称	目录名称

示例：

docker compose run --rm web npm test
docker compose run --no-deps api python manage.py migrate

安全性：修改数据的命令需要确认。

配置（2 个工具）

config

验证并查看 Compose 文件配置。

参数	类型	说明	默认值
resolve_image_digests	boolean	将镜像标签固定为摘要	false
no_interpolate	boolean	不插值环境变量	false
project_name	string	覆盖项目名称	目录名称

示例：

docker compose config
docker compose config --resolve-image-digests

输出：解析并合并后的 Compose 配置

port

打印服务端口的公共端口绑定。

参数	类型	描述	必填
service	string	服务名称	是
private_port	number	容器端口	是
protocol	string	协议（tcp/udp）	tcp
project_name	string	覆盖项目名称	目录名称

示例：

docker compose port web 80
docker compose port db 5432

输出：<host>:<port> 绑定

常见工作流

启动开发环境

# 1. Validate configuration
docker compose config

# 2. Pull latest images
docker compose pull

# 3. Build custom images
docker compose build

# 4. Start services in detached mode
docker compose up -d

# 5. Check service status
docker compose ps

# 6. View logs
docker compose logs --tail 100

使用 Compose Watch 进行实时开发

# 1. Ensure develop.watch blocks are configured in compose.yaml

# 2. Start with watch mode (foreground, shows sync events)
docker compose watch

# 3. Or start detached then watch
docker compose up -d
docker compose watch --no-up

排查服务故障

# 1. Check container status
docker compose ps --all

# 2. View service logs
docker compose logs --tail 200 failing-service

# 3. Inspect running processes
docker compose top failing-service

# 4. Check configuration
docker compose config

# 5. Restart the service
docker compose restart failing-service

# 6. If needed, recreate container
docker compose up -d --force-recreate failing-service

更新服务镜像

# 1. Pull latest images
docker compose pull

# 2. Stop services
docker compose down

# 3. Rebuild if using custom Dockerfiles
docker compose build --pull

# 4. Start with new images
docker compose up -d

# 5. Verify services
docker compose ps

调试服务连通性

# 1. Check running services
docker compose ps

# 2. Inspect port mappings
docker compose port web 80
docker compose port api 3000

# 3. Exec into container
docker compose exec web sh

# 4. Test connectivity (from inside container)
docker compose exec web curl api:3000/health

# 5. Check logs for errors
docker compose logs web api

清理环境

# 1. Stop all services
docker compose down

# 2. Remove orphaned containers
docker compose down --remove-orphans

# 3. View images
docker compose images

# 4. Clean up (manual - volume removal BLOCKED)
# Volumes require manual cleanup with explicit confirmation

使用配置文件为不同环境指定服务

# Development: default services only
docker compose up -d

# Development + debug tools
docker compose --profile debug up -d

# Start monitoring stack
docker compose --profile monitoring up -d

# Via env var (useful in CI)
COMPOSE_PROFILES=monitoring docker compose up -d

# Stop and clean a specific profile
docker compose --profile debug down

配置

环境变量

变量	描述	默认值
COMPOSE_PROJECT_NAME	默认项目名称	目录名称
COMPOSE_FILE	Compose 文件路径	compose.yaml
COMPOSE_PROFILES	以逗号分隔的活动配置文件	（无）
COMPOSE_PATH_SEPARATOR	多个文件的路径分隔符	:（Linux/Mac），;（Windows）
DOCKER_HOST	Docker 守护进程套接字	unix:///var/run/docker.sock
COMPOSE_HTTP_TIMEOUT	API 调用的 HTTP 超时时间	60
COMPOSE_PARALLEL_LIMIT	最大并行操作数	不限

设置

1. 安装 Docker Engine：

   # macOS
   brew install --cask docker
   
   # Linux (Ubuntu/Debian)
   sudo apt-get update
   sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin
   
   # Windows
   # Download Docker Desktop from docker.com
   

2. 验证 Docker Compose：

   # Check Docker version
   docker --version
   
   # Check Compose version (must be V2, e.g. 2.24+)
   docker compose version
   

3. 创建 compose.yaml（不含 version: 字段 — V2 不需要该字段）：

   services:
     web:
       build: .
       ports:
         - '8080:80'
       depends_on:
         db:
           condition: service_healthy
     db:
       image: postgres:16-alpine
       environment:
         POSTGRES_PASSWORD: example
       healthcheck:
         test: ['CMD-SHELL', 'pg_isready -U postgres']
         interval: 10s
         timeout: 5s
         retries: 5
   

4. 测试该技能：

   docker compose config
   docker compose ps
   

安全功能

已阻止的操作

默认情况下，以下操作会被阻止，以防止意外丢失数据：

• 移除卷：docker compose down -v（已阻止 — 需要手动确认）
• 完全清理：docker compose down -v --rmi all（已阻止 — 破坏性极强）
• 破坏性执行：在容器内执行 rm -rf、dd、mkfs、sudo rm（已阻止）
• 强制移除：docker compose rm -f（已阻止 — 请先停止，再移除）

需要确认的操作

以下操作需要明确确认：

• 使用 --no-cache 构建（资源消耗较大）
• 在生产环境中拉取镜像
• 使用 --force-recreate 启动服务
• 以 root 用户执行命令
• 执行会修改数据库的命令
• 使用极短超时时间停止服务

自动终止的操作

以下操作会自动终止，以防止资源问题：

• 跟踪日志（--follow）：超时时间为 60 秒
• 执行服务命令（exec）：超时时间为 30 秒
• 一次性命令（run）：超时时间为 60 秒

错误处理

常见错误：

错误	原因	解决方法
docker: command not found	未安装 Docker	安装 Docker Engine
Cannot connect to Docker daemon	Docker 未运行	启动 Docker 服务
network ... not found	网络清理问题	运行 docker compose down，然后运行 up
port is already allocated	端口冲突	更改端口映射或停止冲突的服务
no configuration file provided	缺少 compose 文件	创建 compose.yaml
service ... must be built	镜像尚未构建	运行 docker compose build
service unhealthy	健康检查失败	检查 docker compose logs <service>
include path not found	缺少被包含的文件	检查 include: 块中的路径

恢复：

• 验证配置：docker compose config
• 检查 Docker 状态：docker info
• 查看服务日志：docker compose logs
• 强制重新创建：docker compose up -d --force-recreate
• 清理并重启：docker compose down && docker compose up -d

与 Agent 集成

此技能与以下 Agent 集成：

主要 Agent

• devops：本地开发、CI/CD 集成、容器编排
• developer：应用程序开发、测试、调试

次要 Agent

• qa：集成测试、测试环境设置
• incident-responder：生产问题调试、服务恢复
• cloud-integrator：云部署、迁移到 Kubernetes
• performance-engineer：性能测试、资源优化

渐进式披露

此技能采用渐进式披露，以尽量减少上下文用量：

1. 初始加载：仅加载元数据和工具名称（约 700 个 token）
2. 工具调用：按需加载特定工具的架构（约 100–150 个 token）
3. 结果流式传输：大型输出（日志）以增量方式传输
4. 上下文清理：使用后清除旧结果

上下文优化：

• 使用 --tail 限制日志输出
• 使用服务筛选器定位特定容器
• 对于仅运行的服务，优先使用 ps 而非 ps --all
• 使用 --since 查询指定时间范围内的日志

故障排除

技能问题

未找到 Docker Compose：

# Check Docker Compose version
docker compose version

# V1 (docker-compose) is end-of-life — upgrade to V2
# Docker Compose V2 is integrated into Docker CLI as a plugin

权限被拒绝：

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
newgrp docker

# Verify permissions
docker ps

Compose 文件问题：

# Validate syntax
docker compose config

# Check for errors (quiet mode — exit code only)
docker compose config -q

# View resolved configuration
docker compose config --resolve-image-digests

网络问题：

# List networks
docker network ls

# Remove unused networks
docker network prune

# Recreate services
docker compose down
docker compose up -d

健康检查失败：

# Inspect healthcheck status
docker inspect <container_id> | grep -A 10 Health

# View healthcheck output
docker compose logs <service>

# Manually run the healthcheck command
docker compose exec <service> pg_isready -U postgres

Compose Watch 未同步：

# Verify develop.watch block is present in compose.yaml
docker compose config | grep -A 20 develop

# Ensure Compose version is 2.22+
docker compose version

# Watch requires build: attribute (not image: only)

性能注意事项

• 构建缓存：使用层缓存加快构建；除非必要，否则避免使用 --no-cache
• 多阶段构建：大幅减小生产镜像体积（通常可减少 80% 以上）
• 并行操作：Docker Compose V2 默认并行执行；使用 COMPOSE_PARALLEL_LIMIT 控制
• 资源限制：在 compose 文件中定义 CPU/内存限制，避免资源耗尽
• 日志轮转：使用日志驱动程序，避免磁盘空间问题
• 卷清理：定期清理未使用的卷（需要手动确认）
• Compose Watch 与绑定挂载：跨平台开发时优先使用 develop.watch；绑定挂载在 macOS/Windows 上存在 I/O 性能问题

相关内容

• Docker Compose 文档：https://docs.docker.com/compose/
• Compose 文件参考：https://docs.docker.com/compose/compose-file/
• Compose Watch 文档：https://docs.docker.com/compose/how-tos/file-watch/
• Compose Profiles 文档：https://docs.docker.com/compose/how-tos/profiles/
• Compose Include 文档：https://docs.docker.com/compose/how-tos/multiple-compose-files/include/
• Docker CLI：https://docs.docker.com/engine/reference/commandline/cli/
• Kubernetes 迁移：.claude/skills/kubernetes-flux/（Kubernetes 编排）

来源

• Docker Compose 文档
• Docker Compose V2
• Compose 规范
• Docker 最佳实践
• 使用 Compose Watch
• 使用 Compose Profiles
• Compose Include 指令

相关技能

• cloud-devops-expert - 云平台（AWS、GCP、Azure）和 Terraform 基础设施

铁律

1. 始终使用 docker compose（V2 插件）——绝不使用已弃用且即将移除的 docker-compose（V1 独立版本）。
2. 绝不在 Compose 文件或已提交的 .env 文件中直接包含机密或凭据——使用外部机密管理，或仅用于文档说明的 .env.example 模板。
3. 始终为其他服务所依赖的服务定义健康检查——没有健康检查时，依赖服务会在其依赖项真正就绪前启动。
4. 绝不将服务端口暴露给主机，除非必须从 Compose 网络外部访问该服务——不必要地暴露主机端口会扩大攻击面。
5. 始终为计划用于生产环境的服务指定资源限制（CPU 和内存）——不受限制的容器可能耗尽其他服务的资源并导致主机崩溃。

反模式

反模式	失败原因	正确做法
使用 docker-compose V1 命令	V1 已弃用；缺少 V2 功能（profiles、merge、watch），且即将移除	使用 docker compose（中间是空格，不是连字符）；通过 docker compose version 验证
在 Compose 文件中硬编码机密	提交到 git 的机密会永久暴露在历史记录中	使用从未跟踪的 .env 文件加载的环境变量引用（${SECRET}）
数据库／缓存服务没有健康检查	应用容器会在数据库就绪前启动；导致启动竞态条件和崩溃	添加包含适当测试命令的 healthcheck:；使用 depends_on: condition: service_healthy
将所有端口暴露给主机（0.0.0.0）	服务可通过任何网络接口访问，包括公共接口	开发时绑定到 127.0.0.1；服务间通信使用内部网络
没有重启策略	在生产环境中，容器崩溃或主机重启后会保持停止状态	对应自动恢复的服务使用 restart: unless-stopped

Memory Protocol（必须遵守）

开始前： 阅读 .claude/context/memory/learnings.md

完成后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现的问题 -> .claude/context/memory/issues.md
• 做出的决定 -> .claude/context/memory/decisions.md

假设工作会被中断：如果未记录在记忆中，就等于从未发生。