6.1 Compose多服务编排：一份文件管一队容器

6.1 Compose 多服务编排：一份文件管一队容器

摘要：Compose 用一份声明式 YAML 描述一组容器的镜像、网络、卷、环境与依赖，把十几条 docker run 压缩成一条 docker compose up。本节解剖一份生产可用的编排文件，讲透依赖顺序与健康检查的配合，以及环境分文件的实践。

能力目标

1. 写出含服务、网络、卷、健康检查的完整编排文件
2. 解释 depends_on 带 condition 与裸 depends_on 的关键差别
3. 掌握 compose 的起停、扩缩、日志与重建命令族
4. 用 override 文件分离开发与生产配置

从三条命令的重复地狱说起

没有 Compose 的世界，起一个三层应用要敲三长串命令：网关发布端口接网络、应用跨两个网络传环境变量、数据库挂卷设密码。三条命令、几十个参数，任何一条丢失或写错，应用就瘸。更糟的是这些知识只存在于操作者的终端历史里，换台机器、换个同事，一切从零推理。

Compose 的解法是声明式：把"期望的状态"写成一份机器可读的文件，工具负责把现实推到期望状态。先看一份完整的骨架：

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 10
    networks:
      - back

  app:
    build: .
    environment:
      DATABASE_URL: postgres://postgres:${DB_PASSWORD}@db:5432/app
    depends_on:
      db:
        condition: service_healthy
    networks:
      - front
      - back
    deploy:
      resources:
        limits:
          memory: 512m
          cpus: "1.0"

  gw:
    image: nginx:alpine
    ports:
      - "80:80"
    depends_on:
      - app
    networks:
      - front

volumes:
  pgdata:

networks:
  front:
  back:
​

这份文件浓缩了前面各章的全部知识点，几个要害单独拆：

服务互访用名字。app 连接串里写的是 db 这个主机名。Compose 会为这组服务建一个专属网络（自定义网络，第 4 章的 DNS 在此生效），db、app、gw 互相按名可达。IP 是谁、在哪台机器，全都不用关心。

depends_on 的两档语义。裸的 depends_on: [app] 只保证启动顺序——app 容器先创建，至于应用是否就绪不管；带 condition: service_healthy 的写法会等健康检查真正通过才启动当前服务。数据库这种"进程起来但还要几秒才能接客"的服务，必须用后者，否则应用启动时连库报错的经典剧目准时上演。

资源限制写进文件。deploy.resources 段把第 3 章的 cgroup 参数声明化，limits 是硬顶。这份知识进入文件而不是进入人的脑子，才是编排的意义。

变量外置。${DB_PASSWORD} 从同目录的 .env 文件读取，密码不进版本库。

命令族：声明式的日常

docker compose up -d          # 按文件创建并启动全部服务
docker compose ps             # 查看各服务状态与健康色标
docker compose logs -f app    # 跟踪单个服务日志
docker compose up -d --scale app=3   # 把 app 扩到 3 个实例
docker compose restart app    # 重启单个服务
docker compose up -d --build app     # 改代码后重建镜像并滚动该服务
docker compose down           # 停止并删除容器与网络（卷默认保留）
docker compose down -v        # 连卷一起删 ⚠️ 数据归零
​

两条值得展开。--scale app=3 一次拉起三个 app 实例，配合网关的负载均衡即是单机横向扩容的最小实现；注意扩容的服务不能再占用固定宿主端口与固定容器名，否则端口与名字冲突。up -d --build app 是日常开发的高频动作：改代码、重建镜像、只滚动受影响的服务，其余服务纹丝不动。

⚠️ down -v 是新手数据事故第一名。默认 down 保留卷是安全设计，加 -v 时 Compose 会删掉文件里声明的卷——开发库无所谓，但凡有真实数据的 compose 项目，这条命令要当作危险品对待。

环境分文件：一份基础，多份覆盖

Compose 默认还会自动合并一份 compose.override.yml，利用这个机制做环境分离：

• compose.yml：所有环境共有的服务骨架
• compose.override.yml：本地开发——绑定挂载源码、开调试端口、起本地数据库
• compose.prod.yml：生产——只发内网端口、用镜像 tag 而非 build、挂真实卷

生产部署时显式指定：

docker compose -f compose.yml -f compose.prod.yml up -d
​

两份文件深度合并，覆盖规则是后者赢。这套机制避免了"每个环境复制一份几百行文件、改一处漏三处"的经典维护灾难。

健康检查为什么是编排的地基

再强调一次 healthcheck 的分量。编排系统的一切自愈动作（重启、摘流量、等依赖）都以健康状态为输入；没有健康检查的服务，编排只能看到"进程活着"，看不到"服务已僵死"。健康检查的写法要点：检查命令要在容器内可执行（slim/alpine 镜像常缺 curl，用 wget 或进程自带工具如 pg_isready）；interval 别太密（5 到 10 秒足够）；retries 给足（网络抖动一次就重启是灾难放大器）。

编排文件是给机器读的运维知识库。它进版本库、走评审、随代码一起演进——这份纪律比任何一条命令都值钱。

本节要点回顾

• 声明式模型：写期望状态，工具负责把现实推过去
• 服务按名互访：专属网络加内置 DNS，IP 彻底退场
• depends_on 配 condition 才是真就绪，健康检查是编排自愈的地基
• override 分文件实现一份骨架多环境覆盖
• down -v 与 volume prune 同级危险：删卷即删数据

单机编排到此顶点。机器不够用、要自愈、要滚动发布时，就到下一节的集群世界。