NewAPI-Gateway

一个面向 NewAPI 生态的透明聚合网关：单一 ag-token 接入多个上游供应商，支持智能路由、故障降级、使用统计和管理后台。

1. 项目定位

这是一个更偏 平台接入层 / 网关层 的项目，而不只是简单的 API 转发器。

它要解决的问题是：当业务需要同时接入多个上游 AI 服务提供商时，如何在调用方和上游之间增加一层 统一接入、可控路由、可观测、可扩展 的平台能力。

对调用方来说，它暴露的是一个统一入口； 对平台侧来说，它沉淀的是多供应商管理、策略路由、日志统计与运维能力。

2. 解决的问题

这个项目重点解决以下几个典型平台问题：

统一接入

• 调用方只使用一个统一网关地址
• 使用单一聚合令牌 ag-xxx
• 降低业务侧对多个上游服务的直接耦合

多供应商聚合

• 可以统一接入多个 NewAPI 供应商
• 管理不同供应商的 token、价格、余额与模型可用性
• 让多个供应商在平台侧被抽象成一组可调度资源

智能路由与降级

• 支持优先级分层
• 支持基于价值评分的候选排序
• 支持可选健康调节
• 当上游不可用时自动切换到下一条路由

透明代理

• 对上游隐藏网关存在
• 清洗代理特征 Header
• 将客户端聚合 token 替换为上游真实 token
• 尽量保持请求体与 User-Agent 透明传递

运维与可观测性

• 记录每次调用的模型、供应商、状态、耗时
• 支持使用统计
• 提供 Web 管理面板用于供应商、Token、日志和路由管理

3. 为什么我会一直想做这个项目

相比单纯写一个代理，我更想把它做成一个自己也愿意长期维护的平台接入层。这个项目吸引我的地方主要有：

• 接入层设计：统一入口、鉴权、转发、协议兼容
• 可靠性思维：优先级路由、失败降级、健康调节
• 平台抽象能力：把多个上游统一抽象为可管理资源池
• 运维意识：同步、签到、日志、统计、后台管理
• 演进空间：限流、审计、观测、告警、K8s 化

我一直想看看，一个看起来只是转发请求的网关，能不能慢慢长成一个可运行、可维护、可扩展的平台接入层。

4. 架构图

这张图表达的重点是：

• 网关并不是单纯转发流量，而是承担了 鉴权、路由、管理、统计 多层职责
• 数据面和管理面被放进了同一个可演进的平台系统里

5. 核心请求链路

6. 架构思路

根据项目文档，目前系统可以拆成几个主要组件：

• router/：负责注册 Relay API、管理 API、Web 路由
• middleware/：负责鉴权、限流、CORS、缓存等横切逻辑
• controller/：负责请求编排和参数校验
• service/：负责代理转发、同步、签到、路由重建等核心业务
• model/：负责数据库实体与核心查询逻辑
• web/：React 管理后台

核心请求链路

客户端
  -> /v1/*
  -> 聚合 Token 鉴权
  -> 解析请求模型
  -> 生成候选路由计划
  -> 代理转发到命中的上游供应商
  -> 返回流式/非流式响应
  -> 记录 usage log

这个链路的价值在于：

• 把调用入口标准化
• 把路由决策集中化
• 把日志和统计沉淀在平台层

7. 路由策略设计

这个项目最有亮点的地方之一，是它不是简单随机选上游，而是做了更像“平台调度”的路由设计。

候选筛选

在正式路由前，系统会先对模型名做统一目录归一，把 canonical / alias / 上游目标名尽量收敛到同一语义。

分层路由

候选路由会先按 优先级 分层，优先尝试更高优先级的候选。

价值评分

同一优先级层内，不是死板轮询，而是会结合：

• 模型价格
• 供应商余额
• 最近一段时间的使用成本

来计算一个更偏“性价比”的评分。

加权随机不放回

在同一层里，路由会结合人工权重和评分结果做加权排序，形成完整重试顺序；某条路线失败后，再尝试同层其他候选；同层全部失败后再降级到下一层。

可选健康调节

项目还预留了基于：

• 成功率
• 失败率
• 平均延迟

做健康倍率调节的能力，这点很像真实平台里的“动态路由”设计。

8. 稳定性与运维设计

从平台工程视角看，这个项目已经有不少“可运行系统”特征：

自动同步

系统会定时从上游同步：

• 模型定价
• Token 列表
• 用户余额

然后重建模型路由表，避免人工维护静态路由。

自动签到

对于需要每日签到的供应商，系统支持定时签到任务。

使用日志

调用日志会记录：

• 命中模型
• 命中供应商
• 耗时
• 状态
• 使用量相关信息

这使它具备继续向监控、审计、成本分析方向演进的基础。

管理后台

项目自带 Web 面板，用来管理：

• 供应商
• 聚合 Token
• 路由
• 日志
• 仪表盘信息

这使它不只是“代码能跑”，而是已经具备平台型产品的雏形。

9. 部署与交付方式

项目目前已经支持多种启动方式：

• Docker 镜像部署
• 预编译二进制启动
• 源码构建

这部分对我来说也很重要，因为我不太想让项目停在“本地能跑”这一步：

• 本地开发之外，交付路径也要清楚
• 部署方式最好从一开始就留有余地
• 文档和运行方式越统一，后面越容易继续打磨

如果从 DevOps / 平台工程方向继续增强，我会优先补这些内容：

1. Docker Compose 一键启动示例
2. 生产环境配置说明
3. 健康检查与日志采集建议
4. 反向代理 / TLS / 域名接入方案
5. 从 Compose 迁移到 Kubernetes 的部署思路

10. 这个项目让我更关注的几件事

做到这里以后，我会更自然地把注意力放在下面这些事情上：

系统抽象

能把多个离散上游抽象成统一的平台接入层。

工程化完整度

不仅写功能，也关注配置、鉴权、日志、管理面板和部署方式。

可靠性设计

在路由设计里引入优先级、评分、失败降级和健康调节，而不是只做“请求转发”。

运行视角

关心使用统计、同步任务、后台操作和系统长期运行问题。

11. 后续我还想继续完善的方向

这个项目后续我还会继续往更完整的平台系统方向补，例如：

• 补充系统架构图
• 补充路由算法流程图
• 补充日志与指标设计
• 接入 Prometheus / Grafana 观测方案
• 增加限流、审计、告警能力说明
• 补充 Docker Compose 与 Kubernetes 部署文档
• 增加故障演练和高可用设计说明

后面我也会继续把关键设计取舍、从代码到运行的演进路线，以及更贴近真实运维的问题整理进来。

12. 项目链接

• GitHub：https://github.com/xxbbzy/NewAPI-Gateway