Docker healthcheck 怎样让依赖服务等待就绪

Docker 容器显示 running，不代表里面的数据库、HTTP 服务已经能接收请求。要让依赖服务真正等待就绪，需要把两件事接起来：依赖容器用 healthcheck 报告健康状态，Compose 再用 depends_on.condition: service_healthy 决定应用服务何时创建。只写 healthcheck，Web 服务仍可能过早启动。

官方地址：https://docs.docker.com/reference/dockerfile/#healthcheck

Compose 启动顺序说明：https://docs.docker.com/compose/how-tos/startup-order/

最小可靠配置是：数据库探针检查“能否接受真实连接”，Web 服务在 service_healthy 后再启动；同时保留应用自身的连接重试，因为健康检查只解决编排时序，不替应用处理运行期间的重启和网络抖动。

先区分容器运行与服务就绪

HEALTHCHECK 会给容器增加健康状态：初始是 starting，探针返回成功后是 healthy，连续失败达到 retries 后是 unhealthy。它回答的是“这个容器当前是否通过检查”，并不会自动改变另一个服务的启动顺序。

为依赖服务写 healthcheck

以 PostgreSQL 为例，pg_isready 比单纯检查端口更有意义：它会按用户和数据库参数判断 PostgreSQL 是否已经可以接受连接。下面的示例把检查范围限定在 db 服务，并给数据库留出初始化时间。

services:
  db:
    image: postgres:18
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: change-me
      POSTGRES_DB: appdb
    healthcheck:
      # 用数据库探针判断“可连接”，不要只探测 TCP 端口
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      # 初始化期间先快速探测，正常运行后按 interval 检查
      start_period: 30s
      interval: 10s
      timeout: 5s
      # 连续失败 5 次才标记为 unhealthy
      retries: 5

几个参数要一起看：start_period 给首次初始化留窗口，窗口内的失败不会直接计入重试上限；interval 是两次检查之间的间隔；timeout 限制一次探针最长执行时间；retries 决定连续失败多少次才进入 unhealthy。Docker 文档还列出了 start_interval，它用于启动阶段的检查频率，并要求 Docker Engine 25.0 或更高版本。

让应用服务等待 healthy

真正控制等待的是 Web 服务的 depends_on。把数据库列为依赖，并把条件写成 service_healthy，Compose 才会等 db 的健康检查通过后再创建 web。

services:
  web:
    build: .
    depends_on:
      db:
        # 只有 db 进入 healthy，web 才继续创建
        condition: service_healthy
    environment:
      DATABASE_URL: postgres://app:change-me@db:5432/appdb

  db:
    image: postgres:18
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: change-me
      POSTGRES_DB: appdb
    healthcheck:
      # $${...} 让 Compose 把变量交给容器内的 shell 展开
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

这里的顺序是“创建 db → 运行探针 → db healthy → 创建 web”。如果依赖是一次性迁移任务，可以考虑 service_completed_successfully；如果只需要容器先被创建，则是 service_started。不要把这三种条件混用成“都表示可用”。

用状态和日志判断为什么没有就绪

配置完成后，先用 Compose 展开配置，确认健康检查和依赖条件没有被环境变量覆盖：

# 展开最终 Compose 配置，便于确认 healthcheck 和 depends_on 是否存在
docker compose config

# 查看服务状态；重点观察 db 的 healthy/unhealthy
docker compose ps

# 读取数据库容器的健康检查输出，定位探针失败原因
docker inspect --format='{{json .State.Health}}' project-db-1

如果一直是 starting，通常是数据库初始化时间超过了 start_period，或探针命令没有安装在镜像里。如果变成 unhealthy，先检查用户名、数据库名、容器内 DNS 名称和探针退出码。Docker 记录的健康检查输出应保持简短；探针成功只表示当前检查通过，不表示应用之后永远不会断开。

还有一个常见边界：Compose 只在依赖服务的创建阶段按条件等待。数据库后续重启、网络中断或连接池失效时，Web 应用仍需要自己的超时、重试和优雅降级策略。

常见问题

只写 HEALTHCHECK，为什么 Web 还是先启动？

因为 healthcheck 只报告状态，必须在 Web 的 depends_on 下写 condition: service_healthy，Compose 才会把该状态用于启动条件。

探针检查端口是不是就够了？

不一定。端口能连接只说明进程监听了端口；更可靠的探针应执行轻量的协议或数据库就绪检查，例如 PostgreSQL 的 pg_isready。探针要快速、无副作用，并且能在镜像内实际执行。

小结：让依赖服务等待就绪的关键不是把重试次数调大，而是把“可执行的 healthcheck”与 service_healthy 连接起来。先确认探针能代表真实就绪，再按初始化耗时设置 start_period，最后保留应用运行期间的连接重试。