opencodex Codex 多账号池 502 频发根因分析：会话内首个 502 之后的 split-brain 残留路径与修复方向（186 RCA S）

【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址https://gitcode.com/gh_mirrors/ope/opencodex点击查看免费下载导读本文基于 opencodex 仓库 dev 树的实测 RCA 记录006_rca_s_sticky_502.mdissue #186深入分析 Codex 多账号池account-pool在 round-robin 轮询 多会话并发场景下首个 502 之后会话内 502 反复出现的残留路径。文章完整还原当前账号亲和性affinity与上游健康upstream health策略地图逐条拆解 4 个残留差距假设并结合当前仓库源码验证其中关键机制如incomplete被终端记录为成功导致的 split-brain、transient soft-avoid 的 30s 固定窗口与 escalation 现状最后给出 6 条可落地的修复方向。读者将掌握该代理网关在账号级故障隔离、会话粘性与 failover 之间的完整权衡以及诊断这类客户端看到 502、路由侧却判定成功问题的排查思路。一、症状与证据边界什么现象触发了本次 RCA在 opencodex 的多 Codex 账号池配置下account-pool以 round-robin 策略轮询账号同时并发运行 5 个 Codex 会话时只有部分会话在经历首个502 upstream_server_error/Provider unreachable: socket closed unexpectedly之后持续反复失败而其余会话保持正常。这正是会话内 502 频发残留的典型形态。证据边界必须明确两点RCA 原文也做了标注用户最初提供的复现日志基于v2.7.28修复未包含版本只能作为症状的定性佐证后续修复版本中 2/5 会话仍复现的口头报告在 RCA 调查时点需要通过 GitHub API 二次确认尚未定论——残留结论主要由下述代码级缺陷推得而非依赖该后续报告。这种日志版本滞后 代码缺陷支撑的组合决定了本次 RCA 的产出是修复方向清单而非单纯的版本回归结论。二、现状亲和性策略地图Affinity Policy MapRCA 首先测绘了当前账号选择与故障隔离的完整策略面。结合当前仓库源码可将其归纳为四个维度行号为当前 dev 树实测量1. 会话亲和性Affinity全局 threadAccountMap全局映射threadAccountMapthreadId → accountId保证同一会话thread连续轮次尽量落在同一账号以复用 Codex 的 prompt-cache 前缀空闲 TTL 24h、最大条目 2048相关常量定义在 thread-affinity.tsCODEX_THREAD_AFFINITY_IDLE_TTL_MS、CODEX_THREAD_AFFINITY_MAX_ENTRIES。2. 上游健康upstreamHealth账户级 soft-avoid健康状态按账号全局记录upstreamHealth[accountId]而非按会话transient 失败connect_error / timeout / 5xx的 soft-avoid 窗口固定为 30sfailure streak 计数窗口为 5 分钟CODEX_FAILURE_WINDOW_MS 5 * 60_000见 cooldown-math.tsfailover 阈值默认 3 次config.upstreamFailoverThreshold ?? 3见 routing.ts。3. 选择排除与解除规则被排除的候选hard cooldown429 触发的强制冷却、soft-avoidtransient 触发、needsReauth401/403 触发当绑定会话的账号进入 avoid / 达到阈值时解除该 thread 的亲和性并重新选择connect_error/timeout/5xx 记录时立即删除该 thread 的 affinity达到 failover 阈值时删除该账号的全部affinity401/403 →needsReauth 全部解除429 → hard cooldown 全部解除2xx 则立即清除 avoid 与 streak。4. 候选耗尽兜底fail-open当所有候选账号均不可用时会静默回退选择 soft-avoided 的 active 账号fail-open这正是已知不良账号被复用的入口。这一策略面在 routing.ts 的recordCodexUpstreamOutcome中得到了完整实现函数按classifyCodexUpstreamOutcome将上游结果分为success / credential / workspace / quota / transient / caller / neutral / unknown多个类别分别执行清除、隔离、冷却或记录 streak 的动作。三、残留差距假设按可能性排序假设 1最可能HTTP 200 之后的 mid-stream reset 被记录为账号成功——split-brain这是本次 RCA 的核心发现机制链如下头部headers之前的 fetch 拒绝会被正常记录为connect_error/timeout这是正确的200 之后 SSE 流中途断开时客户端 tee 会生成合成事件response.failed/upstream_reset但记录 routing outcome 的 inspection 分支在read throw 时统一上报为incomplete终端 recorder 于是将incomplete当作正常 200 成功记录当前源码中对应 core-codex-account.ts 的codexForwardTerminalOutcomeRecorder当status incomplete且无 429/402 quota 状态时记录recordCodexUpstreamOutcome(config, authCtx.accountId, 200, ...)。结果产生split-brain客户端真实看到 502而路由侧把这次请求记成账号成功——不设置 soft-avoid、不解除 affinity、不增加 streak甚至会把此前积累的失败健康状态当作成功直接清除。随后该账号继续以健康身份被 round-robin 选中下一轮再次 502形成会话内反复失败。Windows 原生侧更严重由于是 raw native relay连合成的 failed 尾巴都不存在失败信号完全丢失。当前仓库源码佐证relay 侧已开始区分无协议终端的干净 EOF与带上游错误的中断——见 relay.ts干净 EOF 生成adapterEofIncompleteFrame而携带upstreamError时生成upstreamErrorTailFrame即 failed 502 尾巴。因此 split-brain 是否彻底消除取决于 inspection/tee 分支能否把 mid-read throw 正确映射为transport_failure/failed502而不是笼统的incomplete。这正是修复方向 1 的核心。假设 2结构性不良账号缺少升级escalation旧策略只存在 30s 固定的 soft-avoid反复失败只会不断刷新 30s 窗口单次 2xx或一次被误分类的 incomplete就能把 streak 全部清零。于是真正持续不可用的账号每 30s 就重新进入候选池无限循环被选中→失败→30s 后重来。当前仓库源码佐证此问题在现有代码中已有实质改善——cooldown-math.ts 定义了CODEX_TRANSIENT_SOFT_AVOID_ESCALATION_MS [30s, 2m, 10m, 30m]的阶梯数组routing.ts 按consecutiveFailures索引取对应档位同时成功恢复路径对已升级账号要求连续 2 次成功才彻底清除routing.ts。这说明30s→2m→10m→30m 连续 N 次成功才恢复即修复方向 2已在后续版本落地。RCA 原文描述的仍是修复前的 30s 固定窗口。假设 3选择前 health-check 只看本地状态usable判定围绕 credential 是否存在 / generation / needsReauth 展开见 account-usability.ts 与isCodexAccountSelectable。问题在于refresh 能成功、但特定 backend 请求被拒绝的账号例如 workspace 授权缺失、接口级拒绝会被判为 usable 继续留在候选池。这类凭据活着但服务不可达的中间态恰好是 local-state 检查无法发现的。假设 4pool 耗尽时静默复用 known-bad active候选全灭时策略会静默选择 soft-avoided 的 active 账号fail-open把已知失败的账号重新送进请求路径失败 → 恢复 → 再失败的循环因此无法终止。四、诊断笔记如何从日志判断账号身份RCA 特别指出一个日志解读陷阱日志中的provider: openai在当前代码下大概率是 main 账号即未走 pool 的直连主登录而额外的 pool 账号会以openai-safe-label形式出现对应 routing.ts 的formatCodexProviderForLogmain 账号折叠为基础 provider 名pool 账号追加-safe-label后缀。这意味着排查 502 归属时必须先确认日志版本与账号标签规则否则会把 main 账号的故障误判为 pool 账号行为——RCA 原文中的日志即来自修复前版本不能直接作为修复后行为的证据。五、修复方向按 030 补丁单元落地RCA 给出了 6 条修复方向按优先级排列最高优先修正结果分类将consumeForInspection的 catch 分支从笼统的incomplete拆分为transport_failure/failed502让终端 recorder 把 mid-stream 中断记录为 transient 账号失败。必须严格区分 client cancel 与 upstream read error——客户端主动取消不该污染账号健康而上游读错误必须污染。per-account cooldown escalation30s → 2m → 10m → 30m5 分钟窗口内累积且只有连续正常终止 N 次后才允许完全恢复避免单次 2xx 直接洗白。新绑定前 lightweight probe仅对新账号 / 重新认证后 / 冷却回归的账号在正式绑定前做一次 backend 可达性确认。pool 耗尽策略显式化放弃静默复用 known-bad active改为显式返回 503/429 健康摘要或引入 half-open circuit-breaker。compact buffering 路径复查确保 compact.ts 的缓冲读取路径也不会把 mid-read reset 当成功处理。诊断字段补全新增 account label/hash、affinity 状态reused / new_bind / rebound / cleared、transport phasepre_headers / mid_stream / terminal_sse、terminal sourcereal / synthetic、选择理由与排除候选——让下一次 RCA 不再依赖人工猜日志。其中方向 2 与方向 1 的连续成功才恢复在 cooldown-math.ts 与 routing.ts 中已有对应实现可作为 030 补丁落地的参照基准。六、结语从客户端 502到路由侧 200的系统性教训#186 RCA 的价值在于揭示了一类隐蔽故障的共性代理网关的故障语义必须与客户端感知语义严格对齐。当 transport 层的中断SSE 截断、socket 关闭在统计层被翻译成成功 200任何账号级故障隔离soft-avoid、affinity 解除、streak 计数都会失效甚至被反向清除。本仓库后续的 escalation 阶梯、连续成功恢复、以及 relay 侧 failed-tail 与 incomplete-frame 的显式区分正是对这一缺陷的系统性回应。对于同样运行多账号 LLM 代理网关的开发者建议优先审计自身的终端 recorder是否把流中断和协议终止混为一谈是否让客户端取消污染了账号健康。赞分享【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址https://gitcode.com/gh_mirrors/ope/opencodex点击查看免费下载相关推荐OpenCodex 会话回滚根因剖析Codex App 重启后历史丢失的定位与非破坏性修复OpenCodex 会话回滚根因剖析Codex App 重启后历史丢失的定位与非破坏性修复 导读 本文基于 OpenCodexUniversal proviopencodex 中 ocx Agent 注册表在工作流执行后消失根因分析与修复实录RCAopencodex 中 ocx Agent 注册表在工作流执行后消失根因分析与修复实录RCA 导读 本文记录 opencodex 项目中一次真实的事故根因opencodex Web Search 侧车驻留超时Stall Timeout故障根因分析与修复方案opencodex Web Search 侧车驻留超时Stall Timeout故障根因分析与修复方案 opencodex 是面向 OpenAI Codex上一篇Diaporama高级教程自定义GLSL过渡效果实现独特视觉体验下一篇OpenCore Legacy Patcher架构解析老款Mac现代化改造的技术实现路径创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考