一份 docker-compose 摆在那里,MySQL 的日志写着 ready for connections,应用起来还是报连不上。这种时候第一反应是觉得依赖没起来,然后去翻 depends_on,看见配了,就不知道往哪查了。
热榜上那篇文章把这四种原因列得很清楚。我按 Agent 服务栈的场景过一遍。
一、depends_on 配了不等于生效
默认的 depends_on 只等容器进入运行状态,也就是 service_started。它不检查 healthcheck 的结果。
所以 MySQL 启动完成和 MySQL 能接受连接是两件事。前者只要主进程拉起来就算,后者要等初始化脚本跑完、端口监听上、用户建好。
要让 healthcheck 真的挡住下游启动,必须显式写条件。
yaml
depends_on:
mysql:
condition: service_healthy
condition 有三个可选值。service_started 是默认,只看主进程起来。service_healthy 要等依赖容器的 healthcheck 返回 0。service_completed_successfully 要等它正常退出,适合一次性任务,比如跑迁移脚本。
二、四个原因,按这个顺序查
原因一,缺条件。 写了 depends_on,但没写 condition。一条命令能确认。
bash
docker compose config | grep -A3 depends_on
输出里只有服务名没有 condition 字段,就是这个问题。
原因二,healthcheck 配在调用方。 位置错了。healthcheck 必须在被依赖的那个服务块里,也就是 mysql 下面,不是 web 下面。配在 web 下,mysql 根本没有健康检查,service_healthy 永远不满足。
原因三,命令依赖镜像里不存在的二进制。 这个坑很常见,网上抄来的检查命令用 curl 探本机端口,但 mysql 8.0 镜像基于 Debian Slim,里面根本没有 curl,命令直接返回 127,healthcheck 永久失败。
文章给的修法是换成镜像自带的 mysqladmin。逻辑一样,二进制得存在。
原因四,检查太宽松或者宽限期太短。 写 echo ok 当检查,或者只测端口开着没,都会得到假健康。数据库端口通了但还在初始化,应用一连就报错。另一种是 start_period 给得太短,MySQL 初始化要三十秒,你给五秒,被判定不健康。
三、看 healthcheck 的执行记录
docker compose ps 只看状态不够,要看执行日志。
bash
docker inspect $(docker compose ps -q mysql) --format='{{json .State.Health}}'
关注 Log 数组最后一条的 ExitCode 和 Output。
ExitCode 127 且 Output 里有 command not found,就是原因三。ExitCode 0 但业务还是连不上,说明检查过于宽松,命中原因四。这两个的修法完全不同,别混。
顺带记一个细节,start_period 内的失败不消耗 retries 次数。所以给足 start_period,比把 retries 调大更对症。
四、替代方案与它们的代价
文章列了三种,取舍很清楚。
service_started 加应用层重试。适合 healthcheck 命令难写、或者启动顺序不确定但能容忍短暂失败的场景。代价是重试逻辑侵入应用代码,而且第一次请求可能失败。
把 restart 策略设成 on-failure 再加依赖。适合依赖服务启动时间波动大的场景。代价是首次启动可能失败并重启,日志噪音大,排查时容易被误导。
本文这套 service_healthy。适合检查命令能在容器内可靠执行、且能准确判断就绪的场景。代价是配置复杂度上升,检查命令要针对镜像定制。
有一种情况别用它,依赖服务是精简镜像,连 mysqladmin 都没有;或者就绪判断需要多个依赖同时满足,比如 Redis 和 MySQL 都要好,单一 healthcheck 覆盖不了。
五、搬到 Agent 服务栈上
我现在的 Agent 项目一般有五个依赖,模型推理服务、向量库、消息队列、数据库、缓存。启动顺序错了,最常见的报错是容器起来了但第一个请求 500。
三层检查,从粗到细。
进程活着。 最简单,随便回一个 200。它只能证明容器没崩,证明不了任何别的事。
依赖可用。 检查自己的依赖连得上。这一层解决上面那四种原因的大部分。
能跑一次最小业务。 比如推理服务连着模型跑一次十个 token 的推理,向量库跑一次空查询,队列发一条测试消息再删掉。这一层最贵,但只有它能证明服务真的能干活。
我的做法是前两层每十秒跑一次,第三层每三十秒跑一次,失败了只标记降级不直接杀容器。理由很实际,模型冷启动要几十秒,按秒级检查会一直判死。
| 层 | 检查什么 | 频率 | 失败处理 |
|---|---|---|---|
| 进程 | 端口能连 | 10 秒 | 重启容器 |
| 依赖 | 数据库、队列、向量库连得上 | 10 秒 | 摘流量,不重启 |
| 业务 | 真实跑一次最小请求 | 30 秒 | 标记降级,告警 |
| 就绪 | 上面三层都过 | 启动时 | 才允许接流量 |
一句经验收尾。启动依赖这件事,启动完成和能干活是两个状态,中间隔着一个健康检查。检查命令要在镜像里能跑,检查的内容要真的代表业务就绪。这两条都对上,那四个原因就不会再消耗你一个上午。
这一批还有两篇,一篇讲 Subagent 的本质是上下文隔离,一篇讲做技术选型 PoC 怎么才可信。感兴趣的关注一下。