Docker Compose

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

.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 — 能力边界（适用与不适用场景）

When NOT to Use This Skill

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 Skills Journey

📍 You are here: `docker-compose` — 多容器编排

← Previous: docker-buildx / docker-networking → Next: docker-production / docker-cicd

LAMP 全栈部署 — Nginx + PHP-FPM + MySQL + Redis

compose.yml

name: lamp-stack

services:
  web:
    image: nginx:1.27-alpine
    ports:
      - "8080:80"
    volumes:
      - ./app:/var/www/html:ro
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - web_logs:/var/log/nginx
    networks:
      - frontend
    depends_on:
      php:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost/health"]
      interval: 30s
      timeout: 3s
      retries: 3

  php:
    build:
      context: ./php
      dockerfile: Dockerfile
    volumes:
      - ./app:/var/www/html:ro
    networks:
      - frontend
      - backend
    environment:
      PHP_FPM_PM: dynamic
      PHP_FPM_PM_MAX_CHILDREN: "10"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "php-fpm-healthcheck"]
      interval: 30s
      timeout: 3s
      retries: 3

  db:
    image: mysql:8.4
    ports:
      - "3306:3306"
    volumes:
      - db_data:/var/lib/mysql
      - ./mysql/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
    networks:
      - backend
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p${MYSQL_ROOT_PASSWORD}"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
      - ./redis/redis.conf:/usr/local/etc/redis/redis.conf:ro
    networks:
      - backend
    command: redis-server /usr/local/etc/redis/redis.conf
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true

volumes:
  db_data:
    driver: local
  redis_data:
    driver: local
  web_logs:
    driver: local

.env

MYSQL_ROOT_PASSWORD=rootpass123
MYSQL_DATABASE=myapp
MYSQL_USER=myuser
MYSQL_PASSWORD=mypass123

启动

docker compose up -d
docker compose ps
docker compose logs -f

微服务编排 — API Gateway + 3 服务 + Kafka + DB

compose.yml

name: microservices

services:
  gateway:
    image: nginx:1.27-alpine
    ports:
      - "8080:80"
    volumes:
      - ./gateway/nginx.conf:/etc/nginx/nginx.conf:ro
    networks:
      - public
      - internal
    depends_on:
      user-service:
        condition: service_healthy
      order-service:
        condition: service_healthy
      product-service:
        condition: service_healthy
    restart: unless-stopped

  user-service:
    build:
      context: ./services/user
      dockerfile: Dockerfile
    networks:
      - internal
    environment:
      DB_HOST: user-db
      DB_PORT: "5432"
      DB_NAME: users
      DB_USER: ${DB_USER}
      DB_PASSWORD: ${DB_PASSWORD}
      KAFKA_BROKERS: kafka:9092
    depends_on:
      user-db:
        condition: service_healthy
      kafka:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8081/health"]
      interval: 15s
      timeout: 3s
      retries: 3
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "0.5"

  user-db:
    image: postgres:16-alpine
    volumes:
      - user_db_data:/var/lib/postgresql/data
    networks:
      - internal
    environment:
      POSTGRES_DB: users
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER} -d users"]
      interval: 10s
      timeout: 5s
      retries: 5

  order-service:
    build:
      context: ./services/order
      dockerfile: Dockerfile
    networks:
      - internal
    environment:
      DB_HOST: order-db
      KAFKA_BROKERS: kafka:9092
    depends_on:
      order-db:
        condition: service_healthy
      kafka:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8082/health"]
      interval: 15s
      timeout: 3s
      retries: 3

  order-db:
    image: mysql:8.4
    volumes:
      - order_db_data:/var/lib/mysql
    networks:
      - internal
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MYSQL_DATABASE: orders
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

  product-service:
    build:
      context: ./services/product
      dockerfile: Dockerfile
    networks:
      - internal
    environment:
      MONGO_HOST: product-db
      KAFKA_BROKERS: kafka:9092
    depends_on:
      product-db:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8083/health"]
      interval: 15s
      timeout: 3s
      retries: 3

  product-db:
    image: mongo:7
    volumes:
      - product_db_data:/data/db
    networks:
      - internal
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
      interval: 10s
      timeout: 5s
      retries: 5

  kafka:
    image: bitnami/kafka:3.7
    networks:
      - internal
    environment:
      KAFKA_CFG_NODE_ID: 0
      KAFKA_CFG_PROCESS_ROLES: controller,broker
      KAFKA_CFG_CONTROLLER_QUORUM_VOTERS: 0@kafka:9093
      KAFKA_CFG_LISTENERS: PLAINTEXT://:9092,CONTROLLER://:9093
      KAFKA_CFG_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092
      KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
      KAFKA_CFG_CONTROLLER_LISTENER_NAMES: CONTROLLER
    volumes:
      - kafka_data:/bitnami/kafka
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "kafka-topics.sh", "--bootstrap-server", "localhost:9092", "--list"]
      interval: 30s
      timeout: 10s
      retries: 5

networks:
  public:
    driver: bridge
  internal:
    driver: bridge
    internal: true

volumes:
  user_db_data:
  order_db_data:
  product_db_data:
  kafka_data:

启动策略

# 1. 先启动基础设施（DB + Kafka）
docker compose up -d user-db order-db product-db kafka

# 2. 等基础设施就绪后启动服务
docker compose up -d user-service order-service product-service

# 3. 最后启动网关
docker compose up -d gateway

监控栈 — Prometheus + Grafana + cAdvisor + Loki

compose.yml

name: monitoring

services:
  prometheus:
    image: prom/prometheus:v3.1.0
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus_data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
      - '--storage.tsdb.retention.time=30d'
      - '--web.enable-lifecycle'
    networks:
      - monitoring
    restart: unless-stopped

  grafana:
    image: grafana/grafana:11.4.0
    ports:
      - "3000:3000"
    volumes:
      - grafana_data:/var/lib/grafana
      - ./grafana/datasources:/etc/grafana/provisioning/datasources:ro
      - ./grafana/dashboards:/etc/grafana/provisioning/dashboards:ro
    environment:
      GF_SECURITY_ADMIN_USER: ${GRAFANA_USER:-admin}
      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD:-admin}
      GF_USERS_ALLOW_SIGN_UP: "false"
    networks:
      - monitoring
    depends_on:
      - prometheus
      - loki
    restart: unless-stopped

  cadvisor:
    image: gcr.io/cadvisor/cadvisor:v0.50.0
    ports:
      - "8080:8080"
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
      - /dev/disk/:/dev/disk:ro
    privileged: true
    devices:
      - /dev/kmsg
    networks:
      - monitoring
    restart: unless-stopped

  node-exporter:
    image: prom/node-exporter:v1.8.2
    ports:
      - "9100:9100"
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /:/rootfs:ro
    command:
      - '--path.procfs=/host/proc'
      - '--path.sysfs=/host/sys'
      - '--path.rootfs=/rootfs'
    networks:
      - monitoring
    restart: unless-stopped

  loki:
    image: grafana/loki:3.2.0
    ports:
      - "3100:3100"
    volumes:
      - ./loki/loki-config.yaml:/etc/loki/local-config.yaml:ro
      - loki_data:/loki
    command: -config.file=/etc/loki/local-config.yaml
    networks:
      - monitoring
    restart: unless-stopped

  promtail:
    image: grafana/promtail:3.2.0
    volumes:
      - /var/log:/var/log:ro
      - /var/lib/docker/containers:/var/lib/docker/containers:ro
      - ./promtail/promtail-config.yaml:/etc/promtail/config.yml:ro
    command: -config.file=/etc/promtail/config.yml
    networks:
      - monitoring
    depends_on:
      - loki
    restart: unless-stopped

  alertmanager:
    image: prom/alertmanager:v0.28.0
    ports:
      - "9093:9093"
    volumes:
      - ./alertmanager/alertmanager.yml:/etc/alertmanager/alertmanager.yml:ro
      - alertmanager_data:/alertmanager
    networks:
      - monitoring
    restart: unless-stopped

networks:
  monitoring:
    driver: bridge

volumes:
  prometheus_data:
  grafana_data:
  loki_data:
  alertmanager_data:

prometheus/prometheus.yml

global:
  scrape_interval: 15s
  evaluation_interval: 15s

alerting:
  alertmanagers:
    - static_configs:
        - targets: ['alertmanager:9093']

rule_files:
  - '/etc/prometheus/alert.rules.yml'

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: ['localhost:9090']

  - job_name: cadvisor
    static_configs:
      - targets: ['cadvisor:8080']

  - job_name: node-exporter
    static_configs:
      - targets: ['node-exporter:9100']

启动

docker compose up -d

# 访问
# Prometheus: http://localhost:9090
# Grafana:    http://localhost:3000
# cAdvisor:   http://localhost:8080

Compose 文件完整语法速查

顶级元素

Service 配置项速查

镜像与构建

services:
  app:
    image: nginx:1.27-alpine             # 直接拉取
    build:                                # 从 Dockerfile 构建
      context: ./app
      dockerfile: Dockerfile.prod
      args:
        NODE_ENV: production
      target: production                  # 多阶段目标
      platforms:                          # 多平台（BuildKit）
        - linux/amd64
        - linux/arm64
    pull_policy: always                   # always/missing/never

端口

ports:
  - "8080:80"                           # host:container
  - "127.0.0.1:3306:3306"               # 仅本地
  - "9090"                               # 随机 host 端口
  - target: 80
    published: 8080
    protocol: tcp
    mode: host                           # host/ingress (Swarm)

环境变量

environment:
  NODE_ENV: production
  DB_URL: postgres://${DB_USER}:${DB_PASS}@db:5432/mydb

env_file:
  - .env
  - .env.production

# .env 文件（同目录下自动加载，用于变量替换 ${VAR}）
# DB_USER=myuser
# DB_PASS=secret

卷挂载

volumes:
  - data_volume:/var/lib/mysql           # 命名卷
  - ./config:/etc/app/config:ro          # bind mount（绝对/相对路径）
  - /var/run/docker.sock:/var/run/docker.sock  # Docker socket
  - type: bind
    source: ./logs
    target: /var/log/app
  - type: tmpfs
    target: /tmp
    tmpfs:
      size: 128M

依赖与启动顺序

depends_on:
  db:
    condition: service_healthy           # service_started/service_healthy/service_completed_successfully
    restart: true                        # 依赖重启时本服务也重启

  redis:
    condition: service_started

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
  interval: 30s
  timeout: 5s
  retries: 3
  start_period: 10s
  start_interval: 2s

资源限制（Compose v2.x / docker compose）

deploy:
  resources:
    limits:
      cpus: "0.5"
      memory: 256M
      pids: 100
    reservations:
      cpus: "0.25"
      memory: 128M

重启策略

restart: unless-stopped                  # no/always/on-failure[:max-retries]/unless-stopped

deploy:
  restart_policy:
    condition: on-failure                # none/on-failure/any
    delay: 5s
    max_attempts: 3
    window: 120s

其他常用

command: ["npm", "start"]               # 覆盖 CMD
entrypoint: ["/custom-entrypoint.sh"]    # 覆盖 ENTRYPOINT
user: "1000:1000"                        # 运行用户
working_dir: /app                        # 工作目录
stdin_open: true                         # -i
tty: true                                # -t
profiles:                                # 按 profile 启动
  - debug
  - tools
extra_hosts:                             # 额外 hosts
  - "host.docker.internal:host-gateway"
dns:
  - 8.8.8.8
  - 1.1.1.1

Networks

networks:
  frontend:
    driver: bridge
    driver_opts:
      com.docker.network.bridge.name: br-frontend
    ipam:
      config:
        - subnet: 172.28.0.0/16
    internal: false                       # 是否禁止外部访问

  backend:
    driver: bridge
    internal: true                        # 仅内部互通
    attachable: true                      # 允许外部容器连接

Volumes

volumes:
  db_data:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /mnt/data/db
    labels:
      backup: daily

  nfs_data:
    driver: local
    driver_opts:
      type: nfs
      o: addr=192.168.1.100,nolock,rw
      device: ":/exports/data"

Profiles（可选服务）

services:
  app:
    image: myapp

  debug-tools:
    image: nicolaka/netshoot
    command: sleep infinity
    profiles:
      - debug                              # 仅 --profile debug 时启动

docker compose --profile debug up -d

片段复用（x-扩展）

x-logging: &default-logging
  driver: json-file
  options:
    max-size: "10m"
    max-file: "3"

x-healthcheck: &default-healthcheck
  interval: 30s
  timeout: 3s
  retries: 3

services:
  app1:
    logging: *default-logging
    healthcheck:
      <<: *default-healthcheck
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]

  app2:
    logging: *default-logging
    healthcheck:
      <<: *default-healthcheck
      test: ["CMD", "curl", "-f", "http://localhost:8081/health"]

include（模块化）

# compose.yml
include:
  - path: ./infra/compose.db.yml
  - path: ./infra/compose.mq.yml
  - path: ./services/compose.api.yml

name: full-stack

Compose 环境变量管理策略

三种方式对比

.env 文件（变量替换）

.env 放在 compose.yml 同目录，自动加载用于 ${VAR} 替换，不直接注入容器。

# .env
POSTGRES_VERSION=16
DB_USER=myapp
DB_PASSWORD=secret123

services:
  db:
    image: postgres:${POSTGRES_VERSION:-16}    # 替换为 16
    environment:
      POSTGRES_USER: ${DB_USER}                 # 替换为 myapp
      POSTGRES_PASSWORD: ${DB_PASSWORD}

env_file（注入容器）

services:
  app:
    env_file:
      - .env.common
      - .env.api

# .env.common
TZ=Asia/Shanghai
LOG_LEVEL=info

# .env.api
API_PORT=8080
RATE_LIMIT=100

⚠️ env_file 不用于 $VAR 替换，如需替换请用 .env 或 cli --env-file。

environment（直接声明）

services:
  app:
    environment:
      NODE_ENV: production
      PORT: "8080"
      DATABASE_URL: postgres://user:pass@db:5432/mydb

多环境 override 策略

# compose.yml（基础配置）
services:
  app:
    image: myapp:latest
    ports:
      - "8080:8080"
    environment:
      LOG_LEVEL: info

# compose.override.yml（本地开发，默认自动合并）
services:
  app:
    build: .
    ports:
      - "8080:8080"
      - "9229:9229"           # debug port
    environment:
      NODE_ENV: development
      LOG_LEVEL: debug

# compose.prod.yml（生产环境，-f 显式指定）
services:
  app:
    ports:
      - "80:8080"
    environment:
      NODE_ENV: production
    deploy:
      resources:
        limits:
          memory: 512M
    restart: always

# 开发（自动合并 compose.yml + compose.override.yml）
docker compose up -d

# 生产（合并 compose.yml + compose.prod.yml）
docker compose -f compose.yml -f compose.prod.yml up -d

优先级总结

命令行 -e VAR=val          ← 最高
    ↓
compose.yml environment   ← 中
    ↓
env_file 文件值            ← 低
    ↓
.env 文件默认值 ${VAR:-x}  ← 最低

最佳实践

Compose 网络深度指南

默认网络行为

# compose.yml（不定义 networks）
services:
  web:
    image: nginx
  api:
    image: myapp

启动后自动创建 <project>_default bridge 网络，所有服务加入，可通过 服务名 DNS 互访：

# web 容器中可 ping api 服务名
docker compose exec web ping api

自定义网络

services:
  web:
    networks:
      - frontend
  api:
    networks:
      - frontend
      - backend        # 多网络
  db:
    networks:
      - backend

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true      # 不暴露到宿主机

网络模式选择

services:
  app:
    network_mode: host

  sidecar:
    network_mode: service:app   # 共享 app 的网络

外部网络

连接已存在的 Docker 网络（如独立创建的共享网络）：

docker network create shared-network

services:
  app:
    networks:
      - shared-network

networks:
  shared-network:
    external: true       # 使用已存在的网络

IP 地址分配

networks:
  frontend:
    driver: bridge
    ipam:
      config:
        - subnet: 172.28.0.0/16
          gateway: 172.28.0.1

services:
  app:
    networks:
      frontend:
        ipv4_address: 172.28.0.10

DNS 解析

Compose 内置 DNS，服务名即域名：

服务名 → 该服务的所有容器 IP
<service>.<network> → 指定网络中的容器 IP

services:
  api:
    networks:
      - frontend
      - backend

  web:
    networks:
      - frontend
    # 可以访问: api, api.frontend, api.backend

常见问题

生产级 Compose 部署

资源限制

services:
  api:
    image: myapp:latest
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
          pids: 100
        reservations:
          cpus: "0.5"
          memory: 256M

滚动更新（零停机）

services:
  api:
    image: myapp:latest
    deploy:
      replicas: 3
      update_config:
        parallelism: 1             # 每次更新几个
        delay: 10s                 # 间隔
        failure_action: rollback   # 失败回滚
        monitor: 30s               # 监控新容器是否正常
        max_failure_ratio: 0.3     # 容忍 30% 失败
        order: start-first         # 先启新再停旧
      rollback_config:
        parallelism: 1
        delay: 0s

Secrets 管理

secrets:
  db_password:
    file: ./secrets/db_password.txt
  api_key:
    external: true                  # Swarm 中已存在

services:
  db:
    secrets:
      - db_password
    environment:
      MYSQL_PASSWORD_FILE: /run/secrets/db_password

Configs（非敏感配置）

configs:
  nginx_conf:
    file: ./nginx/nginx.conf

services:
  web:
    configs:
      - source: nginx_conf
        target: /etc/nginx/nginx.conf

日志配置

services:
  api:
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
        labels: "com.docker.compose.project,com.docker.compose.service"

# 使用 loki 驱动
logging:
  driver: loki
  options:
    loki-url: "http://loki:3100/loki/api/v1/push"
    loki-retries: "5"
    loki-batch-size: "400"

systemd 守护

# /etc/systemd/system/myapp.service
[Unit]
Description=MyApp Docker Compose
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/myapp
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
ExecReload=/usr/bin/docker compose restart
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now myapp

Kompose：迁移到 Kubernetes

# 转换
kompose convert -f compose.yml -o k8s/

# 输出
# k8s/api-deployment.yaml
# k8s/api-service.yaml
# k8s/db-deployment.yaml
# k8s/db-service.yaml
# k8s/frontend-networkpolicy.yaml
# k8s/backend-networkpolicy.yaml

# 直接部署到 K8s
kompose up -f compose.yml

Compose vs Swarm vs K8s