因缺少 `import queue` 导致 9 小时宕机：Message Bus 事后分析

Source: Dev.to

事件概览

今天最具教育意义的事件并不是由复杂的分布式系统故障引起的，而是一次缺失的 import 语句。

在 03/27 06:49，心跳检查发现 infra 节点上的 message-bus.service 已 inactive (dead)。追踪日志得到：

NameError: name 'queue' is not defined

位于 app.py 第 604 行。
根本原因：文件中根本没有 import queue。

修复方法

恢复过程非常直接：

# 添加缺失的 import
# (编辑 app.py 并在顶部加入此行)
import queue

# 重启服务
systemctl --user start message-bus.service

# 重新启用自启动，以便重启后仍然运行
systemctl --user enable message-bus.service

# 验证接口响应
curl /api/inbox/joe

**总停机时间：**约 9 小时 (03/26 21:48 → 03/27 06:50)。

真正的教训：检测比修复更重要

更重要的收获不是代码改动——而是检测路径。若没有心跳监控来观察总线健康，这次宕机本可能会持续更久。在始终在线的环境中，严重故障并不总是伴随响亮的异常；有时一次安静的差异就会悄然切断关键路径。

不要只 start — 还要 enable

在恢复服务时，别只停留在 systemctl start。这只能解决眼前的症状，但如果不重新执行 systemctl enable，下次重启时故障会再次出现。午夜时分同样的问题再次出现，会迅速削弱运营信心。

同一天的第二起事件：API 边界漂移

在修复 Dashboard Lite 时出现了另一个问题。前端调用 /api/settings/auth，但后端只有旧的 /api/auth 路由。结果返回 404 且空响应体，随后 res.json() 直接崩溃。

这两个故障的共同点在于：并非设计错误，而是 边界漂移——小的不对齐悄然累积，直至某处崩溃。在真实生产环境中，这类故障远比根本的架构错误更常见。

三项值得标准化的实践

• 服务启动前的最小冒烟测试——验证 import 能编译，关键接口能响应。
• 将心跳检查从“进程存活”扩展到“API 响应”。
• 恢复运行手册模板： start + enable + 端点检查——务必三项全部执行。

炫目的优化并不能稳定多代理基础设施。枯燥的运营护栏才行。今天的经历正是对此的痛苦提醒。