Compose 多容器编排：从概念到可验证实践

0. 元信息

• 主题路径：docs/topics/docker-basics/subtopics/compose-multi-container/README.md
• 主分类：工程技术
• 辅助分类：安全与可靠性
• 适合对象：完成 Linux 基础并按父主题路线学习的开发者
• 建议周期：5～8 天，每天 1.5～2 小时
• 前置知识：container-runtime-network-storage
• 最终目标：能独立完成并解释 Compose Specification、service、network、volume、healthcheck、profile、配置和依赖 的实验，留下配置、命令和输出证据

1. 学习路线

概念与对象 → 最小正常实验 → inspect/日志验证 → 边界与失败实验 → 自动化配置 → 交付说明

2. 阶段周数分配

精简子主题不固定周数。按概念、正常路径、失败路径、综合实验四段推进，共 5～8 天。

3. 九阶段表

4. 第一周任务

精简子主题省略逐日表。每天只引入一个变量；先跑正常路径，再做四类失败实验。

5. 阶段通用验收

采用父主题 §5；本页额外要求保存版本、完整配置、关键输出和清理命令。

6. 最终验收

完成一份可运行配置、至少四个失败案例、一次清理后重建，并用 10 分钟解释关键边界。

7. 综合项目

把本页产出合入父主题 Compose Web 应用。单独交付时，提供最小 demo、README、测试记录与 notes/retrospective.md。

本主题贡献

Compose 把 service、network、volume、healthcheck、depends_on condition、profile 揉成一份 YAML，但很多人没分清 declaration 与 runtime 的差距。本子主题负责把”配置渲染 → 运行状态 → 依赖就绪 → 数据保留”四条线讲到底，避免 depends_on 当 readiness、profile 当 magic、override 默默覆盖关键 limit。

3 职责

1. 用 docker compose config > resolved.yaml 看合并结果，把 env_file / override / secrets 三条入口写清，CI 中跑 diff 防止误覆盖。
2. 用 healthcheck + depends_on.condition: service_healthy 把服务依赖变成可观察的就绪，而不是简单的启动顺序。
3. 用 profile + 多 compose.yaml 区分 dev / staging / prod，secret / config 走 Docker secret 不进 git。

4 交付物

1. 一份 compose.yaml，含 api + db + cache 三服务、backend 网络、两个 named volume、每个服务独立 healthcheck（含 start_period）。
2. 一份 docker-compose.override.yaml（dev 端口映射 + bind mount + extra env），用 config 验证合并结果与 limit 是否被吞。
3. 一份 docker compose config | diff 校验脚本（CI 中跑），防止 override 误覆盖关键 limit 与 healthcheck 参数。
4. 一份 profile 切换脚本（--profile dev / --profile debug），含 compose --profile debug ps 输出与 debug-only sidecar。

3 指标

1. 服务 ready 时间 < 30 s（healthcheck healthy 至所有依赖，时间差取 compose ps 的 Status 列）。
2. docker compose up -d 后 60 s 内无 restart（看 compose ps 的 State 与 Restart 列）。
3. docker compose down -v 误删率 0%（先 list volume 与 backup 校验再执行；named volume 默认不被删除，必须显式 -v 才删）。

Docker Docs 作主线；OCI 文档用于契约；Moby、BuildKit、containerd、runc 源码只在需要确认实现时查。复制前核对当前 LICENSE。

8. 推荐开源资料

Docker Docs 作主线；OCI 文档用于契约；Moby、BuildKit、containerd、runc 源码只在需要确认实现时查。复制前核对当前 LICENSE。

9. 学习资料汇聚（v0.3 自包含）

9.1 背景与动机

本子主题处理：用 Compose 管理服务依赖、网络、存储、healthcheck、配置和环境差异。。Docker 的易用 CLI 会隐藏多层状态。我们通过最小实验、inspect 和失败注入把对象关系变成可观察事实。

9.2 概念地图

flowchart LR
  Spec[声明 / Spec] --> Engine[Docker Engine / BuildKit]
  Engine --> Artifact[image / config / state]
  Artifact --> Runtime[container runtime]
  Runtime --> Evidence[inspect / logs / events / metrics]
  Failure[故障注入] --> Runtime
  Evidence --> Fix[修改与验证]

本页核心概念：Compose Specification、service、network、volume、healthcheck、profile、配置和依赖。声明经过 engine 产生制品或运行状态，所有判断回到 evidence。

9.3 基础知识讲解

9.3.1 论文 / 规范

9.3.2 书

9.3.3 博客 / 文档

9.3.4 人物

9.3.5 方法

9.4 经典问题与经典案例

9.4.1 实战片段：compose.yaml 与常用命令

# compose.yaml (Compose Specification 3.x)
name: shop
services:
  api:
    image: ghcr.io/acme/api:v1
    build:
      context: .
      dockerfile: Dockerfile
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://app:app@db:5432/shop
      REDIS_URL: redis://cache:6379/0
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:8080/healthz"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 15s
    networks: [backend]
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M

  db:
    image: postgres:18-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: shop
    volumes: [pgdata:/var/lib/postgresql/data]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d shop"]
      interval: 5s
      timeout: 3s
      retries: 10
    networks: [backend]

  cache:
    image: redis:8-alpine
    command: ["redis-server", "--appendonly", "yes"]
    volumes: [redisdata:/data]
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks: [backend]

networks:
  backend:
    driver: bridge

volumes:
  pgdata:
  redisdata:

# 1. 渲染与校验
docker compose -f compose.yaml config > resolved.yaml
docker compose -f compose.yaml --env-file .env up -d

# 2. 看服务状态、健康、网络
docker compose ps
docker compose top
docker inspect "$(docker compose ps -q api)" \
  | jq '.[0].State.Health.Status'

# 3. 拉日志与进入容器
docker compose logs --tail 100 -f api
docker compose exec -u nonroot api sh
docker compose exec db psql -U app -d shop

# 4. 升级回滚与清理
docker compose pull api
docker compose up -d api
docker compose run --rm api migrate-down
docker compose down            # 保留 volume
docker compose down -v         # 删除 volume（先确认）
docker compose ls -a

9.5 学习难点

概念难点

思维难点

工程难点

9.6 技术标准与接口

9.6.1 Entity

9.6.2 Scope

OCI 定义 image 与 runtime 契约，不定义完整编排。containerd 管高层生命周期，runc 执行 OCI bundle。CNI、CSI 面向编排系统；Docker bridge、volume driver 有自己的实现接口。Docker Compose 处理单机或 context 上的多服务应用，不替代 Kubernetes 的集群调度。

9.6.3 Structure

必须掌握 image manifest/config/layer、content digest、OCI bundle、config.json、namespace、cgroup、capability、seccomp、network namespace、mount、snapshotter。常用接口是 Docker CLI/API、Dockerfile、Compose Specification、registry HTTP API。

9.6.4 Ecosystem

Docker Engine 由 daemon、containerd、runc 等组成。替代或邻接实现有 Podman、Buildah、BuildKit、nerdctl、CRI-O、Kubernetes。扩展点包括 BuildKit frontend/cache exporter、network/volume/logging plugin、CNI 与 CSI driver。Compose 文件规范与具体 engine 支持范围要分开核对。

9.6.5 Depth Tiers

本计划目标是 L3。

9.6.6 Source

• Docker 官方文档：CLI、Dockerfile、BuildKit、Compose、rootless 与生产建议。
• Moby 项目仓库：Docker Engine 核心实现，Apache-2.0。
• containerd 仓库：runtime 管理实现，Apache-2.0。
• 引用版本快照日期：2026-07-30；实作前运行 docker version 与 docker compose version。

10. 常见误区

• 只复制命令，不理解对象状态；
• 以 tag 代替 digest；
• 默认 root；
• 把 secret 写进 image 或仓库；
• 用重启掩盖 readiness 和数据问题；
• 只测试正常路径；
• 不记录 Docker/Compose 版本；
• 不区分 Docker 行为、OCI 契约和 Linux kernel 能力；
• 看见报错就重建全部对象；
• 未备份就 remove volume 或 prune。

11. 所有知识点分类（统一规则）

1. 编程语言；2. 数据结构与算法；3. 计算机基础；4. 工程技术；5. Web 与后端；6. 前端与客户端；7. 数据与人工智能；8. 项目与职业能力；9. 安全与可靠性。

本计划归属：工程技术 主 + 安全与可靠性 辅。