企业官网建设流程全解析

导读

本文基于 opencodex 仓库 dev 树的实测 RCA 记录（006_rca_s_sticky_502.md，issue #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 原文也做了标注）：

1. 用户最初提供的复现日志基于v2.7.28（修复未包含）版本，只能作为症状的定性佐证；
2. 后续"修复版本中 2/5 会话仍复现"的口头报告，在 RCA 调查时点需要通过 GitHub API 二次确认，尚未定论——残留结论主要由下述代码级缺陷推得，而非依赖该后续报告。

这种"日志版本滞后 + 代码缺陷支撑"的组合，决定了本次 RCA 的产出是修复方向清单而非单纯的版本回归结论。

二、现状亲和性策略地图（Affinity Policy Map）

RCA 首先测绘了当前账号选择与故障隔离的完整策略面。结合当前仓库源码，可将其归纳为四个维度（行号为当前 dev 树实测量）：

1. 会话亲和性（Affinity）：全局 threadAccountMap

• 全局映射threadAccountMap（threadId → accountId），保证同一会话（thread）连续轮次尽量落在同一账号，以复用 Codex 的 prompt-cache 前缀；
• 空闲 TTL 24h、最大条目 2048，相关常量定义在 thread-affinity.ts（CODEX_THREAD_AFFINITY_IDLE_TTL_MS、CODEX_THREAD_AFFINITY_MAX_ENTRIES）。

2. 上游健康（upstreamHealth）：账户级 soft-avoid

• 健康状态按账号全局记录（upstreamHealth[accountId]），而非按会话；
• transient 失败（connect_error / timeout / 5xx）的 soft-avoid 窗口固定为 30s；
• failure streak 计数窗口为 5 分钟（CODEX_FAILURE_WINDOW_MS = 5 * 60_000，见 cooldown-math.ts）；
• failover 阈值默认 3 次（config.upstreamFailoverThreshold ?? 3，见 routing.ts）。

3. 选择排除与解除规则

• 被排除的候选：hard cooldown（429 触发的强制冷却）、soft-avoid（transient 触发）、needsReauth（401/403 触发）；
• 当绑定会话的账号进入 avoid / 达到阈值时，解除该 thread 的亲和性并重新选择；
• connect_error/timeout/5xx 记录时立即删除该 thread 的 affinity；达到 failover 阈值时删除该账号的全部affinity；
• 401/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 的核心发现，机制链如下：

1. 头部（headers）之前的 fetch 拒绝会被正常记录为connect_error/timeout，这是正确的；
2. 200 之后 SSE 流中途断开时，客户端 tee 会生成合成事件response.failed/upstream_reset；
3. 但记录 routing outcome 的 inspection 分支在read throw 时统一上报为incomplete；
4. 终端 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/failed+502，而不是笼统的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 检查无法发现的。

假设 4：pool 耗尽时静默复用 known-bad active

候选全灭时策略会静默选择 soft-avoided 的 active 账号（fail-open），把已知失败的账号重新送进请求路径，失败 → 恢复 → 再失败的循环因此无法终止。

四、诊断笔记：如何从日志判断账号身份

RCA 特别指出一个日志解读陷阱：日志中的"provider": "openai"在当前代码下大概率是 main 账号（即未走 pool 的直连主登录），而额外的 pool 账号会以openai-<safe-label>形式出现（对应 routing.ts 的formatCodexProviderForLog：main 账号折叠为基础 provider 名，pool 账号追加-<safe-label>后缀）。

这意味着排查 502 归属时，必须先确认日志版本与账号标签规则，否则会把 main 账号的故障误判为 pool 账号行为——RCA 原文中的日志即来自修复前版本，不能直接作为修复后行为的证据。

五、修复方向（按 030 补丁单元落地）

RCA 给出了 6 条修复方向，按优先级排列：

1. （最高优先）修正结果分类：将consumeForInspection的 catch 分支从笼统的incomplete拆分为transport_failure/failed+502，让终端 recorder 把 mid-stream 中断记录为 transient 账号失败。必须严格区分 client cancel 与 upstream read error——客户端主动取消不该污染账号健康，而上游读错误必须污染。
2. per-account cooldown escalation：30s → 2m → 10m → 30m（5 分钟窗口内累积），且只有连续正常终止 N 次后才允许完全恢复（避免单次 2xx 直接洗白）。
3. 新绑定前 lightweight probe：仅对"新账号 / 重新认证后 / 冷却回归"的账号，在正式绑定前做一次 backend 可达性确认。
4. pool 耗尽策略显式化：放弃静默复用 known-bad active，改为显式返回 503/429 + 健康摘要，或引入 half-open circuit-breaker。
5. compact buffering 路径复查：确保 compact.ts 的缓冲读取路径也不会把 mid-read reset 当成功处理。
6. 诊断字段补全：新增 account label/hash、affinity 状态（reused / new_bind / rebound / cleared）、transport phase（pre_headers / mid_stream / terminal_sse）、terminal source（real / 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：是否把"流中断"和"协议终止"混为一谈，是否让客户端取消污染了账号健康。