Docker Compose

Docker Compose 是 Docker 官方推出的一个工具，用于定义和运行多容器 Docker 应用程序。它通过一个 YAML 文件（默认 compose.yml 或 docker-compose.yml）来配置所有服务，使得多容器的定义、部署和管理变得简单高效。

Docker 官方已用 Go 重写了 Compose（V2），作为 docker CLI 子命令。将 docker-compose 替换为 docker compose 即可使用。下文统一使用 docker compose。

安装

Docker Desktop 自带 Compose 插件。Linux 独立安装：

# 插件方式（推荐，随 docker 一起）
docker compose version

# 独立二进制（旧 V1 方式，已不推荐）
sudo curl -L "https://github.com/docker/compose/releases/download/v2.22.20/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

基础结构

services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
  mysql:
    image: mysql:8
    environment:
      MYSQL_ROOT_PASSWORD: example

默认 Compose 会为项目创建独立 bridge 网络，服务间可用服务名互相访问（如 web 访问 mysql 主机名）。

生产级配置

健康检查 healthcheck

让编排器/依赖顺序感知服务真实就绪状态：

services:
  db:
    image: mysql:8
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
  app:
    image: myapp
    depends_on:
      db:
        condition: service_healthy   # 等 db 健康后才启动

资源限制

services:
  app:
    deploy:
      resources:
        limits:
          cpus: "2"
          memory: 512M
        reservations:
          memory: 256M

注意：deploy.resources 在 docker compose up 下默认生效（新版 Compose 已支持），旧版需 docker stack deploy。

重启策略

services:
  app:
    restart: unless-stopped   # 推荐：除手动停止外总是重启

日志轮转

防止日志打满磁盘（详见 Docker 存储）：

services:
  app:
    logging:
      driver: json-file
      options:
        max-size: "100m"
        max-file: "3"

只读文件系统与降权

services:
  app:
    read_only: true
    tmpfs:
      - /tmp
    user: "1000:1000"

卷挂载

services:
  mysql:
    image: mysql:8
    volumes:
      - db-data:/var/lib/mysql        # 命名卷
      - ./my.cnf:/etc/mysql/my.cnf:ro # 绑定挂载（只读）
volumes:
  db-data:

多环境（override 文件）

用多个文件叠加，避免重复：

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

# 叠加生产配置
docker compose -f compose.yml -f compose.prod.yml up -d

compose.prod.yml 示例（仅覆盖差异）：

services:
  app:
    image: myapp:prod
    environment:
      NODE_ENV: production

也可通过 .env 文件注入变量：

services:
  app:
    image: myapp:${TAG:-latest}
    environment:
      - TZ=${TZ}

# .env
TAG=2026-08-28-abc1234
TZ=Asia/Shanghai

常用命令

docker compose up               # 前台启动
docker compose up -d            # 后台启动
docker compose down             # 停止并删除容器/网络
docker compose down -v          # 同时删除卷
docker compose ps               # 查看状态
docker compose logs -f app      # 跟踪某服务日志
docker compose build            # 构建本地镜像服务
docker compose config           # 校验并查看最终配置
docker compose exec app sh      # 进入服务容器

实战：监控栈（cAdvisor + Prometheus）

监控类容器常需挂载宿主机目录才能采集指标。参考天眼 Alloy 的 cAdvisor 配置经验，容器指标采集三要件缺一不可：

1. docker.sock（列出容器）
2. /sys:/sys:ro（读取 cgroup）
3. /var/lib/docker:/var/lib/docker:ro（读取 overlay2 layerdb）

services:
  cadvisor:
    image: gcr.io/cadvisor/cadvisor:latest
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker:/var/lib/docker:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "8080:8080"
    restart: unless-stopped

若仅挂载 /sys:/host/sys:ro 而缺 /sys:/sys:ro，cAdvisor 读不到宿主机 cgroup 视图，会报 "failed to identify the read-write layer ID" 而采集失败。

最佳实践

1. 用 depends_on + condition: service_healthy 控制启动顺序。
2. 数据库等用命名卷持久化，配置用只读绑定挂载。
3. 配置日志轮转与资源限制，防止单服务拖垮宿主机。
4. 多环境用 override 文件 + .env 管理。
5. 生产镜像用固定 tag，避免 latest。