Docker Compose healthcheck 如何控制依赖服务启动顺序

如果 web 一启动就连接数据库，最容易踩的坑是：容器已经处于 Running，并不代表数据库已经能接受连接。Docker Compose 的短语法 depends_on: [db] 只表达“先启动 db”；要等待真正可用，必须给 db 写 healthcheck，再让 web 使用长语法 condition: service_healthy。

第一步：准备 Compose 文件并打开依赖设置

在项目目录中打开 compose.yaml，先确认服务名。本文用一个数据库服务 db 和一个应用服务 web 演示。Docker Desktop 的入口路径是“Containers → compose-demo → Files/编辑配置”；如果使用编辑器，则直接打开项目根目录的 compose.yaml。先不要把 web 的启动命令写成固定等待几十秒，固定延时无法判断数据库是否真的就绪。

本步骤的屏幕确认点是：左侧项目树能看到 compose.yaml，服务区同时出现 db 与 web，右侧依赖设置入口指向 web → depends_on。下一步只改 db 的健康检查。

第二步：给数据库配置 healthcheck

在编辑路径“compose.yaml → services → db”下加入探针。以 PostgreSQL 为例，pg_isready 只要能连接到目标数据库就返回成功；环境变量要写成 $${...}，这样变量会留给容器内的命令，而不是被 Compose 在解析文件时提前替换。

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: change-me
      POSTGRES_DB: appdb
    healthcheck:
      # 用数据库原生探针判断“可以接收连接”，不要只看容器是否运行
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      # 启动初期给数据库预留初始化时间，随后按间隔重试
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 20s

按“db → healthcheck → test”逐项填写后，确认编辑器没有 YAML 缩进错误。屏幕状态应能看到 test、interval、timeout、retries 四个字段；它们是健康判断的输入，不是启动顺序本身。

第三步：在 web 服务绑定 service_healthy

回到“compose.yaml → services → web → depends_on”，把短语法改为长语法，并明确依赖条件：

  web:
    build: .
    depends_on:
      db:
        # web 只有在 db 的 healthcheck 通过后才启动
        condition: service_healthy
    environment:
      DATABASE_URL: postgres://app:change-me@db:5432/appdb

保存后，屏幕确认点是 web → depends_on → db → condition 显示 service_healthy。这里不要把 service_started 当成健康检查：它等价于短语法，只代表依赖容器已经启动。

第四步：用 Compose 状态面板验收启动顺序

在 Docker Desktop 中按“Containers → compose-demo → Start/启动”，或在项目目录执行 docker compose up -d。先观察 db 的状态从 Starting 变成 Healthy，再观察 web 进入 Running。若 db 一直 Unhealthy，点击“db → health details → logs”查看探针输出，不要先放宽 retries。

验收可以按这张清单走：

相关问题

healthcheck 通过了，web 还是连接失败怎么办？

先确认探针检查的是应用实际使用的数据库、用户和端口；Healthy 只说明探针命令成功，不代表业务迁移或连接池配置完成。

为什么只写 depends_on 不够？

短语法只保证依赖服务先被启动，Compose 不会等待它进入可用状态，因此数据库初始化较慢时仍可能发生启动竞态。

可以用 sleep 代替 healthcheck 吗？

不建议。sleep 只等待时间，不读取服务状态；健康探针更容易解释、重试和排查，应用本身仍应保留连接重试。