Docker Compose 速查表：所有命令与选项一网打尽

Docker Compose 速查表

Docker Compose 让你通过一个 YAML 文件定义和运行多容器应用。本参考涵盖从基本命令到生产就绪模式的所有内容。

基本 CLI 命令

# 启动服务（后台运行）
docker compose up -d

# 停止服务
docker compose down

# 停止并移除卷
docker compose down -v

# 查看运行中的服务
docker compose ps

# 跟踪日志
docker compose logs -f

# 跟踪单个服务的日志
docker compose logs -f web

# 在运行中的容器内执行命令
docker compose exec web bash

# 运行一次性命令（新容器）
docker compose run --rm web python manage.py migrate

# 重新构建镜像
docker compose build

# 拉取最新镜像
docker compose pull

# 扩展服务
docker compose up -d --scale worker=3

# 重启单个服务
docker compose restart web

# 查看资源使用情况
docker compose top

docker-compose.yml 结构

version: "3.9"

services:
  web:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - .:/app
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/mydb
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:16
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: mydb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  postgres_data:

networks:
  default:
    name: myapp_network

构建选项

services:
  web:
    build:
      context: .                    # 构建上下文路径
      dockerfile: Dockerfile.prod   # 自定义 Dockerfile
      args:
        NODE_ENV: production         # 构建时参数
      target: production            # 多阶段构建目标
      cache_from:
        - myregistry/myapp:latest

卷参考

services:
  web:
    volumes:
      # 命名卷（由 Docker 管理）
      - mydata:/app/data

      # 绑定挂载（主机路径）
      - ./src:/app/src

      # 只读绑定挂载
      - ./config:/app/config:ro

      # 匿名卷
      - /app/node_modules

volumes:
  mydata:
    driver: local

  # 外部卷（预先存在）
  external_db:
    external: true

网络

services:
  frontend:
    networks:
      - frontend_net

  backend:
    networks:
      - frontend_net
      - backend_net

  db:
    networks:
      - backend_net

networks:
  frontend_net:
    driver: bridge
  backend_net:
    driver: bridge
    internal: true    # 禁止外部访问

同一网络上的服务可以通过服务名称作为主机名互相访问。frontend 可以调用 http://backend:8080 —— Docker 的内置 DNS 会解析它。

环境变量

services:
  web:
    # 内联值
    environment:
      NODE_ENV: production
      PORT: 3000

    # 从主机环境继承
    environment:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY

    # 从 .env 文件（默认：与 compose 文件同目录下的 .env）
    env_file:
      - .env
      - .env.local

# .env 文件
DATABASE_URL=postgres://localhost/mydb
SECRET_KEY=changeme

Compose 文件中的变量替换：

services:
  web:
    image: myapp:${APP_VERSION:-latest}   # 如果未设置，默认使用 'latest'
    ports:
      - "${HOST_PORT:-3000}:3000"

健康检查

services:
  api:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s      # 检查间隔
      timeout: 10s       # 单次检查超时
      retries: 3         # 失败次数超过此值标记为 'unhealthy'
      start_period: 40s  # 启动后的宽限期

其他测试格式：

# Shell 形式
test: ["CMD-SHELL", "wget -qO- http://localhost/health || exit 1"]

# 禁用继承的健康检查
healthcheck:
  disable: true

重启策略

生产服务使用 unless-stopped，批处理作业使用 on-failure。

资源限制

services:
  web:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M

注意：deploy.resources 需要 Compose v3+，并且适用于 docker compose（而非旧的 docker-compose）。

配置文件（条件服务）

services:
  web:
    image: myapp

  debug-tools:
    image: nicolaka/netshoot
    profiles: ["debug"]

  db-admin:
    image: adminer
    profiles: ["debug", "admin"]

# 仅启动 web
docker compose up -d

# 启动 web + 调试工具
docker compose --profile debug up -d

多个 Compose 文件（覆盖模式）

# 基础配置
docker compose -f docker-compose.yml up

# 基础 + 覆盖（合并）
docker compose -f docker-compose.yml -f docker-compose.prod.yml up

# docker-compose.prod.yml — 覆盖开发默认值
services:
  web:
    build:
      target: production
    environment:
      NODE_ENV: production
    restart: always

常见模式

等待数据库就绪后再启动应用：

services:
  app:
    depends_on:
      db:
        condition: service_healthy  # 等待健康检查通过
  db:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready"]
      interval: 5s
      retries: 10

热重载开发环境：

services:
  web:
    build: .
    command: npm run dev
    volumes:
      - .:/app
      - /app/node_modules  # 保留容器的 node_modules
    ports:
      - "3000:3000"

多阶段：开发 vs 生产：

# docker-compose.yml（开发）
services:
  web:
    build:
      target: development
    volumes:
      - .:/app
    command: npm run dev

# docker-compose.prod.yml
services:
  web:
    build:
      target: production
    command: node dist/server.js
    restart: always

→ 使用 Docker Run → Compose 转换器 将 docker run 命令即时转换为 Compose 文件。