Docker Compose depends_on 怎么用?让服务等数据库就绪的 3 步配置

技术教程 · 云原生 · 容器与镜像 · 2026-11-11

Docker Compose depends_on 怎么用?让服务等数据库就绪的 3 步配置

一句话开头

docker compose up 之后 app 容器一起来就报 connection refused 连不上 Postgres,重启几次又好了——问题基本都在 depends_on 只排了启动顺序,没等数据库真正能连。

前置准备

步骤 1:先搞清 depends_on 短语法到底做了什么

大部分人的 compose 文件长这样:

services:
  app:
    build: .
    depends_on:
      - db
  db:
    image: postgres:18

这段配置的语义只有一句:db 容器比 app 容器先创建。它不代表 Postgres 已经能接受连接。

官方文档写得很直白:启动时 Compose 不等容器 "ready",只等它 "running"。而 Postgres 容器处于 running 状态时,初始化数据库、replay WAL 这些事可能还要跑十几秒。这段窗口里你的 app 连上去就是 connection refused 或者 database system is starting up。

所以 depends_on 不是没用,是它承诺的东西和你想的不一样。

步骤 2:给数据库加 healthcheck

要等"就绪",得先定义什么叫"就绪"。这一步加在被依赖的服务上,不是加在 app 上:

  db:
    image: postgres:18
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: example
      POSTGRES_DB: app
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 10s
      retries: 5
      start_period: 30s

四个参数的作用:

注意 $${POSTGRES_USER} 这里是两个美元符。Compose 会先做一次变量插值,$$ 转义成 $ 传进容器,让容器自己展开环境变量。写成单个 $ 的话,Compose 在你本机就把变量替换掉了,探针拿到的可能是空值,然后一直 unhealthy。

步骤 3:depends_on 换成带 condition 的长语法

  app:
    build: .
    depends_on:
      db:
        condition: service_healthy
        restart: true

condition 有三个可选值,别选错:

restart: true 是另一件事:当你显式 docker compose restart db 或更新 db 时,app 会被一起重启,省得它握着一个已经断掉的连接。它管不到"容器运行时自己崩溃重启"这种情况——那种还得靠应用自身的重试。

步骤 4:验证真的等到了

docker compose config --quiet          # 先确认 YAML 和插值没问题
docker compose up -d
docker compose ps                      # db 的 STATUS 应该显示 (healthy)

想知道探针到底在干什么:

docker compose ps --all -q db
docker inspect --format '{{json .State.Health}}' <container-id> | jq

输出里 Status 是 starting / healthy / unhealthy,Log 里是每次探针的执行结果和退出码,比猜快得多。

一次性起全栈并等所有服务就绪(CI 里很好用):

docker compose up -d --wait

--wait 会等到所有服务 running 或 healthy 才返回,起不来就直接非零退出。

常见坑

探针命令在镜像里不存在。 拿 curl 探 HTTP 服务,结果镜像基于 distroless 或 slim,压根没装 curl。探针永远失败,容器永远 unhealthy,然后 service_healthy 的 app 永远不启动——你看到的现象是"app 根本没起来",很容易误判成 Compose 配置问题。选探针前先 docker compose run --rm db which pg_isready 确认一下。

start_period 给短了。 有些数据库首次启动要建库、跑 initdb,30s 不够。表现是第一次 up 起不来,第二次因为数据目录已经初始化好了反而成功——这种"时好时坏"基本都是 start_period 的问题。

探针用 localhost 但应用走 service name。 healthcheck 在容器内部执行,localhost 指的是容器自己;而你的应用连的是 db:5432。两者在端口映射、监听地址(0.0.0.0 vs 127.0.0.1)上可能不一致,探针通过但应用连不上。作者补充:这个坑在自建镜像里特别常见,服务默认监听 127.0.0.1,Compose 网络里其他容器根本连不到,健康检查却一直绿的。

把 healthcheck 加错服务。 condition: service_healthy 读的是被依赖服务的健康状态。加在 app 上的 healthcheck 对 depends_on 的判断毫无影响,而且 db 没有 healthcheck 时 Compose 会直接拒绝启动。

一句话总结

depends_on 短语法只管启动顺序,要等"能用"就得在依赖服务上写 healthcheck、在依赖方写 condition: service_healthy,两者缺一个都不生效。