Docker Compose只等容器启动？service_healthy健康检查配置教程

应用容器启动时数据库还没准备好，连接报错后不断重启。Compose 的普通依赖顺序只保证依赖服务先启动，不能证明数据库已经接受连接。

把真正可用的检查写进依赖服务的 healthcheck，再让应用依赖 service_healthy。 检查命令必须在被检查的容器内存在，而且应检验业务所需能力。

先确认当前依赖关系

查看有效配置及服务状态：

docker compose config
docker compose ps

短格式 depends_on: [db] 控制创建顺序。它不会等待数据库完成初始化。 如果应用自行重试连接，这一设置可能够用；否则应配置健康检查。

给数据库定义可执行的健康检查

以下以 PostgreSQL 容器为例，检查命令在数据库容器内运行：

services:
  db:
    image: postgres:17
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

Compose 插值会处理美元符号；$$ 让变量传到容器内再展开。pg_isready 只证明服务器接受连接，不保证表结构迁移或应用初始化已经完成。有更严格要求时，应改用可代表该依赖就绪的检查。

让应用等待健康状态

在应用服务中使用长格式依赖：

services:
  web:
    image: example/web:stable
    depends_on:
      db:
        condition: service_healthy

示例镜像名只是配置位置示意，应替换为自己的镜像。Compose 会等待 db 的健康检查通过后创建 web。这不是运行期间的持续故障转移机制；数据库之后变为不健康，应用仍应有连接重试与错误处理。

观察失败原因而非反复重启

docker compose ps
docker inspect --format '{{json .State.Health}}' "$(docker compose ps -q db)"
docker compose logs --tail=100 db web

如果检查连续失败，先核对命令是否安装、变量是否正确、数据库是否仍在初始化、超时是否过短。不要把永远成功的命令写成健康检查，否则会掩盖实际不可用。

区分启动等待与显式重启

长格式 depends_on 的 restart: true 用于 Compose 明确更新或重启依赖服务时一并重启依赖者；它不表示容器运行中数据库每次自行重启都触发应用重启。required: false 会降低依赖缺失时的阻断强度，只适用于可选依赖。

先运行 docker compose config 核对当前 Compose 实现支持的配置，再安排维护窗口更新。不要为了绕过启动失败，把关键数据库改为可选服务。

在隔离环境验证启动顺序

可在 萤光云 或 LightNode 的测试实例复现冷启动，使用脱敏数据核对健康检查和应用重试行为。测试环境应与生产使用相近的 Compose 版本和镜像配置。

验收要看数据库先达到 healthy、应用随后启动且真实请求成功，不能仅凭容器显示 running。

应用配置并验收

docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=80 web

若变更涉及持久化数据库，先确认卷和备份，再执行会重建容器的操作。应用正常处理一次实际数据库请求后，再观察一段时间的日志与健康状态。

FAQ

depends_on 已经写了，为什么仍然连接失败？ 短格式只决定启动顺序，数据库服务可能尚未就绪。

健康检查通过后就不用应用重试了吗？ 仍要保留重试，因为运行期间网络或数据库也可能中断。

温馨提示

健康检查应尽量轻量，避免高频复杂查询增加数据库负担。先验证检查命令的退出码，再把它作为应用启动门槛。