Docker Compose — 多容器编排与 Compose 文件
Expert guidance for writing production-grade Docker Compose configurations.
When to Use
ALWAYS use this skill when the user mentions:
- "docker compose", "docker-compose.yml", "compose 文件"
- "compose 怎么写", "compose 配置"
- "多容器", "multi-container", "服务编排"
- "depends_on", "profiles", "override"
- "compose network", "compose volume"
Complete File Structure
# compose.yml
name: myapp
services: # Container definitions
networks: # Network topology
volumes: # Persistent storage
secrets: # Sensitive data (Swarm)
configs: # Non-sensitive configs (Swarm)
Services — Core Configuration
services:
web:
image: myapp:${TAG:-latest} # Pull from registry
# build: . # Or build from Dockerfile
# build: # Build with options
# context: .
# dockerfile: Dockerfile.prod
container_name: myapp-web # Explicit name (optional)
hostname: web
ports:
- "8080:8080" # host:container
- "127.0.0.1:8443:443" # bind to localhost
- "8080:8080/udp" # UDP
environment:
- NODE_ENV=production
- DB_HOST=db # Service name = hostname!
# env_file: .env.production # Load from file
volumes:
- app-logs:/var/log/app # Named volume
- ./config:/etc/app:ro # Bind mount (read-only)
- /tmp/app:/tmp # Bind mount (read-write)
depends_on:
db:
condition: service_healthy # Wait for health check
redis:
condition: service_started
healthcheck:
test: ["CMD", "wget", "-qO-", "http://localhost:8080/health"]
interval: 30s
timeout: 3s
retries: 3
start_period: 10s
restart: unless-stopped
deploy: # Swarm-only
replicas: 3
resources:
limits:
cpus: '0.5'
memory: 512M
profiles: # Optional service
- debug
Networking
Default Network (Auto-Created)
# Compose auto-creates a default bridge network.
# All services can reach each other by service name.
services:
web:
ports: ["8080:8080"]
db:
# No ports exposed externally — only accessible by 'web'
Custom Networks
networks:
frontend: # Public-facing
backend:
internal: true # No external access
services:
web:
networks: [frontend, backend] # In both networks
db:
networks: [backend] # Backend only (isolated)
cache:
networks: [backend]
Environment Variables
Approaches
| Method | Where | Best For |
|--------|-------|----------|
| environment: | In compose.yml | Simple, few vars |
| env_file: | External .env.prod | Many vars, env-specific |
| .env file | Project root (auto-loaded) | Default values, $VARIABLE substitution |
.env File (Auto-Loaded)
# .env — auto-loaded by docker compose
TAG=v1.2.3
DB_PASSWORD=secret123
# compose.yml — uses ${TAG} and ${DB_PASSWORD}
services:
web:
image: myapp:${TAG:-latest}
db:
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
env_file
# .env.production
DB_HOST=prod-db.example.com
DB_PORT=5432
services:
web:
env_file: .env.production
Depends On — Service Order
services:
db:
image: postgres:16-alpine
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
retries: 5
web:
depends_on:
db:
condition: service_healthy # Wait for DB to be ready
redis:
condition: service_started # Wait for Redis to start
Profiles — Optional Services
services:
app:
image: myapp
debug-tools:
image: nicolaka/netshoot
command: sleep infinity
profiles: [debug] # Only starts with --profile
elasticsearch:
image: elasticsearch:8.15.0
profiles: [analytics] # Only starts with --profile
docker compose --profile debug up # Starts app + debug-tools
docker compose --profile analytics up # Starts app + elasticsearch
Multi-Environment with Override
compose.yml # Base configuration
compose.override.yml # Local dev overrides (auto-applied)
compose.prod.yml # Production overrides
# Local: compose.yml + compose.override.yml (auto)
docker compose up -d
# Production: explicit files
docker compose -f compose.yml -f compose.prod.yml up -d
Migration to Kubernetes
kompose convert -f compose.yml # Generates K8s YAML files
kubectl apply -f .
Workflow — 推荐编排流程
Step 1: 规划服务: 列出所有服务、端口、数据卷、环境变量
Step 2: 编写 compose.yml: 定义 services/networks/volumes
Step 3: 配置依赖: depends_on + condition: service_healthy
Step 4: 本地验证: docker compose up -d → docker compose ps → docker compose logs
Step 5: 生产部署: 添加 resource limits、restart policy、日志轮转 → docker compose -f compose.yml -f compose.prod.yml up -d
Gotchas — Common Pitfalls
- depends_on without healthcheck:
depends_on only waits for container START, not READY. → Recovery: Always add condition: service_healthy + healthcheck: block; use docker compose ps to verify health status.
- Port conflict: Multiple services can't bind the same host port. → Recovery: Use different host ports or remove
ports: for internal-only services (they communicate via service name).
- Bind mount paths: Relative paths are resolved from the compose file location. → Recovery: Use
./config not config/; verify with docker compose config to see resolved paths.
.env file security: .env files often contain secrets. → Recovery: Add .env to .gitignore; use Docker secrets for Swarm; use .env.example with placeholder values.docker compose vs docker-compose: Modern syntax is docker compose (plugin). → Recovery: docker-compose (standalone binary) is deprecated; always use docker compose (with space).
Boundary — 能力边界（适用与不适用场景）
| 分类 | 场景 | 说明 |
|------|------|------|
| ✅ 能做 | 多容器应用编排 | services/networks/volumes/secrets/configs 完整定义 |
| ✅ 能做 | 环境管理 | .env / env_file / override 文件策略 |
| ✅ 能做 | 依赖控制 | depends_on + healthcheck + profiles |
| ⚠️ 需条件 | 多主机部署 | 迁移到 Swarm（docker stack deploy）或 K8s |
| ⚠️ 需条件 | 滚动更新/自动扩缩 | Compose 不支持，需 Swarm 或 K8s |
| ❌ 超范围 | 编写 Dockerfile | 使用 docker-dockerfile |
| ❌ 超范围 | K8s 部署 | 使用 kompose convert + K8s 技能 |
| ❌ 超范围 | 云服务编排（Terraform） | IaaC 工具 |
When NOT to Use This Skill
| ❌ Skip | ✅ Use Instead |
|---------|---------------|
| Single-container apps | docker-run |
| Writing Dockerfile | docker-dockerfile |
| Kubernetes deployment | K8s manifests / Helm charts |
| Docker basics | docker-basics |
Security & Stability
- Use
internal: true for backend networks to prevent external access.
- Never commit
.env files with secrets. Use CI secrets or Docker Swarm secrets.
- Production Compose on single host: combine with systemd for auto-start on boot.
- Multi-host production: migrate to Swarm (
docker stack deploy) or Kubernetes.
📚 官方文档参考
| 文档 | 地址 |
|------|------|
| Docker Compose 概述 | https://docs.docker.com/compose/ |
| Compose 文件参考 | https://docs.docker.com/reference/compose-file/ |
| Compose CLI | https://docs.docker.com/reference/cli/docker/compose/ |
| 环境变量 | https://docs.docker.com/compose/environment-variables/ |
| Compose 网络 | https://docs.docker.com/compose/networking/ |
| 生产环境 Compose | https://docs.docker.com/compose/production/ |
🧭 Docker Skills Journey
📍 You are here: docker-compose — 多容器编排
← Previous: docker-buildx / docker-networking
→ Next: docker-production / docker-cicd