docker-compose

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

编写生产级 Docker Compose 配置的专业指南。

何时使用

用户提到以下内容时，始终使用此技能：

• “docker compose”“docker-compose.yml”“compose 文件”
• “compose 怎么写”“compose 配置”
• “多容器”“multi-container”“服务编排”
• “depends_on”“profiles”“override”
• “compose network”“compose volume”

完整文件结构

# compose.yml
name: myapp

services:       # Container definitions
networks:       # Network topology
volumes:        # Persistent storage
secrets:        # Sensitive data (Swarm)
configs:        # Non-sensitive configs (Swarm)

服务 — 核心配置

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

网络

默认网络（自动创建）

# 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'

自定义网络

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:	在 compose.yml 中	简单、变量较少
env_file:	外部 .env.prod	变量较多、按环境配置
.env 文件	项目根目录（自动加载）	默认值、$VARIABLE 替换

.env 文件（自动加载）

# .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 — 服务顺序

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 — 可选服务

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

使用 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

迁移到 Kubernetes

kompose convert -f compose.yml   # Generates K8s YAML files
kubectl apply -f .

工作流 — 推荐编排流程

步骤 1：规划服务：列出所有服务、端口、数据卷和环境变量
步骤 2：编写 compose.yml：定义 services/networks/volumes
步骤 3：配置依赖：depends_on + condition: service_healthy
步骤 4：本地验证：docker compose up -d → docker compose ps → docker compose logs
步骤 5：生产部署：添加资源限制、重启策略和日志轮转 → docker compose -f compose.yml -f compose.prod.yml up -d

注意事项 — 常见问题

• depends_on 未配置健康检查：depends_on 只会等待容器启动，不会等待容器就绪。→ 处理方法：始终添加 condition: service_healthy 和 healthcheck: 块；使用 docker compose ps 验证健康状态。
• 端口冲突：多个服务不能绑定同一个主机端口。→ 处理方法：使用不同的主机端口，或为仅供内部使用的服务移除 ports:（这些服务通过服务名称通信）。
• 绑定挂载路径：相对路径以 Compose 文件所在位置为基准解析。→ 处理方法：使用 ./config 而非 config/；运行 docker compose config 检查解析后的路径。
• .env 文件安全性：.env 文件通常包含机密信息。→ 处理方法：将 .env 添加到 .gitignore；Swarm 使用 Docker secrets；使用包含占位值的 .env.example。
• docker compose 与 docker-compose：现代语法是 docker compose（插件）。→ 处理方法：docker-compose（独立二进制文件）已弃用；始终使用 docker compose（中间有空格）。

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

分类	场景	说明
✅ 能做	多容器应用编排	完整定义 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）	IaC 工具

何时不使用此技能

❌ 跳过	✅ 改用
单容器应用	docker-run
编写 Dockerfile	docker-dockerfile
Kubernetes 部署	K8s 清单 / Helm charts
Docker 基础知识	docker-basics

安全与稳定性

• 后端网络使用 internal: true，以阻止外部访问。
• 切勿提交包含机密信息的 .env 文件。使用 CI secrets 或 Docker Swarm secrets。
• 单主机上的生产 Compose 部署：结合 systemd 实现开机自动启动。
• 多主机生产环境：迁移到 Swarm（docker stack deploy）或 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