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

yaml

# 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

yaml

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)

yaml

# 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

yaml

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)

bash

# .env — auto-loaded by docker compose
TAG=v1.2.3
DB_PASSWORD=secret123

yaml

# compose.yml — uses ${TAG} and ${DB_PASSWORD}
services:
  web:
    image: myapp:${TAG:-latest}
  db:
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

env_file

bash

# .env.production
DB_HOST=prod-db.example.com
DB_PORT=5432

yaml

services:
  web:
    env_file: .env.production

Depends On — Service Order

yaml

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

yaml

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

bash

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

bash

# 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

bash

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

docker-compose

NPX Install

Tags

SKILL.md Content

Docker Compose — 多容器编排与 Compose 文件

When to Use

Complete File Structure

Services — Core Configuration

Networking

Default Network (Auto-Created)

Custom Networks

Environment Variables

Approaches

.env File (Auto-Loaded)

env_file

Depends On — Service Order

Profiles — Optional Services

Multi-Environment with Override

Migration to Kubernetes

Workflow — 推荐编排流程

Gotchas — Common Pitfalls

Boundary — 能力边界（适用与不适用场景）

When NOT to Use This Skill

Security & Stability

📚 官方文档参考

🧭 Docker Skills Journey