Docker Compose 怎么让服务只在依赖健康后启动

如果应用容器一启动就连接数据库，最容易遇到的不是网络配置错误，而是数据库进程已经启动、却还没有准备好接受连接。Docker Compose 的 depends_on 短语法只负责先启动依赖容器，并不会等待它进入可用状态。要让服务只在依赖健康后启动，需要同时配置依赖服务的 healthcheck，再在应用服务中使用长语法的 condition: service_healthy。

最小可靠配置就是：依赖服务提供真实可执行的健康检查，应用服务把依赖条件设为 service_healthy，启动后再查看依赖状态是否真的变为 healthy。

一、先分清“容器已启动”和“服务已就绪”

假设项目有 web 和 db 两个服务。下面这种写法能让 Compose 先创建 db，但不能证明数据库已经可以处理查询：

services:
  web:
    image: example-web:local
    depends_on:
      - db # 只声明启动顺序，不等待健康状态
  db:
    image: postgres:16

因此，应用可能在数据库初始化期间先启动，第一次连接收到拒绝或认证前置错误。这里要改的是 Compose 的依赖条件，而不是简单把 sleep 10 塞进启动命令；固定等待时间无法覆盖首次初始化、磁盘慢或恢复时间变化的场景。

二、为依赖服务添加可执行的 healthcheck

第 1 步，在项目的 compose.yaml 中找到 db 服务；第 2 步，在它下面加入能真正检查数据库连接的命令。以 PostgreSQL 为例，可以使用镜像提供的 pg_isready：

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: devpass
      POSTGRES_DB: appdb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"] # 检查数据库是否接受连接
      interval: 5s       # 两次探测之间等待 5 秒
      timeout: 3s        # 单次探测最多等待 3 秒
      retries: 5          # 连续失败 5 次才判定 unhealthy
      start_period: 10s   # 给首次初始化留出缓冲时间

这里的命令必须和镜像实际提供的客户端一致。换成 Redis 时，应改成类似 redis-cli ping 的检查；不要把 true 或只检查进程存在的命令当作业务就绪信号。保存后，第 3 步可执行 docker compose config，先确认 YAML 缩进、变量转义和字段展开没有问题。

三、用 service_healthy 绑定 web 的启动条件

在 web 服务中把短语法改成长语法。第 4 步，找到 web.depends_on；第 5 步，把 db 写成对象，并明确指定 service_healthy：

services:
  web:
    image: example-web:local
    depends_on:
      db:
        condition: service_healthy # db 通过 healthcheck 后才满足依赖
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]

第 6 步，在项目目录运行：

# 展开 Compose 配置，先排除缩进和字段拼写问题
docker compose config

# 重新创建项目，观察依赖状态变化
docker compose up -d

如果只写 condition: service_started，行为就回到了“容器启动即可继续”；如果 db 的健康检查始终失败，Compose 不应把它当作已满足 service_healthy 的依赖。这个条件适合解决启动时机，不会替应用修复错误的用户名、密码、端口或网络。

四、启动并确认依赖健康后才创建应用

启动后，第 7 步查看服务状态：

# 查看容器状态，重点关注 db 后面的 health 标记
docker compose ps

# 查看 db 最近的健康检查输出
docker inspect --format='{{json .State.Health}}' "$(docker compose ps -q db)"

正常结果是 db 显示 healthy，随后 web 进入运行状态。若 db 是 unhealthy，先看健康检查的最后一次输出，再检查用户、数据库名、端口和初始化时间。不要只看 docker ps 中的 Up；容器处于 Up 只说明主进程还在，不等于应用端口已经可用。

常见问题

为什么加了 depends_on 还是偶尔连接失败？

先确认是不是仍使用短语法，或者 healthcheck 只检测进程而没有检测真实连接。还要注意 Compose 条件只覆盖编排启动阶段；网络抖动、数据库重启和应用运行期间的连接断开，仍需由应用连接池和重试策略处理。

healthcheck 的 retries 越大越好吗？

不是。应按服务的正常初始化时间设置 start_period、interval 和 timeout，让失败尽快暴露但避免把正常冷启动误判为故障。改完后用 docker compose ps 和健康检查输出复核。

最后可以按这条路径复查：healthcheck.test 能否真实连接依赖服务，web.depends_on.db.condition 是否为 service_healthy，启动时 db 是否先出现 healthy。三项都成立，Compose 才会把“依赖健康后启动”落实为可观察的状态，而不是固定延时的猜测。