健康检查端点把整个面板渲染了一遍:空载 1.5 秒,编码中 4.2 秒
一秒半的回答,在调用方眼里等于“不在”
健康检查是最便宜的一种契约:一个请求进去,一个诚实的布尔值出来,快到调用方不需要为它思考。它也是一个系统里最容易烂掉的端点,因为它做的事情看上去没有任何一处是错的。它返回 200,载荷能解析,它报告的那个队列确实健康。
我维护一台媒体处理控制面的控制进程:一个持有约 3,800 行 SQLite 队列的 supervisor,带按泳道分的 worker 线程、一个把文件系统与队列对账的 scanner,以及一套被三类轮询者使用的 HTTP 接口。桌面壳要挂上来,托盘看门狗要盯着它,面板自己每三秒拉一次状态端点。
代价是一个上午的故障是这样的:桌面壳报**“8790 上没有 supervisor,也没有启动过”**,而四条编码泳道正在处理队列。什么都没挂。用 curl 打同一个端口,返回 200——大约一秒半,而且手上是有活在跑的。桌面壳的挂载探测在 0.5 秒就放弃了,于是“活着的 supervisor”和“不存在的 supervisor”得到同一个结论:预算之内什么都没来。
这就是值得写下来的故障形状。端点没有坏,它在回答一个比被问的大得多的问题,而超时是唯一一种无法与死亡区分的答案。
端点是对的,这正是问题
/healthz 调用的是 sup.state()——渲染整个面板的同一个方法。那份载荷不是一行状态,它要算 ETA、算建议视图、算即将执行与已决策的行、算基础设施故障、算作业统计,读一遍许可证,取一次系统信息快照,再取守卫状态,最后把这一切序列化。
2026-11-10,一条泳道在跑编码时的实测:
| 条件 | /healthz 耗时 | 桌面壳预算 |
|---|---|---|
| 空载 | 1.5 秒 | 0.5 秒 |
| 一条泳道跑 x265 | 4.2 秒 | 0.5 秒 |
在任何工作到来之前,这两个数字就已经越过了调用方的预算,也就是说这个端点从设计上就一直在辜负它唯一的职责。二阶损害比一阶更糟:三类轮询者定期命中这条路径,于是看门狗、挂载探测和面板,每一跳都把一次完整的面板渲染拖到一台本来就在编码的机器上。一个健康检查耗费的正是它要衡量的东西,那它是反馈回路,不是观测。
修法不是“把贵的调用缓存起来”。缓存一份为别的消费者组装的载荷,只会让错误的答案更早抵达。这个端点需要属于自己的载荷,刻意比面板的小,只保留判断“supervisor 是否活着”真正需要的字段。
六个字段、两条查询、一条旁连接
新实现返回六个键:ok、started、uptime_s、lanes_running、pending、done_today。其中只有两个会碰数据库,而且它们正是 state() 开头那两条计数,所以面板与探针不可能在队列状态上各说各话。
有三个决定值得留住:
同一个表达式,而不是同一个意思。 uptime_s 用的是 state() 里一模一样的表达式。写一个“差不多”的版本,正是两个端点开始差一秒的开端,而看门狗与面板之间的这种不一致,是要花掉一整个下午去追的东西。
缓存带自己的锁,TTL 很短。 两条计数在线上队列上实测分别是 0.1 毫秒(按泳道数 pending)与 5 毫秒(今天的 done),不贵,直到三个轮询者同时问。2 秒的 TTL 足够吸收它们,又短到没人会看着一个陈旧数字超过一次呼吸。uptime_s 与 lanes_running 每次请求现算,因为两者都不花钱。
计数查询走只读旁连接,不走共享连接。 共享连接被一个 db_lock 串行化,而 scanner 是成批地持有它。排在扫描后面的探针照样会把超时交给桌面壳——正是这个端点存在的意义所在的那个故障。2026-11-10 实测:重启后的冷探针为那把锁等了 0.72 秒,而同样两条计数放到一个短命的 mode=ro URI 连接上是 8-18 毫秒。只读还白送第二重保证:这条路径永远不可能写入、迁移或做 checkpoint。
🔍 `Supervisor.health()` 与只读计数路径(Python,57 行)
HEALTH_COUNT_TTL_S = 2.0
def health(self) -> dict:
"""The `/healthz` payload - deliberately NOT `state()`.
`state()` renders the whole dashboard: insight views (ETA, advisory, upcoming, decisions,
infra failures, job stats, decided rows, saved), the licence read, sysinfo, guards. Measured
2026-11-10 with one lane encoding: 1.5 s idle, 4.2 s under x265.
"""
now = time.time()
with self._health_lock:
if self._health_counts is None or (now - self._health_ts) > self.HEALTH_COUNT_TTL_S:
self._health_counts = self._health_counts_uncached()
self._health_ts = now
pending, done_today = self._health_counts
return {"ok": True, "started": self.started,
# same expression state() uses, so the two endpoints can never disagree by a second
"uptime_s": int(time.time() - time.mktime(time.strptime(self.started,
"%Y-%m-%d %H:%M:%S"))),
"lanes_running": sum(1 for w in self.lanes.values() if w.running),
"pending": pending, "done_today": done_today}
def _health_counts_uncached(self):
"""`(cpu pending, done today)` on a READ-ONLY side connection.
`self.conn` is serialised with `db_lock`, which the scanner holds in bursts, so a probe that
queued behind a scan would still hand the shell a timeout. Measured 2026-11-10: the cold probe
took 0.72 s right after a restart (lock wait), while the same two counts cost 8-18 ms on a
side connection. `mode=ro` also means this path can never write, migrate or checkpoint.
"""
count_sql = "SELECT lane, COUNT(*) n FROM files WHERE state='pending' GROUP BY lane"
done_sql = "SELECT COUNT(*) FROM files WHERE state='done' AND verified_at LIKE ?"
today = (time.strftime("%Y-%m-%d") + "%",)
side = None
try:
import sqlite3
side = sqlite3.connect("file:%s?mode=ro" % self.db_path.replace("\\", "/"),
uri=True, timeout=5)
pending = 0
for r in side.execute(count_sql):
if r[0] == "cpu":
pending = r[1]
return pending, side.execute(done_sql, today).fetchone()[0]
except Exception: # noqa: BLE001 - fall back below
pass
finally:
if side is not None:
try:
side.close()
except Exception: # noqa: BLE001
pass
with self.db_lock:
pending = 0
for r in self.conn.execute(count_sql):
if r["lane"] == "cpu":
pending = r["n"]
return pending, self.conn.execute(done_sql, today).fetchone()[0]
最底下那条回退路径是刻意留的,也值得点名:万一旁连接打不开,探针退回共享连接并在锁下执行。它更慢,但它仍然有界,对一个最坏失败模式是沉默的端点来说,这是正确的取舍。两条路径取行字段的方式也不同——旁连接用 SQLite 默认的元组游标,共享连接返回 sqlite3.Row,所以同样两条查询,一条按位置取值、另一条按列名取值。
钉依赖,不钉耗时
要防的回归不是“端点又变慢了”,而是“有人顺手把面板渲染器又挂了回来,因为反正它就在那儿,载荷看起来还更丰富”。这是两个不同的性质,只有第二个能被可靠地测试——在测试套件里断言耗时,等于在负载机上抛硬币。
所以第一个测试把 sup.state 换成一个会抛异常的函数,然后调 health() 并断言载荷正常。任何人若把那个依赖装回去,测试会带着成本说明失败:
expected = sup.state() # snapshot taken before state() is replaced
def boom():
raise AssertionError("/healthz called state(): that is the 1.5-4.2 s the shell cannot "
"wait for")
sup.state = boom
got = sup.health()
assert got["pending"] == expected["queue"]["cpu"]["pending"] # the panel and the probe agree
assert got["done_today"] == expected["done_today"]
第二个性质是缓存永远在威胁的那一条:它不能变成谎言。TTL 之内新增的行允许暂时缺失;TTL 过后仍然缺失就不允许。测试先加一行、断言缓存里的数,把缓存时间戳往前拨过 TTL,再断言新数字到来。一个永不过期的缓存能通过所有耗时测试,同时报告一个一小时前就已经清空的队列。
撑住这一切的套件现在是 1,596 个测试、15 个跳过——部署路径也平淡得像它该有的样子:把模块拷进已安装的那份,在所有泳道都已停止的前提下用边界重启脚本重启,确认 autostart_lanes 和每条泳道的期望状态原样回来。
部署后的实测
- 一次探测 1.8-2.9 毫秒,对照空载 1.5 秒的基线。
- 载荷报
pending=709、done_today=8,与同一刻的/api/state一致——测试钉住的那条一致性,在线上队列上同样成立。 - 原来 0.5 秒的探测预算,现在冷启动探测大约 12 毫秒即可完成,留出超过 480 毫秒的余量。
- 编码进行中桌面壳重新挂得上来,这是唯一真正要紧的那个测量。
结果
/healthz耗时:空载 1.5 秒 / x265 下 4.2 秒 降到 1.8-2.9 毫秒。- 冷启动锁等待:共享连接 0.72 秒 降到只读旁连接 8-18 毫秒。
- 载荷:整个面板渲染 降到六个字段,其中两个是查询,加 2 秒 TTL 缓存。
- 测试:1,596 个通过、15 个跳过,依赖与缓存过期两件事都被钉住。
- 桌面壳现在能在 supervisor 正在编码时挂上它,而不是报告它不存在。
带走的只有三句。 延迟预算该写在载荷旁边,而不是躺在调用方的配置里;按契约便宜意味着另开一条路径,而不是把同一条跑得更快,因为建在面板载荷上的一切都会继承面板的未来;共享连接就是一条队列,那 0.72 秒不是慢,是在等,而没有任何 profiler 会把它记在健康检查账上。
服务器频繁异常重启、云账单过高,或缺一位能穿透内核日志的架构师?
真正的生产环境稳定性,靠的是穿透表象抓出根因。我独立管理着跨 3 台物理/云主机、162 个容器的高可用自托管生产网络。