开发工具 Compose 等待依赖健康 怎样处理

Compose 要等待依赖真正通过健康检查，需要同时配置两处：依赖服务定义 healthcheck，使用它的服务在 depends_on 长写法里指定 condition: service_healthy。只写服务名列表，只能表达启动依赖，不能替代就绪检查。不要用固定 sleep 秒数掩盖初始化时间差异。

健康状态是探针的结论，不是整套业务的可用承诺。启动时等到 healthy，也不能替代应用运行期间的断线重连与重试。

Docker 官方文档入口：https://docs.docker.com/compose/how-tos/startup-order/。下面使用桌面编辑器和 Docker Desktop 演示操作位置，命令供读者在自己的练习环境执行；图片均为原创说明图，输出与状态只描述预期，不代表本机运行记录。

1. 打开项目配置并确认依赖服务

在编辑器选择 File → Open Folder，打开独立练习目录 compose-health-lab，再在资源管理器点击 New File，创建 compose.yaml。已有项目先保存配置副本，不直接替换整份生产文件。

本例只有 cache 与 worker 两个服务：cache 是待就绪的 Redis；worker 是睡眠占位进程，便于观察依赖门槛，不会连接缓存或处理业务。这样可以把“是否放行启动”和“应用连接是否成功”分开判断。练习配置不映射宿主端口，也不配置业务数据卷，不应作为生产部署模板。

继续前，确认编辑器标签是 compose.yaml，且目录属于练习项目。再打开 Docker Desktop → Containers，注意当前已有项目，后续只操作 compose-health-lab，不使用批量停止或删除。

2. 设置健康检查与等待条件

在 compose.yaml 的 services.cache.healthcheck 填入探针，在 services.worker.depends_on.cache.condition 填入 service_healthy。下面是一份独立练习配置，保存前保留 YAML 缩进，不用 Tab 混排：

name: compose-health-lab
services:
  cache:
    image: redis:7-alpine
    healthcheck:
      # 在cache容器内执行，镜像需要提供redis-cli。
      test: ["CMD", "redis-cli", "ping"]
      interval: 4s
      timeout: 2s
      retries: 8
      start_period: 12s

  worker:
    image: busybox:1.37
    # 只作为启动观察对象，不是实际业务工作进程。
    command: ["sleep", "3600"]
    depends_on:
      cache:
        # 引用Compose服务名，不引用容器自动生成的名称。
        condition: service_healthy

test 用 CMD 数组直接执行程序，不需要 Shell 拼接。这个无认证练习实例只检查本容器的 Redis 是否能应答，不代表跨容器网络、生产认证或业务数据准备完成。镜像标签用于演示，不表示最新版本、安全评估结果或生产选型建议。

interval 控制检查间隔，timeout 限制单次检查耗时，retries 指定连续失败阈值。start_period 是启动宽限期，不是强制等待时长：服务提前通过检查可以变成 healthy。不要简单把这些数字相乘，当作所有环境一致的启动倒计时。

保存后，文件标签不应再显示未保存标记。两项配置要一起存在：只加 healthcheck 不会让其他服务自动等待；只加 service_healthy 却没有可用健康检查，也不能得到有效的健康门槛。

3. 重新应用配置并查看健康状态

在编辑器进入 Terminal → New Terminal，确认终端工作目录是 compose-health-lab。先查看 Compose 插件版本，再启动这一个练习项目；不要在未知目录照抄命令。若本机插件不识别参数，先对照官方命令帮助处理兼容性。

# 确认使用docker compose插件，而非把旧命令混用进来。
docker compose version
# 应用当前目录配置并等待项目达到running或healthy。
docker compose up --wait --wait-timeout 90
# 查看这一个项目的服务与健康状态。
docker compose ps

up --wait 会采用后台运行模式；没有健康检查的服务以运行状态作为等待目标。因此本例 worker 运行并不证明它与 cache 连通。--wait-timeout 90 是这次命令等待上限，不会自动改变 healthcheck 的判定规则，超时后也不要假定所有已启动资源已自动清理。

回到 Docker Desktop → Containers，在 Search 输入 compose-health-lab，展开项目，点击 cache 容器 → Inspect，查看 State 下的 Health.Status 及检查记录；如需了解服务初始化错误，切换同一容器的 Logs。界面呈现可能随版本变化，字段语义比颜色或图标更可靠。

预期检查点是 cache 为 healthy，worker 已运行。若 cache 长时间 starting，先看检查是否真正执行；若 unhealthy，查看最近一次检查输出与退出码，区分“探针程序不存在”“探针参数错误”和“服务确实没就绪”。不要通过删除健康条件让启动表面成功。

修改 compose.yaml 后需要重新应用配置；只点容器 Restart 不等于重新读取 Compose 文件。对练习项目重新运行 up，并确认没有使用跳过依赖的 --no-deps 或禁止重建的 --no-recreate 来混淆结果。生产项目的重建需另行安排变更窗口。

后来变成 unhealthy，worker 会自动停止吗？

不要把 depends_on 当作运行期联锁或故障编排器。依赖后来失效，应用仍需自己的超时、有限重试与重连策略。depends_on 内的 restart 语义也不能和容器级 restart 策略混为一谈；显式 Compose 操作与运行时故障是不同事件。

为什么增加 start_period 没有改善问题？

如果探针依赖镜像中根本不存在的工具，或检查了错误端口，延长时间只会更晚暴露错误。先修正检查对象，再根据实际初始化特征调整宽限期。数据库能接连接也不等于迁移已完成；需要一次性初始化任务时，应另行设计成功完成条件。

练习结束如何回退？

只在上述独立目录执行以下命令停止并移除练习容器与项目网络；不加 -v，不批量清理 Docker 资源。Redis 镜像可能声明匿名卷，本例不依赖其中任何数据，但保留卷仍应在 Docker Desktop 的 Volumes 视图确认归属后单独处理。

# 仅清理当前练习项目的容器和网络，不请求删除数据卷。
docker compose down

已有项目回退时恢复自己的配置差异，不删除整份 compose.yaml，更不要靠清空数据卷解决健康检查失败。配置层的结论只有三条：探针检查什么，依赖何时允许启动，运行期故障由谁处理。

参考：Compose 启动依赖规则、healthcheck 与服务配置、up 等待参数、Docker Desktop 容器详情入口。