很多团队做 AI 产品，第一阶段都很顺利：
- 调通一个模型；
- 写几个 API；
- 跑出一个 demo。
但到了第二阶段，问题会集中爆发：
- 客户要稳定，单一上游不稳定；
- 成本要可控，调用量上来后账就乱了；
- 用户要分层，个人、团队、管理员权限都不一样；
- 运营要可视，出了问题要知道是谁、哪个 key、哪个渠道、哪个模型；
- 商业要闭环，充值、订阅、额度、结算要打通。
这时你会发现，真正难的不是“会调模型”，而是“把模型能力做成一个能长期运营的系统”。
我这几天把 new-api 关键代码路径完整过了一遍，结论是：它的价值不在于“支持 40+ 上游”这句话本身，而在于它把 AI 网关最难的工程问题做成了一整套闭环。
这篇文章我不做功能清单，而是按“工程决策”的视角，讲我为什么推荐它。
典型请求链路
客户端
↓
/v1/chat/completions 或 /v1/messages
↓
认证 TokenAuth / UserAuth
↓
限流 ModelRequestRateLimit
↓
分发 Distribute
↓
Relay 进行请求校验、token 估算、预扣费
↓
Adaptor 转换上游格式并请求 provider
↓
DoResponse 解析 usage 与流式结果
↓
Settle / Refund 完成结算或退款
先说结论：new-api 适合什么团队？
如果你符合下面两条以上，我建议认真评估 new-api：
- 你不是做一次性 demo，而是要长期运营 AI 服务；
- 你已经或即将接入多个模型提供商；
- 你需要用户体系、令牌体系、额度体系；
- 你需要计费可解释、可审计、可对账；
- 你希望业务团队只写业务，不反复改模型适配代码。
一句话：new-api 更像“AI 能力运营底座”，不是“API 转发脚本”。
关键模块速览
| 模块 | 作用 | 读代码时最值得关注的地方 |
|---|---|---|
router/ | 注册 HTTP 路由 | 看不同 API 如何被分到 Relay、管理后台、支付和订阅 |
middleware/ | 认证、限流、分发、性能保护 | 这里决定请求是否进入业务主流程 |
controller/ | HTTP 入口层 | 负责把“请求”变成“业务动作” |
service/ | 计费、选择、结算、任务 | 核心业务逻辑基本都落在这里 |
model/ | 数据模型与 DB 访问 | 用户、Token、Channel、Subscription 都在这里收口 |
relay/ | 上游适配器层 | 决定如何和 OpenAI、Claude、Gemini 等 provider 对话 |
一、我如何理解它的架构：分层清晰，但核心复杂度集中在中继闭环
从目录结构看，它是标准分层：
- 路由层：
router/ - 控制器层：
controller/ - 服务层：
service/ - 模型层：
model/ - 中继适配层：
relay/
这个结构不新鲜，但 new-api 做对的一点是：把复杂度集中在中继闭环中，而不是让复杂度溢出到业务端。
关键入口我看的是这几处：
- 启动与后台任务：
main.go - 管理 API：
router/api-router.go - Relay API：
router/relay-router.go - 分发中间件：
middleware/distributor.go - 中继主流程：
controller/relay.go - 通道重试：
service/channel_select.go - 计费会话：
service/billing_session.go
在 main.go 里能看到它不是“起个 HTTP 服务就完了”，还挂载了多种后台任务：
- 自动测试渠道；
- 渠道上游模型更新检测；
- 订阅额度重置任务；
- 凭证刷新任务（例如某些 OAuth 型渠道）；
- 可选性能观测、缓存同步等。
这说明它天然按“在线系统”而不是“代码示例”来设计。
二、它最关键的价值：把多模型调用从“请求转发”提升为“策略执行”
很多人理解网关，会停在“把请求发出去，再把响应拿回来”。
但在 new-api 里，请求进入系统后会经历一条治理链路（以 /v1/chat/completions 为例）：
- 认证：
TokenAuth或用户态认证； - 模型级限流：
ModelRequestRateLimit； - 分发：
Distribute解析 model/group 并选通道； - 中继：
Relay做请求校验、估算、预扣费、上游调用； - 异常处理：失败重试、降级切换、可选惩罚；
- 结算：按真实 usage 做 delta 结算或退款。
对应代码路径：
- 路由：
router/relay-router.go - 分发：
middleware/distributor.go - 执行：
controller/relay.go
这条链路的核心思想是：
- 调用成功率不是靠运气，是靠策略。
- 成本正确性不是靠离线修账，是靠在线预扣+结算。
这就是我说它“可运营”的根本原因。
三、通道选择机制是实战导向，不是玩具随机
我专门看了 service/channel_select.go + middleware/distributor.go，它的路由策略值得单独说。
1）优先级 + 权重随机
不是全局随机，而是：
- 先按优先级层选候选集；
- 同优先级内按权重做随机。
这样可以实现“主渠道优先，备渠道兜底”，并且避免单点雪崩。
2）重试不是简单重复，而是“有状态降级”
中继失败后，它会结合重试次数切换优先级层，必要时换组。
这和“retry N 次同一个上游”完全是两个层级的稳定性设计。
3）auto 分组与跨组重试
TokenGroup == auto 时，会遍历可用组：
- 当前组优先级耗尽后切到下一组；
- 切组时重置优先级计数；
- 上下文里记录当前 autoGroupIndex。
这是面对“渠道池异构+波动”时非常实用的策略。
4）通道亲和性
Distribute 还做了会话级亲和性：
- 如果近期某模型在某组有稳定成功通道，优先复用；
- 请求成功后记录亲和性；
- 失败或通道不可用再回退到随机选择。
这对降低抖动、提高用户体感一致性很有效。
四、真正让我愿意推荐的点：计费系统是“系统工程”，不是“字段加减”
AI 网关最容易被低估的部分是计费。很多项目最后都死在“账对不上”。
new-api 在这块做得非常完整。
1）预扣费与退款逻辑是先验正确的
看 service/pre_consume_quota.go：
- 请求前先检查用户额度；
- 按预估成本预扣（钱包/令牌）；
- 调用失败时返还；
- 支持 trustQuota 旁路（额度足够时减少小额高频扣费开销）。
这不是“业务功能”，而是“财务一致性机制”。
2）BillingSession 把账务生命周期统一了
看 service/billing_session.go，它把一次请求的资金行为封装成会话：
PreConsume：预扣；Reserve：流式过程中补扣；Settle：按实际消耗做 delta 结算；Refund：失败回滚，幂等安全。
这套机制的意义是：把“应该扣多少”变成可计算、可回滚、可追踪的状态机。
3）表达式计费：把复杂定价从代码里抽离出来
pkg/billingexpr/expr.md 这份文档非常关键，设计理念我很认同：
- 一个表达式即计费真相（One expression, one truth）；
- 变量体系覆盖 prompt/completion/cache/image/audio；
- 支持 tier（阶梯定价）、header/param 条件；
- 通过 AST introspection 自动处理
p/c子项排除，避免重复计费。
这意味着运营侧可以迭代定价策略，而不是每次都发版改代码。
这对商业化产品非常重要。
五、认证与权限模型不花哨，但很务实
从 router/api-router.go + middleware/auth.go 看，它做了清晰权限分层：
UserAuth：普通用户操作；AdminAuth：运营管理能力；RootAuth：高风险系统配置。
同时，用户登录面也比较完整：
- 注册/登录/重置密码；
- 2FA；
- Passkey/WebAuthn；
- OAuth（含自定义 provider）。
这意味着你可以把它直接作为“面向最终用户”的平台后端，而不是只能给内部工程师用。
认证能力矩阵
| 能力 | 普通用户 | 管理员 | Root |
|---|---|---|---|
| 用户登录 / 注册 | 是 | 是 | 是 |
| API Token 管理 | 是 | 是 | 是 |
| 用户管理 | 否 | 是 | 是 |
| 渠道管理 | 否 | 是 | 是 |
| 支付配置 | 否 | 否 | 是 |
| 系统设置 | 否 | 否 | 是 |
| 订阅计划管理 | 否 | 是 | 是 |
六、管理员视角：new-api 不是“能配渠道”，而是“能做运营”
我看完管理路由后的直接感受是：它的设计是按运营岗位需求来的。
管理员典型工作流可以这样跑：
- 新增渠道，配置模型映射与分组；
- 批量测试渠道可用性，更新余额；
- 检测上游模型变化并应用同步；
- 观察日志与消耗分布，做权重/优先级调优；
- 配置充值、订阅、额度分配；
- 处理异常用户与风险 key。
这在 API 路由里都有对应接口，而不是停留在文档口号。
用户、管理员、运维三视角
| 视角 | 关心什么 | 在 new-api 里看什么 |
|---|---|---|
| 用户 | 模型能不能稳定调用、额度够不够、Key 是否可用 | Token、额度、订阅、模型列表、用量日志 |
| 管理员 | 渠道是否健康、模型是否映射正确、价格和权重是否合理 | Channel、Ability、Pricing、订阅计划、用户管理 |
| 运维 | 故障能否快速定位、系统是否过载、缓存和性能是否正常 | 日志、性能指标、通道亲和性缓存、渠道测试、后台任务 |
七、用户视角：从注册到调用的路径是闭环的
普通用户路径在代码里也很清楚：
- 注册/登录；
- 创建或获取 API token；
- 充值或订阅拿额度；
- 按 OpenAI 兼容 API 调用模型；
- 在日志/面板查看消耗与结果。
对产品团队来说，这条链路完整意味着你可以更快验证“从流量到收入”的闭环。
普通用户流程图
注册 / 登录
↓
创建 Token
↓
选择模型或使用 auto group
↓
按需充值 / 购买订阅
↓
用 OpenAI 兼容接口发请求
↓
查看日志、额度和消耗
八、我认为它在工程上做得好的 5 个决策
决策 1：中间件前置治理
限流、鉴权、分发不挤在业务 handler 里，降低心智负担。
决策 2：适配器模式隔离上游差异
relay/channel/* 各 provider 适配器独立，新增渠道不破坏主流程。
决策 3：重试与路由策略解耦
RetryParam + 通道选择服务让降级逻辑可维护。
决策 4：账务会话化
BillingSession 把扣费问题从“散落函数”变成“有状态对象”。
决策 5：文档与代码一致性较高
docs/architecture.md、docs/api-reference.md、pkg/billingexpr/expr.md 对理解源码非常有帮助。
关键接口一览
| 场景 | 代表接口 | 说明 |
|---|---|---|
| 用户登录 | POST /api/user/login | 账号密码登录 |
| 用户注册 | POST /api/user/register | 注册账号并可生成默认 token |
| Token 列表 | GET /api/token/ | 查看自己的 token |
| 创建 Token | POST /api/token/ | 新建访问令牌 |
| 渠道列表 | GET /api/channel/ | 管理员查看渠道 |
| 测试渠道 | GET /api/channel/test/:id | 验证上游可用性 |
| 订阅计划 | GET /api/subscription/plans | 用户查看可购买计划 |
| 订阅购买 | POST /api/subscription/stripe/pay | 触发支付流程 |
| 充值 | POST /api/user/topup | 用户充值额度 |
| 统一中继 | POST /v1/chat/completions | OpenAI 兼容主入口 |
| Claude 路由 | POST /v1/messages | Claude 兼容入口 |
| Gemini 路由 | POST /v1beta/models/*path | Gemini 兼容入口 |
九、上线时你要注意的现实问题（我给的实践建议）
推荐归推荐，落地时还是要规避几个坑。
1）先别一上来就全渠道
建议先 2~3 个主渠道跑稳定，再逐步扩池。否则排障复杂度会指数上升。
2）先把“观测”建好
至少要能按 用户/令牌/模型/渠道/状态码 维度查日志。
3）计费表达式先做“简单可解释版”
第一版先做基础费率 + 1~2 个阶梯，不要一次上太复杂规则。
4）重试策略要和业务 SLA 对齐
高实时业务不一定适合太多重试层，宁可快速失败再重发。
5）权限边界要明确
RootAuth 能改系统关键配置，生产环境必须收口操作权限。
建议的上线节奏
| 阶段 | 目标 | 重点动作 |
|---|---|---|
| 第 1 阶段 | 先跑通链路 | 只接 2~3 个主渠道，验证鉴权、分发和结算 |
| 第 2 阶段 | 建立可观测性 | 补齐日志、状态码、渠道健康、用量统计 |
| 第 3 阶段 | 做成本优化 | 启用亲和性、权重、优先级、auto group |
| 第 4 阶段 | 商业闭环 | 打通充值、订阅、优惠、额度分配 |
| 第 5 阶段 | 规模化运营 | 做告警、缓存、批量同步和策略调优 |
十、适用与不适用边界
适用
- 多模型聚合平台；
- ToB AI 中台；
- 有明确商业化目标（计费、订阅、充值）；
- 需要长期可运营能力。
可能不适用
- 只做个人脚本，单模型、低调用量；
- 不需要账号体系和额度管理；
- 对运维治理完全无要求。
如果你只是写个个人代理，new-api 可能“过重”； 如果你要做产品平台，它反而“刚好”。
结语：我为什么愿意推荐它
我推荐 new-api，不是因为它“功能多”，而是因为它在最难的地方做了正确工程化：
- 把多模型接入做成了策略路由；
- 把计费做成了可结算、可回滚、可扩展的系统；
- 把用户/管理员场景都放进同一个产品闭环。
对准备认真做 AI 产品的团队来说， 从“能调用模型”到“能运营业务”，中间那段最难的路，new-api 基本帮你铺好了。
如果你现在正处在“demo 之后、平台之前”的阶段，这个项目值得你深挖并投入。