Codex账号池管理调研报告

GitHub仓库地址:https://github.com/Soju06/codex-lb

一、项目定位与核心价值

codex-lb 是一个面向 ChatGPT 账号池的协议兼容型负载均衡网关，对外提供 OpenAI / Anthropic / Codex 三套主流大模型 API 协议，对内统一管理一组 ChatGPT Plus/Pro 账号，自动完成请求路由、配额追踪、令牌续期、故障切换等全套运维动作。

一句话价值：让任何使用 OpenAI/Claude/Codex 协议的客户端（Cursor、Codex CLI、Claude Code、OpenCode、各类 SDK）都能透明地复用一组 ChatGPT 订阅账号，把"个人订阅"用成"企业级 API 网关"。

典型使用场景：

• 团队/小组共享 ChatGPT Plus 订阅给开发工具使用

• 个人多账号轮换以突破单账号配额

• 公司内部统一收口对外大模型调用，便于审计与计费

• 替代官方 API 节约成本（订阅费 vs token 计费）

二、核心功能

2.1 多账号池负载均衡

• 账号注册：通过 OAuth 登录方式批量录入 ChatGPT 账号（支持 Plus / Pro / Business / Enterprise / Edu 五个套餐等级）

• 智能路由：根据账号配额剩余、健康状态、套餐等级、限流情况自动选择最合适的账号承载本次请求

• 失败转移：单账号请求失败/限流后自动切换到下一个可用账号重试，对客户端透明

• 健康巡检：实时统计每个账号的成功率、错误码分布、最近一次失败时间，不健康账号自动从池中摘除

2.2 三协议兼容（核心卖点）

• 同一组账号同时对外暴露三种协议，客户端只需改 BASE_URL 即可接入

• 流式（SSE）/ 非流式两种返回模式都已对齐

• 兼容图片输入、工具调用（function calling）、推理过程（thinking/reasoning）等高级特性

2.3 自动令牌续期

• 账号 OAuth access_token 有 8 天默认续期周期，到期前自动调用 https://auth.openai.com/oauth/token 刷新

• 并发请求场景下用 singleflight 去重模式，避免同一账号被并发刷新 N 次

• 续期失败自动告警并将账号标记为不健康，等待人工介入

• 令牌全部使用 Fernet 对称加密存储，数据库泄露不直接等于账号泄露

2.4 用量追踪（Usage Tracking）

• 每一次请求都落盘 请求日志 与 使用量记录（input_tokens / output_tokens / cache_read / cache_creation 全维度）

• 后台定时任务（默认 60 秒一轮）拉取上游官方接口 /wham/usage，把"账号侧真实账单"与"代理侧推算用量"做核对

• Dashboard 实时展示每账号 / 每 API Key / 每天的用量曲线

• 支持按"接口类型 / 请求种类 / 账号 / API Key"四维度过滤分析

2.5 API Key 管理（对客户端的接入凭证）

• 每个客户端使用一把独立的 API Key（sk-clb-…），与底层 ChatGPT 账号完全解耦

• 每把 Key 可单独配置：

• 配额上限（按 token、按请求次数、按时间窗口）

• 可用账号子集（绑定到指定账号或账号组）

• 过期时间 / 启用-停用开关

• 支持 预扣（reservation）机制：流式请求开始时先预占用量，结束后结算，避免长流式请求超限被打穿

• Key 一旦泄露可秒级吊销，不影响其他客户端

2.6 Dashboard 管理后台

• React + TypeScript 单页应用，提供完整的可视化运维：

• 账号列表 / 新增账号 / OAuth 引导

• API Key 增删改查、配额配置

• 实时请求日志（含 SSE 详情、请求/响应体回放）

• 使用量大盘、TOP 用户、错误码分布

• 系统配置、IP 防火墙、审计日志、Sticky Session 管理

• Codex Session 重打标签、对话归档查看

• 三种登录模式可选（详见周边功能 §3.5）

三、周边功能（运维 & 安全相关）

3.1 IP 防火墙白名单

• Dashboard 可视化配置 API Firewall Allowlist：只有白名单内 IP（CIDR 段）可以调用 /v1/... 业务接口

• 命中规则会落审计日志，便于事后追溯

• 默认允许全部，开启后立刻收口，适合公司内网环境

3.2 多副本 / 高可用部署

• 支持多副本部署（Helm chart 直接 replicas: N）

• 内置 数据库选主（leader election），定时任务（usage 刷新、limit warmup）只在 leader 副本执行，避免重复

• HTTP Bridge 环（Bridge Ring）：副本间共享上游长连接归属，避免一个 sticky 会话跨副本时连接漂移

• 滚动升级零停机

3.3 配额预热（Limit Warmup）

• 后台主动给每个账号发探测请求，提前感知到接近限流的账号

• 不等到真实用户请求被拒才发现限流，直接在路由阶段绕开

• 对长尾用户体验稳定性提升明显

3.4 Sticky Session（粘性会话）

• 同一会话（Codex CLI 的 thread / OpenAI 的 prompt cache / 自定义 sticky）始终路由到同一账号

• 三种 kind：codex_session / sticky_thread / prompt_cache

• 显著提升 prompt cache 命中率（多轮对话省 token）

• 支持手动按 kind 批量清理过期会话

3.5 Dashboard 三种鉴权模式

• 首次部署 Bootstrap Token：第一次启动会生成一次性 token 并写入日志，管理员凭此 token 设置初始管理员密码，避免默认密码风险

3.6 审计日志（Audit Log）

• 所有"管理动作"（新增/删除账号、调整配额、修改 API Key、修改防火墙、登录登出等）落审计表

• Dashboard 可检索、可导出 CSV

• 满足内部合规与责任追溯需求

3.7 上游 HTTP 代理路由（Outbound Proxy）

• 支持给账号绑定出站 HTTP 代理池（多个代理端点 + 轮询/故障切换策略）

• 不同账号可走不同的出站代理 IP（应对 ChatGPT 风控/区域限制）

• 代理池支持启用/禁用、健康巡检

3.8 限流与封禁

• API Key 速率限制（attempt 表实现滑窗）

• 登录失败计数（防爆破）

• 账号自动隔离：连续 N 次失败、HTTP 401/403、配额耗尽等情况自动从路由池剔除并告警

3.9 数据库与备份

• 默认 SQLite（开箱即用、单文件、零依赖），路径见 .local/data/

• 可选 PostgreSQL（生产环境推荐，更好并发性能与备份生态）

• Alembic 管理 schema 版本，升级自动迁移

• 共 24 张表：账号、用量、请求日志、API Key 体系、限流、审计、Sticky Session、HTTP Bridge、代理池等

3.10 客户端兼容增强

• Anthropic thinking 字段宽容解析：兼容 Claude Code CLI 等客户端发送的非标准 thinking.type 值（empty / interleaved / extended 等）

• Codex Session 重打标签 CLI：可批量给历史 sticky 会话改 kind 标签，便于运维调整路由策略

• 对话归档（Conversation Archive）：完整保存请求/响应体，方便复现 bug 与训练数据沉淀

• 统一错误信封：上游错误自动翻译成对应协议的错误格式（OpenAI / Anthropic 各自的错误结构）

四、部署方式（开箱即用）

• Helm 默认提供 PVC、Ingress、Probe、PodDisruptionBudget 模板

• 配置全部走环境变量（12-Factor 风格），无需改代码

五、典型客户端接入示例

六、与同类产品对比的优势

七、风险与注意事项

1. 合规风险：复用 ChatGPT 个人订阅账号给团队/对外服务，可能违反 OpenAI 服务条款，建议在合规部门评估后小范围试点

2. 账号封禁风险：高频/异常使用会触发风控，需配合代理池、Sticky Session、限流等机制平滑使用

3. 依赖上游：OpenAI 一旦修改鉴权流程或反作弊策略，需要跟进升级

4. 首次部署门槛：OAuth 录入账号需要本人在浏览器走一次授权，无法完全无人值守

5. 数据安全：所有账号 access_token 已加密落库，但仍建议数据库本身加密存储 + 备份隔离

八、推荐使用建议

• 个人/小团队：直接 uvx codex-lb 单机跑，SQLite + standard 鉴权够用

• 公司内部网关：Helm 多副本 + PostgreSQL + trusted_header 模式（内网网关注入用户头）+ IP 防火墙

• AI 工具厂商集成：API Key 维度做租户隔离，配额预扣 + 审计日志支撑计费与对账

九、总结

codex-lb 把"一组个人 ChatGPT 订阅"包装成了一个企业级、可观测、高可用、协议齐全的大模型 API 网关。核心负载均衡能力之上，配套了完整的账号生命周期管理（OAuth/续期/封禁）、多协议兼容、精细化配额与计费、安全加固（防火墙/审计/TOTP）、生产级部署形态（Helm/多副本/选主）——属于个人能力延伸到团队/产品场景的"上限托底"型工具。