网关长跑韧性与故障隔离
当模型列表消失、额度卡片停更、多个供应商同时超时、插件宿主内存持续增长,或客户端请求中断时读本文。分别检查推理、目录、认证、额度和进程生命周期,再决定是否重启。机器开机时间长、进程多或一次负载高,均不能单独证明故障原因。
针对“宿主持续增长,但不能中断任务”的具体顺序、事件关联和插件归因等级,读内存增长分层取证。
请求可用但慢、或怀疑 Agent/Skill 输入过重时,读输入开销与职责交接;从网关分查网络与输入证据,其他层的规则调整交对应维护方,效果仍结合缓存和任务质量复核。
个人进程号、账号、用量和日志原件保存在本机私有状态目录;公开文档只保留复核方法和已证实的机制。
1. 固定现场,不叠加诊断进程
- 记录
magpie --version、故障时间和时区。核现有应用、网关监听者、插件宿主父子链、启动时间和实际可执行路径;不另起网关做诊断。 - 核 provider/plugin 开关、实际绑定来源、模型暴露状态及组成员。只输出白名单,不打印认证、密钥、完整配置或带身份的错误原文。
- 做短时连续 CPU/RSS 采样,同时核磁盘、swap、认证文件变化与相关日志。累计 CPU 是历史消耗,单次 RSS 偏高不等于内存泄漏。
- CLI 读取设总超时;超时保留 TIMEOUT,不叠加同类全量扫描或连续空轮询。
- 修改前存 0600 快照;沿已有授权逐字段修改并回读。发现其他 writer 改动时重新对账,不整文件回滚。
健康检查只证明对应本机接口可用。恢复推理仍需请求的实际 tries、最终 served、状态与用量;已有新鲜回执时不重复探测。真实请求限用户授权内的最小验证。
2. 分开核五条链路
| 链路 | 应核证据 | 解释边界 |
|---|---|---|
| 推理 | 时间、实际 tries、状态、最终 served、用量 |
候选 order 出现不等于请求过;最终 200 可能由回退来源服务 |
| 目录 | 实时列表、暴露/隐藏、账号模型限定、客户端列表 | 空列表不证明下架;静态备用目录不证明当前地区支持 |
| 认证 | token 存在性/过期、刷新回执、保存结果、消费者 | 额度未知不等于退出登录;有 token 不等于刷新成功 |
| 额度 | readAt、窗口重置、刷新回执、历史采样 |
卡片不动不等于没有调用;不同入口可能共用一个订阅池 |
| 进程 | 监听所属、父子链、启动时间、IPC、更新交接 | 多个 host/app-server 不自动构成冲突;PPID=1 不自动等于废弃 |
路由持续有成功回执而额度卡长期没有新采样点时,先排额度采样。重启后恢复只能记为“重启后恢复”,具体刷新停顿原因仍需证据。
模型 hook 超时条数是本地事件数,不是外部 HTTP 请求数。npm registry 不可达不能直接解释全部 hook 超时;须核当时是否安装依赖、哪个事件反复触发刷新,以及内存增长的关联。
内存健康结合压力、swap 速率与缓存判断,不因 swap 总量较高就手动删除交换文件或停止系统内存服务。Apple 内存指标说明将这些指标分别定义。
3. 已复现:双插件认证同步导致刷新循环
一次故障中,常规订阅插件向副 provider 复制完整 OAuth 记录,副插件又将同一记录改成来源引用。两种表示交替落盘,触发 auth 变更事件;宿主失效并重载模型目录,重新执行同步 hook:
插件 A 写完整登录 → auth 变更 → 目录刷新
插件 B 写来源引用 → auth 变更 → 目录刷新 → 再回到 A使用两个虚拟账号及真实同步函数离线复现;停止一个同步方后,重复执行不再写入。现场定向关闭未使用的副插件后,认证文件停止持续变化。附近也发生过应用与宿主换代,后继宿主的 CPU/内存正常,不能当作同一个旧宿主自行回收内存的证据。这支持认证循环的判断,不证明历史上每次掉线均由它引起,也没有证明宿主具体的内存保留实现。
插件迭代要求:
- 同一共享认证记录只有一个写入者;按宿主支持的引用机制复用登录,不让插件互相修正同一份数据。
models/usage等高频读取 hook 保持幂等,真实内容未变则不落盘;不靠每次复制认证来“保鲜”。- provider off 与 plugin off 是两个开关。关闭 provider 不证明插件后台 hook 已停止;停用插件后核实际绑定、认证文件变化和 host 状态。停用前列明其全部 provider 的影响。
- 用虚拟账号、隔离存储和无网络 fixture 复现,不反复消费真实 refresh token 验证竞争。
多供应商同时异常时,先核共享宿主循环,再判断单家供应商或机器性能。
宿主超时与取消的放大效应
宿主 inTime 的超时仅放弃等待,底层模型目录 hook 可继续运行;普通额度 RPC 的取消也不等同于底层任务终止。在隔离虚拟插件上已复现:目录 RPC 超时返回后,多份底层任务仍挂起;普通额度任务收到 abort 后仍等待,直到插件完成。这是未完成任务保留,尚不能称已完成对象永远不被 GC 回收。认证事件风暴可能放大此类积压,但没有故障时的分配栈就不能量化其对历史内存增长的贡献。
结论须绑定实际加载的宿主脚本哈希。上述现象在 Magpie 0.1.2522 对应脚本复现;该版 Go 父进程的退役等待阶段最多十分钟,后续停止还有额外等待和强制退出保护,不能把十分钟当整个回收过程的严格上限。因此“关闭输入后短时仍等待”不等于“受正常托管的旧宿主会永久残留”。父进程被外部终止是另一种生命周期。
补修不能只加 Promise.race:还需插件 I/O 接受取消、按账号合并重复目录/额度读取,并限制未完成任务。没有实现与回归证据时不把这些建议记为已修。内存观察同时记录 RSS、物理 footprint 和虚拟预留,不能用大块未分配地址空间判定泄漏。
可复现的宿主任务生命周期缺口已提交 上游 issue #4678,内含无网络虚拟插件复现。它不是本地配置已修复宿主实现的证明。
4. MiniMax Code:登录、额度与模型消失
内置 API/Coding Plan 与 OAuth 插件入口分别检查;不据 UI 名字认定是同一渠道,也不把两个入口当双份额度。
- 开关:provider 是否 off?插件是否启用、实际由哪个版本服务?关闭的 OAuth provider 在某些 CLI 过滤路径可能显示普通余额接口“未配置”;交叉核
accounts、绑定和开关,不能据此让用户填写 Balance URL。 - 目录:核实时目录、暴露项、
delisted、账号限定和组成员。地区列表可能不同;失败后回退静态备用目录,不证明原模型被下架。先核实时目录,再调整暴露项。 - 认证:只读 token 元数据及刷新/保存结果。一次性 refresh token 需要正确串行化和持久保存;两个 host、一次超时或历史 signed-out 文本,不足以证明竞争消费。须保留刷新失败、保存结果或较新凭据的证据。
- 额度:对比账号接口、额度接口、采样时间与请求。未知保留未知,旧的用尽窗口不当当前限额。一个入口能读订阅、另一入口异常时先定位过滤路径,不重置账号。
- 路由:优先使用已接入且符合用户资源策略的稳定入口,不为恢复同一模型盲开重复 OAuth 来源。核组内位置与 classifier,区分分类器和 worker 请求。直接请求只证明该入口可用,组落点另核真实回执。
必须重新登录时,由用户完成必要授权;不擅自删凭据或复制其他应用的 refresh token,不循环执行登录、刷新或 provider test。
5. 更新交接、进程残留与重启
更新时新主进程可接管监听,旧进程暂留以完成在途请求;两代进程可能是正常交接。插件宿主可通过管道/IPC 服务而不监听 TCP,“PPID=1 + 无监听”不足以证明可清理。
调查残留要绑定 exe、启动时间、旧父进程、交接日志、IPC/文件持有和在途任务。exe/cwd 消失或不可中断等待只是线索,不能单独证明无业务价值,不据此批量 kill。
真正的操作系统重启会终止原来的用户进程,AbandonProcessGroup 不能让进程跨系统重启存活。相同 PID 可能复用;必须区分重启应用、服务和操作系统。
终止主进程后由 launchd 拉起属于服务重启,会中断在途请求,不等于 Magpie 自身更新交接。自动拉起取决于实际 job、KeepAlive 条件、退出状态和节流设置,不把本机配置当通用默认。
KeepAlive、ThrottleInterval 和 AbandonProcessGroup 的语义可核 Apple launchd 手册源码,并以安装版 man launchd.plist 复核;其中没有跨系统重启保留进程的机制。
重启/清理前确认授权、归属、在途影响和恢复入口;之后核监听、插件加载与代表性请求。不擅自 kill host 的父进程,不用固定周期重启掩盖认证循环。
自启任务的正常退出重拉循环
自启任务设无条件 KeepAlive=true 时,启动器若发现另一个实例已服务网关并正常退出,launchd 仍可能按节流间隔不断重拉。核 launchctl print 的实际 job PID、state、runs 和 last exit code:持续出现“spawn scheduled、退出码0、runs增加”,且监听者始终是另一个稳定 PID,支持调查这一循环;不能据“另一个实例存在”就终止它。
若需求是“正常退出不重拉,启动器异常退出才重拉”,可在核实退出语义后选条件 KeepAlive={SuccessfulExit:false},保留所需 RunAtLoad。它只监督该 job 自己启动的进程,不会监督一个独立 GUI 实例的后续崩溃,不能当成完整网关故障自愈。应用更新可能改写自启文件,之后须重新回读。
改 plist 不等于运行中的 job 已更新;重新装载 job 可能结束其进程。有正在运行的 job 时,不为改偏好直接 bootout。只有明确授权、确认 job 无运行 PID,且实际网关归属已核清时,才安排定向重载;备份前态、只改目标键,随后核监听者未变、健康状态及 runs 不再持续增加。
“不影响任务”的维护边界
只读巡检可在任务运行时有界、低频执行,仍会占用少量 CPU/I/O,避免叠加全量扫描。自动清理只能处理有明确归属、保留期和已结束证据的具名临时产物;已退出的普通进程没有可回收的用户内存,僵尸应由父进程回收。CPU低、无TCP监听、文件路径消失都不等于任务结束。
重启应用、清空缓存或结束进程需要对应组件支持停止接新任务、排空在途工作和恢复服务;单次连接数为0也有竞态。无法证明安全窗口时只报告并延期,不承诺全机“等同重启且零中断”。当前 Guardian 只读报告不代表已经实现任务感知的自动维护。
6. 只读巡检
scripts/gateway_guardian.sh 保留 status/reap/guard/cache/all 名称,本版均为只读报告:
bash <skill-dir>/scripts/gateway_guardian.sh status
bash <skill-dir>/scripts/gateway_guardian.sh allreap 只报僵尸数量和 PPID=1 宿主线索;guard 按可配置 RSS 阈值提示复核;cache 只统计已知缓存的过期文件。它不杀进程、不重启、不删缓存、不截断日志;DRY_RUN=0 也不开放写操作。
旧脚本 dry-run 未覆盖缓存删除,guard 也缺少完整归属与托管核验。Skill 更新不会自动替换仓库外运行副本;核 launchd 实际脚本路径和哈希,沿已有授权备份并窄更新后才记为采用。脚本不安装后台任务,不修改 launchd/Magpie 配置。
有界连续采样
需要判断趋势时,使用 magpie_resilience.py,避免重复调用会加载插件或刷新所有供应商的 CLI:
python3 <skill-dir>/scripts/magpie_resilience.py collect \
--samples 6 --interval 10 \
--output <skill-dir>/state/resilience/observation.local.json结果文件拒绝覆盖、权限 0600,输出目录必须为 0700。默认约五十秒,样本/间隔有限且总观察不超过五分钟;参数和实际覆盖时间均写入回执。脚本只读 ps 和认证文件的 stat 元数据,不读取认证内容、不调用 Magpie CLI、不请求网络。配置目录沿 XDG_CONFIG_HOME,也可显式指定 --config-dir。
按 PID 与启动时间分段,宿主更换不能拼成一条内存曲线。认证 mtime 变化次数是相邻采样的观测下界,无法捕获采样间全部写入;合法 token 刷新也会改变时间戳。采样失败记 unknown/partial 并非零退出,不能当零进程/零增长。RSS 变化和认证写入只提供线索,不输出“已确诊泄漏”或自动触发清理。
7. 等待上游期间的本地缓解
按现场需要选择,先保存前态与可读计划,使用已装 CLI 支持的命令;不把以下操作全部设为通用默认。
| 发现 | 最小缓解 | 回读与边界 |
|---|---|---|
| 官方包与多个旧 fork 同时加载,共享认证写入者不清楚 | 核功能差异和当前绑定;选择满足当前需求的已安装插件后,magpie plugin use <spec> <provider>,再 plugin off <unused-spec> |
保留源码、凭据、账号和组成员;核实际 serving spec、模型与账号数量。停用一个插件影响它提供的所有 provider |
| 不用的副 provider 已 off,其插件却仍运行 hook | 停用对应未使用插件 | 不通过删除账号、清空凭据或重置额度止血 |
| 运行期频繁换版本,难以绑定故障基线 | 可选择 magpie update channel stable 和 magpie update auto on notify 24h |
只更改更新偏好,不降级当前版本;notify 不会自动安装修复,看到重要修复后安排验证窗口 |
| 探测脚本、GUI 或多个 Agent 反复全量读取 | 先复用已有回执和本机文件元数据;手动刷新合并为单次有界操作 | 保留正常自动额度采样和推理,不用高频全量 quota/sync 轮询代替健康检查 |
| 巡检依赖 RSS 单阈值定时 kill | 使用只读报告;具名复核后才安排有影响的恢复动作 | 不修改系统 swap,不根据 PPID=1/无监听清理,不承诺无中断 |
每次变化后检查配置的目标与无关字段、实际 provider 绑定、正常模型最小请求及其 served;随后连续采样。插件切换可以触发宿主正常换代,不能把新 PID 的低 RSS 作为旧进程回收证明。恢复时只撤销本次仍匹配预期后态的字段,不把旧快照整文件覆盖回去。
8. 恢复判据
短时复核:认证文件不再持续改写、目录读回、host 资源不再持续失控、网关健康、实际请求成功。记录窗口和同时发生的升级、开关、重启,不把单次通过称为长期稳定。
跨有效期 OAuth 刷新、不同地区目录、多客户端并发、长期内存走势、厂商计费和 Agent 后续执行效果,按证据分别保留 NOT_VERIFIED;CLI/静态检查不能替代。