Docker Compose 健康检查实战：用 service_healthy 消除启动竞态

容器进程处于 running 状态，并不代表应用已经准备好接收请求。在微服务或依赖数据库、缓存的应用中，经常遇到 Web 服务启动过快，而 Redis 或 PostgreSQL 仍在初始化的情况。此时直接发起连接会导致报错或重试风暴。

Docker Compose 默认的 depends_on 仅等待依赖容器进入 running 状态，无法感知应用内部的就绪信号。要解决这一启动竞态，需要引入健康检查机制，并利用 service_healthy 条件控制启动顺序。

本实战基于 Compose Specification，展示如何为 Redis 配置健康探针，并让 Web 服务仅在 Redis 健康后才启动。这种机制将容器生命周期管理与业务可用性解耦，提供更可靠的本地开发与测试环境。

容器 running 了，为什么应用还是连不上 Redis

在传统的 Compose 文件中，depends_on 常被用来声明服务依赖。然而，根据官方文档说明，默认行为下 Compose 只等待依赖容器启动（running），并不等待其内部应用就绪 Control startup and shutdown order in Compose。

这意味着，当 Redis 容器进程启动时，Compose 即认为依赖满足，随即启动 Web 容器。但此时 Redis 可能仍在加载数据或绑定端口，Web 服务的初次连接请求必然失败。区分“容器进程存在”与“业务服务可用”是解决此类问题的关键。

图：web 依赖 redis 的健康状态，探针通过后才继续启动。

通过设置 depends_on 的条件为 service_healthy，Compose 会持续检查依赖服务的健康状态，直到探针返回成功才启动当前服务 Control startup and shutdown order in Compose。这构成了一个从基础设施就绪到应用启动的闭环。

healthcheck 到底检查什么

健康检查的核心是 healthcheck 指令，它与 Dockerfile 中的 HEALTHCHECK 使用相同机制，并允许在 Compose 文件中覆盖镜像默认设置 Compose Specification healthcheck。

探针由 test 字段定义，支持 CMD 或 CMD-SHELL 形式。命令在容器内部执行，退出码 0 表示健康，1 表示不健康 Compose Specification healthcheck。因此，探针依赖的可执行文件必须存在于目标镜像中 Compose Specification healthcheck。

时间参数决定了探针的执行频率与判定逻辑：

• interval：两次探针之间的间隔。
• timeout：单次探针执行的超时时间。
• retries：连续失败多少次后标记为 unhealthy。
• start_period：启动宽限期。在此期间内的失败不计入 retries，适用于长启动时间的服务。
• start_interval：启动期内的探针频率。注意，该参数仅在 Docker Engine 25.0 及以上版本支持 Dockerfile reference: HEALTHCHECK。

图：启动期探针与连续失败次数共同决定容器的健康状态。

合理配置 start_period 可以避免因应用启动慢而被误判为 unhealthy。若未设置宽限期，探针将从容器启动即刻开始计数失败次数。

写一份能被 Compose 解析的最小配置

以下是一个基于 redis:7-alpine 的最小化配置示例。Redis 使用 redis-cli ping 作为探针，Web 服务依赖 Redis 的健康状态。

services:
  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 10s

  web:
    image: nginx:alpine
    depends_on:
      redis:
        condition: service_healthy

在该配置中，test 使用 JSON 数组形式（CMD），避免了 shell 解析的开销与差异。interval: 5s 与 timeout: 3s 确保了探针不会过于频繁地占用资源，同时能较快检测到故障。

在启动容器前，建议先使用 docker compose config 验证配置的正确性。当前环境使用 Docker Compose v5.1.3 进行验证：

docker compose -f compose.yaml config --quiet
docker compose -f compose.yaml config

执行结果显示配置解析成功，且 condition: service_healthy 被正确保留。此步骤仅验证 YAML 结构与字段合法性，并未实际启动容器或验证 Redis 的真实健康状态。

unhealthy 时先查探针，不要先改 retries

当服务状态显示为 unhealthy 时，盲目增加 retries 或延长 interval 往往掩盖了根本问题。正确的排查路径应从探针执行结果入手。

首先，使用 docker compose ps 查看服务状态。若状态为 unhealthy，可通过 docker inspect 获取详细的健康日志，其中包含最后一次探针执行的退出码与输出信息。

其次，进入容器内部手动执行探针命令。例如对于 Redis，执行 docker exec -it redis-cli ping。若命令不存在或连接拒绝，说明探针依赖的环境未就绪，或端口配置有误。

最后，检查 start_period 是否过短。如果应用启动耗时超过宽限期，探针会在应用就绪前就开始计数失败，导致容器被错误标记为 unhealthy。确保探针检查的是业务真正依赖的最小信号，而非仅仅进程存在。

这套方案的边界与下一步

service_healthy 解决了启动顺序问题，但并非万能。depends_on 还支持 service_started 和 service_completed_successfully 条件，分别适用于仅需容器启动和需等待一次性任务完成的场景 Control startup and shutdown order in Compose。

健康检查应聚焦于基础设施的就绪状态，如数据库连接、端口监听等。对于复杂的业务初始化、数据迁移或跨服务的一致性校验，仍需在应用层实现重试机制或就绪探针。

此外，健康检查无法替代服务发现与熔断机制。在生产环境中，应结合 Kubernetes 或 Service Mesh 的能力，处理动态扩缩容与网络故障。在本地开发中，合理配置 healthcheck 足以消除绝大多数启动竞态带来的调试困扰。

下一步，建议在真实服务镜像中验证探针命令的可用性，并根据实际启动耗时调整 start_period，确保健康检查既灵敏又稳健。