new-api 源码拆解：学习路径与模块地图

new-api 是目前最流行的开源大模型网关之一（Go + React，one-api 的增强版）：一个网关身后挂几十个上游渠道，对外暴露统一的 OpenAI/Claude/Gemini 兼容接口，内部完成鉴权、选路、协议转换、计费与审计。读懂它，就读懂了”LLM 网关”这类产品的全部核心命题。

本专栏的学习路径按请求的流动顺序设计：一个 sk-xxx 请求从进门到返回，会依次经过鉴权 → 选路 → 转换 → 计费 → 记录，每个环节对应一个功能模块、一篇源码拆解。

你会学到什么

• 网关架构：多租户 API 服务如何分层（接入/路由/中间件/服务/中继/模型层），gin + gorm + Redis 的经典组合如何在 10 万行规模上保持清晰；
• 协议转换：OpenAI ↔ Claude ↔ Gemini 四协议两两互转的适配器架构，以及新增一个上游提供方的完整清单；
• 流量治理：优先级分档 + 加权随机的负载均衡、失败重试与渠道自动禁用；
• 商业化内核：倍率计费公式、预扣费-结算-退款三段式、批量落库——把”按 token 收费”做对的全部细节；
• 性能工程：三级缓存（渠道/用户/令牌）、Redis Lua 原子操作、突变 fence 防脏写、批量更新。

模块地图与目录

阶段一 · 全局视角（先建立地图）

#	篇章	核心问题
2	架构总览与请求生命周期	一个 sk-xxx 请求从进门到返回经历了什么？
3	鉴权体系：令牌、会话与三层凭据	sk-xxx 和控制台登录是两套体系吗？多协议 key 怎么兼容？

阶段二 · 组织与路由（流量往哪去）

#	篇章	核心问题
4	用户、分组与权限	分组如何同时决定权限、选路和价格？
5	渠道管理与 model_mapping	几十个上游渠道怎么配置、测试、映射模型？
6	relay 中继核心：适配器与协议互转	OpenAI 格式的请求怎么变成 Claude 渠道的请求？
7	负载均衡与失败重试	优先级分档 + 加权随机 + 自动禁用如何协作？

阶段三 · 商业化内核（钱怎么算）

#	篇章	核心问题
8	计费与倍率	预扣费 → 结算 → 退款的三段式，倍率公式长什么样？
12	token 估算器	上游没响应就要扣费——字符级状态机怎么猜对 token 数？

阶段四 · 运行质量（怎么撑住规模）

#	篇章	核心问题
9	日志与可观测性	每一笔消费如何留痕？性能问题如何定位？
10	缓存与性能工程	三级缓存 + Lua 原子操作 + 批量落库如何扛住并发？
11	插件系统与部署	JS 插件怎么在 Go 里安全运行？多机怎么部署？

新手术语表（全专栏通用）

术语	大白话解释
LLM 网关	站在你和众多 AI 服务商之间的”中间商”：统一接口、鉴权、记账、选路
渠道（Channel）	一个上游 AI 服务的接入配置：密钥 + 模型列表 + 优先级
令牌（Token，sk-xxx）	发给你用户的”门禁卡”：带额度、分组、可用模型限制
中继（Relay）	网关的核心动作——收到请求、翻译格式、转发上游、转回响应
适配器（Adaptor）	每个上游品牌的”翻译官”，实现统一的接口规范
倍率（Ratio）	价格乘数：模型贵不贵 × 用户打几折
配额（Quota）	内部货币，1 美元 = 500000，消费与充值都按它记账
预扣费	请求前先冻结一笔钱防欠费，结算后多退少补
负载均衡	多个上游时决定”这次给谁”：优先级分档 + 按权重随机
熔断	上游持续出错自动下线，好了再恢复
分组（Group）	一个字段管三件事：能用什么渠道、走哪条路、按什么价格
SSE	AI 回复”打字机效果”的技术，网关必须原样支持

前置课程

• 读本专栏需要 Go 语言基础（gin/gorm/Redis 的工程用法）与基本的 SQL 常识；Go 系统化前置课在筹备中；
• 建议先读「Agent 工程」专栏第 2 篇（什么是 agent），理解网关服务的对象；
• TS 方向的读者请移步「TypeScript 与 Node 地基」。

学习方法建议

1. 顺着请求流读：目录顺序就是一次请求的经过顺序，按编号读不会迷路；
2. 每篇都有”动手环节”：本专栏的学习材料就是这个仓库本身——clone 下来 docker compose up 起一个实例，边读边在管理台里验证源码行为；
3. 带着对比读：读过 Agent 工程专栏的读者会注意到，网关与 agent harness 是一对镜像问题——网关对上游做协议归一，agent 对模型做能力扩展；两者的计费、限流、审计设计互为参照。