当一个团队同时使用 OpenAI、Claude、Gemini、DeepSeek、通义千问、智谱、火山引擎或本地模型时，接入难点很快就从“怎么调用一个 API”变成“如何统一管理几十个渠道”。不同供应商的鉴权、协议、模型名、限流与计费口径并不一致；业务代码若直接绑定每一家上游，切换模型、容灾和核算成本都会越来越复杂。
New API 正是为这类场景设计的开源大模型网关与 AI 资产管理系统。它在客户端和上游模型服务之间增加一个统一入口，集中处理渠道、模型、路由、协议转换、令牌、用户分组、额度、日志与成本统计。应用通常只需保存一套网关地址和访问令牌，模型选择与上游变化则由管理端控制。
截至 2026 年 8 月 13 日，GitHub API 快照显示该项目约有 4.5 万个 Star、1.06 万个 Fork，许可证为 GNU AGPL v3.0；当时最新 GitHub Release 是 2026 年 8 月 7 日发布的 v1.0.0-rc.24。这些数字代表社区关注度和特定时间点的项目状态，不等于安全审计、稳定性承诺或商业支持。
New API 是什么？
从定位上看，New API 不是模型，也不是聊天客户端，而是一层可私有部署的 AI API 网关。管理员把合法取得的上游凭据配置成“渠道”，再为模型设置可用范围、优先级、权重、价格和分组。用户或内部应用使用 New API 签发的令牌调用统一地址，网关完成鉴权、选择渠道、转发请求、记录用量并扣减额度。
它源自 One API 生态，并明确强调数据库兼容性。现在的 New API 已不只是简单的 OpenAI 兼容转发：项目加入了现代化管理界面、多语言、数据看板、细粒度权限、缓存计费、订阅与额度管理，以及对 Claude Messages、Google Gemini、OpenAI Responses、Realtime、Rerank、图像、音频和视频任务等接口的适配。
最典型的使用者包括需要统一模型出口的研发团队、为多个业务分配额度的平台团队、管理多家合法上游渠道的服务方，以及希望在实验环境中比较模型成本与可用性的个人开发者。如果只有一个应用、一个供应商和一把 Key，直接连接官方 API 往往更简单；网关的价值会随着渠道、用户、模型和治理要求增加而上升。
它解决了哪些问题？
统一客户端接入
New API 可以暴露 OpenAI 兼容接口，让支持自定义 Base URL 的 SDK、AI 客户端和内部服务复用一套接入方式。业务方不必保存每个上游的密钥，也不必在代码中实现所有供应商的签名逻辑。管理员更换渠道或调整路由时，客户端地址通常无需改变。
“兼容”并不表示所有协议完全等价。工具调用、结构化输出、图片输入、思考内容、流式事件、错误码和 Token 统计都可能存在供应商差异。New API 提供协议转换和参数适配，但在生产使用前仍要针对实际模型和接口做回归测试，尤其不能只用一条纯文本对话判断兼容性。
集中管理渠道与模型
一个渠道包含上游类型、Base URL、凭据、可用模型、分组、优先级、权重及其他专属设置。项目源码列出的渠道类型覆盖 OpenAI、Azure、Anthropic、Gemini、Vertex AI、AWS、DeepSeek、通义千问、智谱、腾讯混元、火山引擎、硅基流动、OpenRouter、Ollama、Mistral、Cohere、Jina、xAI 等，也包含 Midjourney、Suno、可灵、即梦、Vidu、Sora 与 Replicate 等异步任务渠道。
管理员可以把多个渠道映射到同一个对外模型名。例如客户端始终请求一个固定模型，网关按配置选择不同上游；也可以通过模型映射把外部名称转换为上游实际名称。这样有利于升级和迁移，但要注意不同模型即使名称相似，能力、上下文长度、价格和内容策略也可能不同。
路由、重试与故障隔离
当同一分组和模型存在多个可用渠道时，New API 会结合优先级与权重选路。项目支持渠道加权随机、失败自动重试、渠道测试、模型更新和用户级模型限流。合理设置后，可以把主渠道故障对应用的影响降到较低程度，也能在多个授权渠道之间分摊流量。
重试并不是越多越好。非幂等任务可能重复创建图片、视频或其他计费任务；超长重试链会放大延迟和成本；跨供应商重放还会改变数据接收方。生产环境应按接口类型设置超时和重试上限，记录最终命中的渠道，并对异步任务使用可追踪的业务幂等键。
用户、令牌、分组与额度
New API 把上游 Key 与下游访问令牌隔离。管理员可以创建用户和令牌，限制令牌可调用的模型、额度、过期时间和 IP 范围，并通过分组设置不同的模型倍率与渠道范围。这样，团队无需把高权限上游密钥分发到每台开发机或每个应用容器。
系统还提供充值、兑换码、订阅和额度分配能力，并支持易支付、Stripe 等相关配置。对于组织内部，这些能力可用于成本中心、项目预算或授权客户的用量管理。若面向公众收费，则不仅是技术部署问题，还涉及支付、税务、消费者权益、模型服务条款、实名、内容安全和所在地监管要求。
支持哪些 API 与模型能力？
项目当前重点覆盖以下接口形态：
- OpenAI Compatible：Chat Completions、Embeddings、Images、Audio 等常见接口。
- OpenAI Responses：面向新一代 Responses API 的请求与响应处理。
- OpenAI Realtime：包含 Azure 场景在内的实时会话接入。
- Claude Messages：支持 Anthropic 原生 Messages 形式及部分格式转换。
- Google Gemini：支持 Gemini 原生请求，并提供与 OpenAI 兼容格式之间的转换。
- Rerank：覆盖 Cohere、Jina 等重排序服务。
- 多媒体与异步任务：图像、语音、音乐和视频相关渠道及任务查询。
README 还列出了 OpenAI Compatible 与 Claude Messages 的双向转换、OpenAI Compatible 到 Gemini 的转换，以及 Gemini 到 OpenAI Compatible 的文本转换；后者暂未覆盖所有函数调用场景。OpenAI Compatible 与 Responses 的完整双向转换仍被标为开发中。部署者应以当前版本的官方接口文档和真实测试为准，不要把路线图当作已完成能力。
用量、定价与运营看板
每次成功请求可以形成用量日志，记录用户、令牌、模型、渠道、输入输出 Token、耗时和扣费等信息。数据看板进一步汇总消费趋势、模型分布和性能指标，帮助管理员定位高成本模型、异常用户、慢渠道与失败请求。项目也支持将日志单独写入数据库，Compose 示例中还给出了 ClickHouse 日志库和保留周期配置。
计费的核心是模型价格、分组倍率、Token 统计和缓存命中规则。New API 支持按次、按量及缓存相关的成本核算，并覆盖多家模型的缓存计费统计。但网关账目仍是依据配置计算的内部账本：供应商可能调整价格，协议适配也可能拿不到精确 Token。正式对账应定期与上游账单抽样核对，价格变更要留存生效时间，避免用今天的价格重算过去的请求。
权限、登录与安全能力
除用户名密码外，项目支持 OIDC，以及 Discord、LinuxDO、Telegram 等授权登录方式。管理端还包含角色和授权策略、全局速率限制、关键操作限流、会话数量与签发窗口控制、可信代理配置、请求体大小限制等机制。多节点部署时，所有实例需要共享一致的会话签名与加密配置。
这些能力提供了治理基础，却不能代替安全配置。反向代理必须正确传递并限制来源地址；公网实例应启用 HTTPS、安全 Cookie 和精确可信 Origin；数据库、Redis、日志与备份都应放在非公开网络。上游密钥、支付密钥、OIDC Secret 和会话密钥不得写进镜像、公开 Compose 文件或前端环境变量。
技术架构
后端使用 Go 构建，HTTP 层采用 Gin，数据层支持 SQLite、MySQL 和 PostgreSQL。编译后的 Web 前端会嵌入 Go 二进制，因此一个服务即可同时提供管理界面、管理 API 与模型中继接口。前端是 React/TypeScript 工程，负责仪表盘、渠道、用户、令牌、日志、模型价格与系统设置等管理体验。
一次典型调用大致经过：下游令牌鉴权、用户与模型权限检查、限流、按分组和模型选择渠道、协议与参数适配、请求上游、流式或非流式响应转换、记录日志并扣减额度。Redis 可承担缓存和多实例协同；后台任务则用于渠道测试、模型同步、异步任务轮询、订阅额度重置和系统实例上报。
这种架构的好处是部署集中、客户端简单，但网关会成为关键基础设施。数据库不可用、路由配置错误或网关资源耗尽，会同时影响多个模型和业务。因此生产环境要把它当作正式服务治理：健康检查、监控、告警、备份、容量规划和升级回滚一个都不能少。
使用 Docker Compose 部署
官方仓库提供了 Compose 示例。当前示例默认组合 New API、PostgreSQL 与 Redis，并将应用数据和日志挂载到持久卷。开始前应安装 64 位 Docker 环境，复制并审查配置，尤其要更换示例中的数据库和 Redis 密码。
git clone https://github.com/QuantumNous/new-api.git
cd new-api
# 先编辑 docker-compose.yml，替换默认密码并设置会话密钥
docker compose up -d
# 查看运行状态与日志
docker compose ps
docker compose logs --tail=200 new-api服务默认监听 3000 端口，启动后可在受控网络中访问 http://服务器地址:3000 完成首次初始化。不要先把端口暴露到公网再创建管理员。更稳妥的做法是通过本机、VPN 或临时防火墙规则完成初始化，然后配置域名、TLS、反向代理和访问控制。
轻量单机与生产数据库
使用单个 Docker 容器且不设置远程数据库时，可以采用 SQLite，并把 /data 持久化到宿主机。它适合个人测试和低并发场景。官方列出的远程数据库最低版本为 MySQL 5.7.8 或 PostgreSQL 9.6；团队和多实例部署通常应选择独立数据库，并使用 Redis 协调缓存状态。
SQLite 文件、数据库卷、应用日志和配置必须纳入备份。数据库备份只有经过恢复演练才有价值；多实例升级前还要确认数据库迁移是否兼容回滚。不要让多个未经验证的应用版本同时对同一数据库执行结构迁移。
首次配置的推荐顺序
- 完成初始化：在受控网络创建管理员，立即保存高强度凭据并限制管理入口。
- 添加一个测试渠道：使用权限和额度受限的上游 Key，只开放一个非敏感测试模型。
- 检查渠道：执行连通性测试，确认 Base URL、模型名、超时和响应格式。
- 配置价格与分组：设置模型价格、分组倍率、渠道优先级和权重，记录配置依据。
- 创建下游令牌：限制模型、额度、有效期和可选 IP 范围，不向客户端发放上游 Key。
- 做端到端验证：分别测试普通、流式、工具调用和多模态请求，核对日志、Token 与扣费。
- 再增加冗余渠道：模拟上游超时和限流，观察重试、故障切换与成本是否符合预期。
生产环境必须注意什么？
密钥与网络边界
使用密码管理器或密钥服务注入 SESSION_SECRET、数据库、Redis、上游和登录服务凭据。多实例的 SESSION_SECRET 与相关加密密钥必须一致，且不能使用示例值。数据库和 Redis 不应直接暴露公网；管理 API 最好通过独立域名、VPN、零信任访问或来源白名单保护。
反向代理与真实客户端地址
正确设置 TRUSTED_PROXIES，只信任实际反向代理的 IP 或网段，避免攻击者伪造转发头绕过 IP 限制。公网 HTTPS 环境应启用安全 Cookie，并为刷新和退出接口配置精确的可信 Origin。通配符、错误的协议或遗漏端口都可能造成登录异常或削弱校验。
请求、日志与隐私
为请求体、流式缓冲、连接与处理时间设置合理上限，防止超大图片、Base64 数据或压缩请求耗尽内存。错误日志和用量日志应避免记录完整密钥与敏感提示词，并制定访问权限、脱敏和保留周期。将请求转发给哪家上游，本身就是数据处理决策，涉及源码、个人信息或客户数据时必须得到授权。
升级、监控与备份
不要在生产环境无条件跟随 latest。更稳妥的方式是固定经过验证的镜像版本，阅读 Release Notes，在预发布环境验证数据库迁移、核心模型、流式输出、计费和 OAuth，再安排升级。监控至少应覆盖进程存活、请求量、错误率、上游延迟、数据库连接、Redis、磁盘、内存与额度异常。
AGPL-3.0 许可证意味着什么？
New API 采用 AGPL-3.0。与宽松许可证相比，AGPL 对修改、分发以及通过网络向用户提供修改版程序的源代码义务更严格。如果只是原样内部使用、修改后对外提供网络服务、把它集成进商业平台，适用义务可能不同。部署前应阅读仓库中的 LICENSE 和第三方许可证清单，涉及商业产品时咨询熟悉开源许可证的专业人士；本文不构成法律意见。
优势与局限
优势：支持的渠道和接口广，统一令牌与模型入口能降低客户端复杂度；分组、额度、价格、日志和看板形成较完整的运营闭环；Docker 部署门槛较低，SQLite 到 PostgreSQL/MySQL 的选择覆盖个人与团队场景；社区活跃，协议适配更新较快。
局限：上游协议变化频繁，格式转换难以保证所有高级能力无损；集中网关扩大了故障和安全影响面；价格与 Token 统计需要持续校准；支付、公开运营和跨供应商数据转发会引入额外合规责任；快速迭代也意味着升级前必须测试。大量 Star 不能替代代码审计、威胁建模与运维能力。
适合谁，不适合谁？
如果团队有多个模型供应商、多个业务或用户，需要统一鉴权、路由、额度和成本观察，New API 能显著减少重复建设。它也适合在合规授权的前提下搭建内部 AI 能力入口，让开发环境只持有权限受限的下游令牌。
如果需求只是偶尔调用一家官方 API，或者团队无法承担网关的安全、备份和监控责任，引入 New API 反而会增加一层复杂度。对于强监管或高敏感环境，还需要确认第三方依赖、日志内容、部署地区和每个上游的数据条款，不能仅因为“私有部署”就认定数据不会离开组织。
总结
New API 的核心价值，是把分散的模型渠道整理成一个可治理的统一入口。它把协议适配、渠道路由、下游令牌、用户分组、额度、计费和数据看板放在同一套系统中，适合模型种类与调用方快速增长的场景。
真正可靠的部署不止是运行一条 Compose 命令。先从受限测试渠道开始，验证协议与账目，再逐步加入冗余、登录和支付；同时固定版本、保护管理面、妥善保存密钥、限制日志、监控核心指标并演练恢复。只有这些基础工作到位，统一网关才能降低复杂度，而不是成为新的单点风险。
资料说明：本文依据 New API 官方 GitHub 仓库、中文 README、Docker Compose、源代码、官方文档、GitHub API 与 v1.0.0-rc.24 发布信息在 2026 年 8 月 13 日可见的内容整理。功能、版本、支持渠道和部署要求会持续变化，请以官方仓库与官方文档为准。
