Compose depends_on condition 健康状态怎么配置和用？

在 Docker Compose version 3.8 及以上版本中，通过配置 depends_on 的 condition: service_healthy 并配合 healthcheck（默认 interval 为 30 秒、retries 为 3 次），可确保下游服务等待上游服务真正就绪后再启动，避免仅等待容器运行导致的连接失败。

原因分析

Docker Compose 的 depends_on 指令默认仅控制容器启动顺序，不验证服务可用性。根据 2026 年 1 月 21 日的技术资料，在 Compose 源码中服务启动通过拓扑排序实现，这意味着 web 服务会在 db 容器启动后立即启动，但 PostgreSQL 可能仍在初始化数据目录，此时应用连接将失败。健康检查机制通过周期性探测容器运行状态来解决此问题，命令返回值为 0 表示健康、1 表示不健康、2 表示异常终止，Docker 引擎据此更新容器状态。

解决方案

步骤一：为被依赖服务配置 healthcheck

必须在 docker-compose.yml 中为数据库等关键服务定义健康检查。以 PostgreSQL 15 为例：

services:
  db:
    image: postgres:15
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d myapp"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 40s

根据 2026 年 3 月 28 日的资料，start_period 给数据库预留足够初始化时间，避免健康检查在服务真正监听前就失败多次进入 unhealthy 状态。对于 Spring Boot 应用，可使用 curl 检查 actuator 端点：test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]。

步骤二：在依赖服务中指定 condition

下游服务通过 depends_on 的 condition 字段声明等待条件：

services:
  app:
    image: myapp:latest
    depends_on:
      db:
        condition: service_healthy

根据 2025 年 12 月 17 日的资料，condition 有三种可选值：service_started（容器已运行，默认行为）、service_healthy（健康检查通过）、service_completed_successfully（适用于一次性任务容器）。若被依赖服务未定义 healthcheck，condition: service_healthy 将无意义。

步骤三：可选配合等待脚本

对于复杂场景，可在应用容器启动前插入等待逻辑。根据 2026 年 4 月 5 日的资料，wait-for-it.sh 支持基于 TCP 连通性检查，dockerize 功能更全支持健康 HTTP 检查。示例配置：

services:
  web:
    build: .
    command: ["./wait-for-it.sh", "db:5432", "--", "python", "app.py"]
    depends_on:
      db:
        condition: service_healthy

注意事项

根据 2026 年 3 月 25 日和 2026 年 4 月 5 日的资料，实际配置中容易忽略以下细节导致等待失效：

• start_period 设置过短：数据库首次启动可能需数十秒初始化，建议设置为 40s-60s，否则健康检查在服务真正监听前就失败多次，进入 unhealthy 状态
• 健康检查路径/端口未开放：确保容器内服务监听 0.0.0.0 而非 127.0.0.1，PostgreSQL 需确认 pg_hba.conf 允许本地 pg_isready 连接
• 容器内缺少检测工具：Docker 默认以 root 运行 healthcheck 命令，若容器内无 curl 或 nc，需提前安装或改用 shell 内置方式如 sh -c 'echo > /dev/tcp/127.0.0.1/8080' 2>/dev/null
• condition 仅作用于启动阶段：不保证运行时服务持续健康，运行时故障需应用自行处理，若健康检查失败超过 retries 次，容器会进入 unhealthy 状态，Compose 将阻塞后续容器启动并报错

参考来源

来源：Docker 官方文档 - Docker Compose healthcheck 和 depends_on condition 配置说明

来源：GitHub Issue - Docker Compose 依赖管理终极指南（2025 年 11 月 29 日）

来源：技术博客 - Docker Compose 健康检查配置最佳实践（2025 年 12 月 16 日）

来源：微服务部署指南 - depends_on 与健康检查协同机制（2025 年 12 月 17 日）

原文链接：https://www.zjcp.cc/ask/9849.html