lijiaoqiao/docs/open_source_gateway_codebase_deep_dive_v1_2026-03-17.md

开源网关代码深度理解（v1）

• 版本：v1.0
• 日期：2026-03-17
• 范围：sub2api-tar、new-api、one-api、litellm
• 目标：为“Subapi First + 自研 Router Core 接管”提供源码级认知基线。

1. 目录与迁移确认

当前开源仓库已位于统一项目根：

• /home/long/project/立交桥/llm-gateway-competitors

核心仓库路径：

1. /home/long/project/立交桥/llm-gateway-competitors/sub2api-tar
2. /home/long/project/立交桥/llm-gateway-competitors/new-api
3. /home/long/project/立交桥/llm-gateway-competitors/one-api
4. /home/long/project/立交桥/llm-gateway-competitors/litellm

2. 法务与商用风险快照

1. sub2api-tar：MIT（可商用，仍需遵守上游 ToS）
2. new-api：AGPLv3（对闭源商用有强约束）
3. one-api：MIT
4. litellm：仓库主体 MIT，enterprise/ 子目录有独立授权边界

结论：你的主线“商用闭源控制面”不应以 new-api 作为核心代码基座。

3. 架构入口（代码级）

3.1 sub2api-tar（推荐重点）

主入口与启动装配：

1. /backend/cmd/server/main.go（setup 模式 + 主服务启动）
2. /backend/internal/server/routes/gateway.go（协议路由汇总）

核心特点：

1. 明确的多协议入口：/v1、/v1beta、responses/chat 别名
2. 账号调度和 failover 逻辑深（适合借鉴路由中台能力）
3. 并发槽位、等待队列、流式错误处理比较完整

建议你优先深读：

1. /backend/internal/handler/openai_gateway_handler.go
2. /backend/internal/handler/gateway_handler.go
3. /backend/internal/handler/gemini_v1beta_handler.go
4. /backend/internal/service/openai_gateway_service.go
5. /backend/internal/service/gateway_service.go

3.2 new-api（功能广但法务受限）

主入口：

1. /main.go
2. /router/relay-router.go
3. /controller/relay.go

核心特点：

1. 协议覆盖广（OpenAI/Claude/Gemini/Responses/Realtime）
2. middleware.Distribute() + controller.Relay() 主干清晰
3. 计费预扣/结算逻辑完善，但 AGPL 影响商用策略

可借鉴点：

1. RelayFormat 分发模型
2. 路由组织和中间件链条设计

3.3 one-api（经典轻量基线）

主入口：

1. /main.go
2. /router/relay.go
3. /middleware/distributor.go

核心特点：

1. 架构简单，易读
2. 渠道选择以“可用通道 + 随机”为主，策略深度有限
3. 适合作为最小网关实现参考，不适合直接承载企业治理能力

3.4 litellm（生态和工程成熟度最高）

架构说明文件：

1. /ARCHITECTURE.md

关键目录：

1. /litellm（SDK 核心）
2. /proxy（AI Gateway）
3. /router.py + /router_strategy（路由策略）
4. /tests（测试资产非常完整）

核心特点：

1. SDK 与 Gateway 分层清晰
2. Proxy 在 SDK 上叠加 auth/rate-limit/budget/routing
3. 作为“多供应商适配能力参考”价值高

4. 代码体量画像（按文件后缀）

1. sub2api-tar：Go 1004，Vue 165，TS 139
2. new-api：Go 511，JSX 321
3. one-api：Go 235，JS 242
4. litellm：Python 3500，TSX 844，Markdown 869

解读：

1. sub2api 在 Go 侧中台能力深，适合做 S1/S2 接入基座。
2. litellm 在多 Provider 抽象和测试体系更强，适合策略与适配层借鉴。

5. 与你当前路线图的对齐建议

1. S1-S2 直接对齐 subapi connector：以 sub2api-tar 路由和 handler/service 为准做契约测试。
2. S2 国内供应商 100% 接管：优先把国内 Provider 的路由与计费从 subapi 迁出到自研 Router Core。
3. S3 机器人能力：优先消费你自研控制面的统一事件，不直接耦合 subapi 内部事件格式。

6. 下一轮深挖计划（v2）

建议按以下顺序继续深挖并输出第二版文档：

1. sub2api 调度链路时序图（选账号 -> 并发槽 -> failover -> usage 入账）
2. sub2api 计费链路字段表（请求级 idempotency 与 ledger 对齐）
3. litellm Router 策略可移植点（cost/latency/success 权重）
4. new-api/one-api 的可借鉴中间件清单（仅借鉴，不引入 AGPL 污染）

7. v2 文档已完成

已完成并落盘的 v2 深挖文档：

• /home/long/project/立交桥/docs/sub2api_scheduler_billing_flow_deep_dive_v2_2026-03-17.md

覆盖内容：

1. SelectAccountWithScheduler 三层调度策略与评分机制
2. 用户/账号并发槽位获取、等待队列与释放保障
3. Failover 触发条件、同账号重试、流式 no-replay 边界
4. submitUsageRecordTask -> UsageRecordWorkerPool -> RecordUsage -> applyUsageBilling 全链路
5. request_id + fingerprint 幂等扣费机制与冲突语义