附录 A 排障案例集
来自《系统架构与工程化学习》 · 原稿更新 2026-11-09 · 服务器只读阅读视图
具体工具、具体某次故障的记录,按章归类。正文用“案例见附录 A.x.y”指向这里。
A.2 第 2 章 HTTP 与网关
A.2.1 MCP 旧 SSE 传输的认证与超时
- 现象:旧式 MCP HTTP+SSE 传输接入时,事件流能建立,请求仍可能返回 401;超时也难以用一个阈值统一。
- 排查方向:事件流建立不代表 OAuth 身份已经传到实际发请求的客户端;只在 Provider 里构造认证配置却没交给 Client,仍可能返回 401。短请求超时、SSE 流读取超时和代理空闲超时分别检查,不宜把“统一设置 300 秒”当通用答案。
- 教训:旧 MCP HTTP+SSE 是兼容传输,新的远程 MCP 连接通常优先 Streamable HTTP,但这不意味着普通网页的 SSE 推送机制被废弃。原测试用 mock 验证参数传递,不能直接当成生产环境无故障的证据。
- 来源:MCP Python 传输文档 · 旧 SSE 迁移说明
A.2.2 Clash Fake-IP 与内网域名
- 现象:内网排障时,内部域名可能被交给不认识它的 DNS 或代理。
- 排查方向:Clash Fake-IP 是常见来源。核对内部域名的 Fake-IP 规则、DNS 分流,以及最终私网地址是否走正确的 DIRECT 路由。
- 教训:TUN 模式下,仅配置系统代理的绕过名单,未必改变 DNS 分流。
A.2.3 第三方登录辅助工具的 refresh_token
- 现象:第三方登录辅助工具写出的配置里,
refresh_token字段装的是浏览器会话令牌。 - 排查方向:字段名叫 refresh_token 不意味着它真能刷新:要查颁发方、有效期、授权范围及是否可轮换。
- 教训:工具能写出配置文件,不等于获得官方长期认证。个人认证材料不能复制到普通日志和知识书。
A.2.4 接入模型报错的归因
- 现象:接入模型报错时,某条中转 API 的 401/403/404 容易被直接当成模型整体不支持。
- 排查方向:先核对请求 URL、服务商、身份凭据所属渠道、权限、额度和真实返回码。
- 教训:把账号、配置、接入方法和产品缺陷分开归因;账号配置错误不等于产品代码缺陷。
A.3 第 3 章 数据库
A.3.1 逻辑删除仍占着联合唯一键
- 现象:用户与角色/分组的关联表用联合唯一索引。关系逻辑删除只把
deleted置 1,旧行仍留在索引里;再给同一用户分配同一角色或分组时报Duplicate entry。 - 根因:逻辑删除保留旧行,旧行继续占着联合唯一键,新插入自然撞键。
- 教训:先确认该表要不要审计与恢复,再决定逻辑删除还是物理删除。当时在这张中间表用
@Delete物理删除释放关系;是否适用于其他表,要先确认审计需求、删除语义和索引设计。也可以改索引与约束设计,让删除状态参与唯一性。
A.3.2 WAL 文件消失但进程仍握着旧 inode
- 现象:旧 Hermes Gateway 出现
state.db-wal、-shm从目录里消失,进程的文件描述符仍握着旧 inode;守护逻辑检测到不一致后拒写。 - 根因:路径存在不等于运行进程握着同一份文件。路径被删除或替换后,fd 仍指向已 unlink 的 inode,不同连接可能各自写出一份历史。
- 教训:排障先保全现场,比对 fd inode 与当前路径 inode,验证主库与 WAL 的一致性,再决定恢复方式。不要看见写不进去就直接删除日志文件重建。当时未查到到底是谁删除了文件。
A.3.3 FTS5 外部内容表留下重复索引
- 现象:旧项目用 SQLite FTS5 外部内容表(
content='memories'、content_rowid='id'),尝试INSERT OR REPLACE去重,可能留下重复索引或遇到冲突,检索与融合排名因此失真。 - 根因:外部内容表的索引按原表行 ID 对齐,两行
filename相同并不满足业务唯一约束;排重键没有和索引行 ID 对齐。 - 教训:先在权威源表确定唯一键和行 ID,再按 FTS5 类型用事务、同步触发器或明确的删除命令维护索引,必要时
rebuild,并用查询和一致性检查确认。不能把“先按filenameDELETE 再 INSERT”当成所有 FTS5 表的通用修复;具体项目的测试结果仍需回原源码核对。
A.5 第 5 章 异步
A.5.1 同步 SDK 与异步客户端的超时排障
- 现象:把同步 SDK 放入
asyncio.to_thread后,事件循环能继续处理其他任务,但超时并不能强杀正在运行的线程。另一种AsyncClient取消后,可能仍在等 gRPC 连接清理。 - 根因:当时排查指向上游响应接近 45 秒超时阈值时的竞争,不能推导为整个 Agent 框架不支持异步。
- 教训:超时只是调用方不再等待,不代表工作线程或连接清理已经停止;要分别测请求超时、取消响应、资源关闭耗时和连接泄漏。
- 来源:asyncio Tasks、取消和 TaskGroup
A.6 第 6 章 分布式
A.6.1 调度开关有两个“主人”
- 现象:曾用
hermes cron pause关闭推送,个人工作台的 WebDAVpush_control.json却在下一次同步重新打开它。 - 根因:调度状态有两个“主人”,本地 CLI 和远端 WebDAV 开关都能改它,没有约定谁是权威。
- 教训:先决定本地 CLI 和远端开关谁是权威、同步失败怎样呈现、何时记录最后写入者;CLI 返回成功不代表最终生效配置已稳定。
A.6.2 飞书突然推送 70 多条
- 现象:消息突然暴增到 70 多条。
- 排查方向:先查 cron 是否误设为每分钟触发,再看是否一次任务内容过多。
- 教训:按 run_id 统计真实启动次数,并加发送幂等与重复告警。只修内容筛选挡不住调度风暴。
A.6.3 两台设备都显示 WebDAV 同步成功,任务却互相看不到
- 现象:电脑和手机各自报告同步成功,但一端的任务在另一端看不到。
- 根因:不是要换数据库,而是两端写入两个不同的远程目录:
super-productivity与Super Productivity。 - 教训:先比较完整远端目标路径、身份和对象 ID,再做 A 创建→B 读取→B 修改→A 回读的真实往返测试;路径不一致时不要启动危险的覆盖同步。
A.6.4 多端计时同步要共享起点与权威状态
- 现象:手机端显示的是旧版本行为。
- 排查方向:先核对缓存和页面版本。
- 教训:多端计时器必须共享开始时间、权威状态和版本,界面用同一状态推算经过时间。验收要用手机和电脑同时核对开始、暂停、恢复,不能只看单端 UI。
A.6.5 某个模型报 429,不代表这个模型坏了
- 现象:某个模型报 429,几个模型在同一路由都 429,另一供应商正常。
- 根因:要区分单模型限流、共享工作区预算、账号额度、网关并发阈值与暂时服务故障。多个模型同时 429 更像上游共享配额问题。
- 教训:不应靠清空密钥或改 Prompt 解决,先确认额度作用范围。
A.7 第 7 章 可观测与排障
A.7.1 采样截断被误判为文件损坏
- 现象:读 UTF-8 中文文件的前几个字节时,若恰好切断多字节字符,样本解码会出现替换字符
U+FFFD,于是被当成原文件是二进制或已损坏。 - 排查方向:结合总文件长度、增量解码或在完整字符边界上取样,区分样本末尾的截断伪影和源文件内部的非法字节。两类 UTF-8 问题要分开:截断样本不足以证明完整源文件有坏字节;而真正从磁盘读到非法 UTF-8 时,便利解码又会用替换字符消掉证据。
- 教训:旧 Agent 评测 CLI 的一次真实修复,改为按原始字节严格解码(例如 JavaScript
TextDecoder('utf-8', {fatal: true})),在解析 JSON 前拒绝非法输入并确认评测记录不被追加。当时有 6 项相关测试记录,旧文估算的中文“固定失败概率”不能当普适值;旧项目曾记录 580 项测试通过,那只是当时证据,不代表当前工作区重新运行过。
A.7.2 CPU 接近 0 但有 ESTABLISHED 连接
- 现象:CPU 接近 0、存在 ESTABLISHED TCP 连接,就被判断为模型服务端卡死。
- 排查方向:这两项只能说明进程可能在等待 I/O。要核对当前会话 PID、请求时间、最近流增量、超时与代理日志,再决定是否取消那条请求。
- 教训:另一个端点能调用,既不能证明本次请求必然正常,也不能证明它必然失败。
A.7.3 Pi 重试三次仍报错
- 现象:按 2/4/8 秒退避重试三轮,仍然
connect error。 - 排查方向:先分清是“错误没被重试规则匹配上”,还是“已经重试但上游一直坏”。看错误是否被规则匹配、每次 attempt 是否真的发生、退避间隔和最终失败类型。
- 教训:相同上游持续故障时,不断发“继续”不会修好;写操作还要考虑幂等。
A.7.4 旧 Agent 缓存统计失真
- 现象:旧 Agent 的缓存命中率报表,答不了真正的命中率。
- 排查方向:分母应是符合统计口径的读取尝试。历史项目曾把写工具混入读取分母,或把固定常驻的身份提示词算成普通缓存访问。
- 教训:曾设计由 SQLite 存累计统计、
cache.log保存排查明细,两份输出都要从同一分类规则产生。这是旧草稿里的排查和拟修复路径,未线上验证。
A.8 第 8 章 协作与 Git
A.8.1 Worktree 隔离被软链接绕过
- 现象:以为只更新了
~/.pi/agent/AGENTS.md这份运行配置,结果另一个正在使用的 Git 工作区被意外改脏。 - 根因:该路径是指向基础设施仓库
agent-skills/prompts/pi.md的软链接,写配置实际写到了源码。 - 教训:写配置前用
lstat/readlink/realpath核对真实落点与所在分支,不能因为路径在 Home 下就认为“不是改源码”。未经许可不要自动reset、stash或restore。
A.8.2 规定了必须用 Worktree,现实只有一个人在用
- 现象:仓库规范写了主目录保持 main、多代理各自 worktree,现实却只有一个人在用,多数分支仍从主目录切换。
- 根因:规范只写在文档里,没有落进脚本、
AGENTS.md、任务分配和 PR 检查,流程就没有生效。 - 教训:用 worktree 隔离要靠工具链强制,不能凭文档写过“必须 worktree”就当已隔离。清理前先看真实工作树与未提交修改。
A.8.3 交接模板 YYYY/MM/DD 中的 DD 被模型当成完整日期
- 现象:Agent 填文件路径时把
DD当成完整日期。 - 根因:
YYYY/MM/DD占位符没有说明字段长度,模型容易误读;DD是两位日号。 - 教训:对目录与文件名分别定义字段长度,给一个正确示例和一个重复年月的反例,再用路径校验兜底。正反例比模糊占位符有用。
A.9 第 9 章 部署与本机环境
A.9.1 本机程序“终端能启动、Finder 双击 offline”
- 现象:旧 Pi Web GUI 在终端里能启动,从 Finder 双击却显示 offline。
- 根因:两套环境没继承同一份 Node PATH,
env node找不到解释器。另一次launchctl bootstrap失败被误说成 macOS 不支持托管,真实原因是目标服务标签处于disabled。 - 教训:分别核对 Shell、Finder、launchd 的实际命令路径、plist、服务域状态和端口日志,不要一上来重写业务。
A.9.2 飞书 MCP 被关闭后反弹
- 现象:本机飞书 MCP 清理过一次,实例又被拉起来。
- 根因:Codex Desktop 的旧 fork 保留了启动配置,继续拉起实例。清理时要分清“杀掉旧进程”“阻止旧会话重新启动”“长期内存压力恢复”三个状态。
- 教训:关闭后仍可能要在启动器入口做一次授权/启用检查,并用实际 PID 追踪验证。该历史修复与未合并的监控 PR 不能混作同一交付。
A.9.3 Mac 本机 cron 离线时不准点
- 现象:旧 Research 任务 08:17 开始后失败,中午人工重跑才成功。
- 根因:出门断网、DNS 不可达。单纯把 cron 从 8 点改到 7 点,不解决机器睡眠与任务中途离线。
- 教训:短期要有恢复联网后的幂等补跑、时效窗口和投递回执;长期若要求准时,就改用真正常在线的执行环境,并验收费用与凭据托管。
A.9.4 原生 Node/SQLite 依赖修好又坏
- 现象:原生 Node/SQLite 依赖突然报不兼容。
- 排查方向:安装目录使用的解释器,不一定是真正启动进程的那个。
- 教训:先确认真正执行的 node 路径、Node 版本和 ABI,再决定 rebuild。盲目重复安装通常治标不治本。
A.9.5 Mac 上 Bash 脚本失败
- 现象:同一段 Bash 脚本在 Mac 上跑不通,容易先怀疑网络。
- 排查方向:macOS 自带旧版 Bash,可能缺
mapfile等新命令;GNU 与 BSD 工具也有差异。 - 教训:先查 shebang、实际 Bash 版本和工具差异,再选兼容的逐行读取方式,或明确声明依赖新版解释器。
A.9.6 Node 25 比 Node 22 新却安装失败
- 现象:装了更新的 Node 25,依赖反而装不上。
- 根因:某依赖的
package engines限定 Node 22、24 或 26 以上,Node 25 不在支持范围。版本号更大不等于更兼容。 - 教训:读实际 node/npm 路径与
package engines,选经过验证的版本再安装,不能只靠重新安装解决。
A.9.7 AionUI 报“模型上游错误”实为 CLI 路径不存在
- 现象:客户端提示“模型上游错误”,看起来像 provider 出问题。
- 根因:原始异常是本地 Agent CLI 路径搬家后不存在,请求根本没进入模型层。
- 教训:迁移项目目录后先核对
command_override、可执行文件及--help,再查 provider。不要因为统一错误文案就去换 Key。
A.9.8 CI 全绿而 Bridge 仍在跑旧工作树
- 现象:Bridge 的修复在 worktree 里测试通过并开了 PR,CI 也全绿,就以为生产已经换新代码。
- 根因:从改好到生产生效还有合并、部署、常驻服务重启、实际 commit 生效和用户路径验收几道关。Bridge 仍运行旧工作树时,CI 全绿只说明分支上的测试过了。
- 教训:按“合并 → 部署 → 重启常驻服务 → 核对实际 commit → 走用户路径验收”逐项确认,才算换完代码。