Docker Compose depends_on 怎么用?让服务等数据库就绪的 3 步配置
技术教程 · 云原生 · 容器与镜像 · 2026-11-11
Docker Compose depends_on 怎么用?让服务等数据库就绪的 3 步配置
一句话开头
docker compose up 之后 app 容器一起来就报 connection refused 连不上 Postgres,重启几次又好了——问题基本都在 depends_on 只排了启动顺序,没等数据库真正能连。
前置准备
-
Docker Engine 20.10+ / Docker Compose v2(docker compose version 能看到 v2.x)
-
一个 compose.yaml,里面有应用 + 数据库两个服务
步骤 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
四个参数的作用:
-
test:探针命令。Postgres 镜像自带 pg_isready,它探测的是"能不能接受连接",不是"进程在不在",这正是我们要的
-
interval / timeout:每 10s 探一次,单次最多等 10s
-
retries:连续失败 5 次才判定 unhealthy
-
start_period:启动宽限期,这段时间内的失败不计入 retries。数据库初始化慢的,这个值要给够
注意 $${POSTGRES_USER} 这里是两个美元符。Compose 会先做一次变量插值,$$ 转义成 $ 传进容器,让容器自己展开环境变量。写成单个 $ 的话,Compose 在你本机就把变量替换掉了,探针拿到的可能是空值,然后一直 unhealthy。
步骤 3:depends_on 换成带 condition 的长语法
app:
build: .
depends_on:
db:
condition: service_healthy
restart: true
condition 有三个可选值,别选错:
-
service_started:只等启动,等于原来的短语法
-
service_healthy:等 healthcheck 通过,数据库场景用这个
-
service_completed_successfully:等容器以 0 退出。这个给一次性任务用,比如数据库迁移
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,两者缺一个都不生效。