Docker Compose 怎样让服务等待健康检查

Docker Compose 要让后启动的服务等待依赖就绪，需要把两个配置配合使用：依赖服务定义 healthcheck，使用它的服务在长语法 depends_on 中设置 condition: service_healthy。只有依赖名、没有健康条件，解决的是启动顺序，不是可用性。

例如一个客户端启动后立即访问 Redis，Redis 容器虽然已经运行，却可能还没准备好处理请求。下面用 cache 和一次性 client 两个服务演示这个区别。目标是先看到 cache 健康，再看到 client 完成 PING，而不是给启动过程加一个固定 sleep。

官方地址：https://docs.docker.com/compose/how-tos/startup-order/

使用当前支持长语法依赖条件的 docker compose。示例只用于全新、隔离的本地演示目录，不要覆盖现有 compose.yaml 或在生产项目直接操作。Docker Engine 需要可用，镜像拉取需要网络。文中的状态是预期结果，配图是原创说明图，没有在本机运行容器。

1. 给 cache 设置真正可执行的健康检查

在新建演示目录的编辑器中创建 compose.yaml，先填写 cache 部分。保存文件后，确认 healthcheck 缩进在 cache 内，而不是与 services 并列。

services:
  cache:
    image: redis:7-alpine
    healthcheck:
      # 在 cache 容器内执行，并要求输出完整的 PONG 行
      test: ["CMD-SHELL", "redis-cli ping | grep -q '^PONG$'"]
      interval: 3s
      timeout: 2s
      retries: 5
      # 留出初始化宽限期；成功的检查仍可提前标记健康
      start_period: 5s

这里的探测工具来自 Redis Alpine 镜像环境，不是宿主机上的 redis-cli。用 CMD-SHELL 是因为检测包含管道；grep 找不到 PONG 时返回非零，使失败能够体现到健康检查中。对于自制精简镜像，必须先保证镜像内存在所用命令，不能把宿主机装有工具当成容器内也有。

interval 是检查间隔，timeout 限制单次检查耗时，retries 控制连续失败达到不健康状态的门槛。start_period 不是强制睡眠：宽限期内失败不计入正常失败门槛，但检查成功后可以进入健康状态。不要把几个数相乘当成精确的启动总耗时。

本例只检测 Redis 能否响应 PING，不检测业务键是否存在，也不证明客户端权限、数据加载或完整业务流程已经满足要求。实际应用应让探测标准与“允许启动下游”的条件一致。

2. 在 client 中声明等待 service_healthy

继续在同一份文件的 services 下添加 client，令它通过服务名 cache 访问 Redis。下面是最终完整文件，直接保留一份，不要把两个 services 顶层重复粘贴进去。

services:
  cache:
    image: redis:7-alpine
    healthcheck:
      # PONG 才表示本示例的 Redis 探测通过
      test: ["CMD-SHELL", "redis-cli ping | grep -q '^PONG$'"]
      interval: 3s
      timeout: 2s
      retries: 5
      start_period: 5s

  client:
    image: redis:7-alpine
    # 一次性访问依赖；完成后退出，不是常驻应用
    command: ["redis-cli", "-h", "cache", "ping"]
    depends_on:
      cache:
        # 等待依赖健康，而不仅是容器已启动
        condition: service_healthy

保存后，逐项确认：依赖键写的是服务名 cache；condition 位于 client 的 depends_on.cache 下；cache 自己有可执行的 healthcheck。这个示例使用默认项目网络，不需要额外 links，也没有映射宿主机端口；client 内的 localhost 指向 client 自身，因此不能拿 localhost 代替 cache。

只添加 healthcheck 而保留 depends_on 的短列表，仍没有把“等待健康”设为 client 的启动条件。反过来，只填写 service_healthy 而没有有效健康检查，也不能凭空产生就绪判定。

3. 启动项目并分开核对健康状态和业务结果

在演示目录的终端执行以下命令。显式指定项目名与文件，减少把命令作用到其他 Compose 项目的风险；这里只给读者操作方法，没有代替读者启动服务。

# 在保存 compose.yaml 的演示目录启动两个服务
docker compose -p compose-health-demo -f compose.yaml up -d

# 包含已退出容器，才能看到一次性 client 的状态
docker compose -p compose-health-demo -f compose.yaml ps --all

# 查看 client 的返回内容；去掉日志前缀便于阅读
docker compose -p compose-health-demo -f compose.yaml logs --no-log-prefix client

在正常环境里，启动过程会等待 cache 的健康检查通过，随后启动 client。服务就绪速度不同，等待状态可能很短；没有肉眼看到长时间停留，不代表健康条件没生效。验收要分开看三件事：

• cache 的状态含 healthy：代表配置的容器内探测通过。
• client 为 Exited (0)：这里是一次性命令正常完成，不是异常停机。
• client 日志包含 PONG：说明它通过项目网络访问了 cache，并获得本例期望的响应。

实际输出的容器名、时间、排版可能不同。默认 ps 只列运行中的容器，因此不要因为没有 client 行就认定没启动；用 --all 才能把已经完成的客户端纳入判断。

没有通过时，先区分哪一层失败

cache 仍在 starting，先看它是否还在初始化。cache 已 unhealthy，关注探测命令、退出码以及依赖服务自身日志，而不是盲目加长等待时间。工具缺失或目标地址写错不会因为重试次数增加而被修复。

cache 已 healthy，但 client 未返回 PONG，说明容器内本地探测和下游真实访问不是同一件事。需要查看 client 日志里的地址、网络或认证错误；换成有鉴权的真实服务时，不能照搬这个无认证演示。若修改了 compose.yaml，后续应重新执行 up 让配置被应用，不能只重启旧容器就假定配置已替换。

启动门槛不是持续故障恢复

service_healthy 管的是依赖启动条件，并不承诺 cache 以后变得 unhealthy 时自动停止、重启或修复所有下游应用。常驻业务仍需要连接重试、超时和断线处理。depends_on 的 restart: true 针对 Compose 显式操作触发的依赖更新或重启，不等于容器运行时自动重启的联动保证；本例没有添加它。

记录什么，才方便复现

保存最终 compose.yaml、使用的 Compose 版本和镜像标签，以及 cache 健康状态、client 退出码、客户端日志。这个演示没有发布端口，但也没有认证配置，不能直接当作生产 Redis 部署方案。镜像标签可能更新；需要严格复现时应由自己的环境固定镜像摘要。

整个设置的核心是把就绪标准放在依赖里，把等待条件放在使用方里，再分别核对探测与真实访问结果。它比固定 sleep 更贴近依赖是否可用，但不会替业务定义什么叫“准备好了”。

官方配置参考：https://docs.docker.com/reference/compose-file/services/。健康检查参数：https://docs.docker.com/reference/dockerfile/。状态查询参考：https://docs.docker.com/reference/cli/docker/compose/ps/。PING 语义：https://redis.io/docs/latest/commands/ping/。