NewAPI大模型积分网关简介

OpenAI 兼容的大模型网关，统一管理上游渠道与 Key，按用户积分扣费、额度不足即拒绝。适合私有化部署和线下加额，并说明 AGPL、Compose 与用户令牌调用。

发表于 2026/07/31

作者 handsomestwei

12 分钟阅读

NewAPI大模型积分网关简介

New API（仓库 QuantumNous/new-api）是 OpenAI 兼容的大模型网关：统一管理上游渠道与 Key，按用户令牌计积分、超额拒绝。适合「平台统一配渠道 + 按用量扣额度 + 线下收款后台加额」的私有化部署。本文说明选型、AGPL 边界、Docker Compose 部署，以及线下充值与用户令牌调用。产品别名、渠道路由与系统访问令牌的控制台细项另文展开；本文只保留上线所需的骨架。

参考与延伸阅读：

官方文档：https://docs.newapi.ai/zh/docs
Docker Compose 部署：https://docs.newapi.ai/zh/docs/installation/deployment-methods/docker-compose-installation
Compose 配置说明：https://docs.newapi.ai/zh/docs/installation/config-maintenance/docker-compose-yml
渠道管理：https://docs.newapi.ai/zh/docs/guide/feature-guide/admin/channel
GitHub 仓库：https://github.com/QuantumNous/new-api
商务合作：https://docs.newapi.ai/zh/docs/business

1. 选型对照

终端用户自配厂商 URL / Key 对非技术人员不友好。常见替代是平台侧托管一组上游渠道，按租户用量扣额度，额度不足则拒绝请求。线下收款时不必接在线支付，后台手动加额即可。

能力	New API	One API	LiteLLM Proxy
多渠道上游 Key	支持	支持	支持
用户积分 / 配额	开箱即用	基础额度	Virtual Key + 预算，充值需自建
充值	易支付 / Stripe；也可纯手动	弱	需自建
超量拒绝	支持	支持	`max_budget`
模型换算定价	模型倍率 / 补全倍率 / 分组倍率	基础	偏 USD 成本追踪
部署形态	Go + Docker，单机可跑	更轻，维护偏旧	Python，偏工程网关
许可	AGPL-3.0	MIT	MIT

与「统一配渠道 + 按用户积分计费 + 线下加额度」最贴合的是 New API。会员功能权益（席位数、时长配额等）仍由业务后端管理；New API 只负责 LLM Token 积分。二者正交，互不替代。

2. 商用与 AGPL

要点	说明
私有化给自家产品用	可以
线下收款、后台手动加额度	支持，不必接在线支付
协议	AGPL-3.0
官方定位	合法授权的 API 网关、内部管理、私有化部署；须遵守上游服务条款与当地监管

AGPL 要点（正式商用前建议法务复核）：

允许商用、允许收费。
若修改了 New API 源码并以网络服务形式提供给他人使用，通常需向使用者提供对应修改后的源码。
不改源码、原样 Docker 部署，合规负担相对较小；仍应保留官方仓库链接与 LICENSE。
官方商务入口见文档首页的 Business Cooperation。

别名映射、多渠道路由、失败重试均可在控制台完成，不必 fork。若要把响应 JSON 里的 upstream 模型名改回产品名，才需要业务侧 BFF 或改网关源码。

3. 目标架构

用户登录业务系统
    → 业务后端签发会话（功能权益照旧）
    → 同步或签发 New API 用户令牌

客户端 LLM 请求
    → baseUrl = https://llm.example.com/v1
    → Authorization = 用户专属 sk-xxx（非厂商 Key）

New API
    → 校验额度 → 产品模型别名重定向 → 按优先级/权重选渠道
    → 失败时按重试次数切换 → 按定价扣积分
    → 额度不足 → 直接拒绝

覆盖范围是走 OpenAI 兼容协议的桌面端与服务端 SDK。OAuth 类 Provider（如部分 Copilot / Codex 接入）难经统一网关替换，可暂不纳入积分池。

4. Docker Compose 部署

官方步骤以 Docker Compose 部署为准。

前置：Linux 服务器、Docker 与 Compose；开放 3000（生产用 Nginx / Caddy 反代 HTTPS）。

  
git clone https://github.com/QuantumNous/new-api.git
cd new-api
# 生产务必先改 docker-compose.yml 中的默认密码
docker compose up -d

仓库自带 compose 通常包含：

服务	说明
`new-api`	镜像 `calciumion/new-api:latest`，端口 `3000`
`postgres`	默认数据库（也可用 MySQL，见官方注释）
`redis`	缓存

生产必改：Postgres 密码及 SQL_DSN、Redis 密码及 REDIS_CONN_STRING。多机部署再设 SESSION_SECRET。官方 compose 已挂载 ./data、./logs，勿删。

浏览器打开 http://服务器IP:3000，首次访问创建 Root 管理员。常用命令：

docker compose ps
docker compose logs -f new-api
docker compose down

down 一般不删 volume / ./data。

5. 线下充值与用户令牌

按下列顺序即可支撑「线下收款 + 后台加额度」，不必启用易支付 / Stripe。

渠道：控制台添加上游（DeepSeek、MiniMax、通义等）及官方 API Key；可配优先级 / 权重。
定价：为请求里的 model 名配置按量价格或倍率；额度不足则拒绝后续请求。
用户：用户管理中创建账号（或按需开放注册）。每个终端用户对应一个 New API 用户，或由业务后端代管令牌。
加额度：编辑用户调整配额；也可批量生成兑换码发给用户自兑。
令牌：创建形如 sk-xxx 的 API 令牌供客户端调用。

项	值
Base URL	`https://llm.example.com/v1`（或 `http://IP:3000/v1`）
API Key	用户专属 `sk-xxx`
协议	OpenAI 兼容（`/v1/chat/completions` 等）

  
curl https://llm.example.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"app-chat","messages":[{"role":"user","content":"ping"}]}'

额度用尽应返回余额不足类错误，请求不会打到上游。控制台若用独立 HTTPS 端口对外，客户端 Base URL 仍拼 /v1；令牌页里出现的 http://localhost:3000 是网关本机根地址，不是给终端填的地址。

6. 产品别名与失败切换

不需要改 New API 源码。客户端请求产品名（如 app-chat），网关映射到上游真实模型（如 deepseek-chat）。换 upstream 只改控制台映射，不必发版客户端。

能力	控制台位置	是否改源码
产品别名 → 真实 upstream	渠道 → 模型映射 / 模型重定向	否
同模型多渠道负载	渠道优先级、权重	否
渠道失败切换	设置 → 运营设置 → 失败重试次数	否
坏渠道自动下线	渠道自动禁用	否
积分 / 分组倍率	系统设置	否

渠道的模型列表必须包含客户端实际请求的产品名，名称备注写成产品名并不够。定价同样按请求 model 名查找，只给上游名配价会报价格未配置。这两处是上线后最常见的 503 / model_price_error 来源。

Failover 概念：

请求 model=app-chat
  → 重定向为上游真实名
  → 选优先级最高的渠道 A
  → A 返回 4xx/5xx 且重试次数 > 0
  → 尝试优先级次高的渠道 B
  → 连续失败达阈值 → 自动禁用

创建 Token 时可设模型白名单，只允许产品别名，避免用户构造 upstream 名称绕过档位。

7. 与业务系统的职责划分

默认把客户端 baseUrl 指到 New API，Key 改为登录后下发的平台令牌；高级用户可另留 BYOK 开关。
产品别名由业务后端下发；真实 upstream 只在 New API 后台映射。
多端（桌面 Agent、Python SDK 等）走同一网关，避免两套计费。
登录成功后创建或绑定 New API 用户与令牌；功能权益仍走原有会员体系。
剩余额度可由网关查询接口返回，或由业务后端聚合展示。

OAuth 类上游、以及要把响应里的 model 改回产品名，都不在「原样 Docker + 控制台」范围内。

8. 验收要点

项	预期
`docker compose up -d`	`new-api` / `postgres` / `redis` 健康
控制台	完成 Root 初始化；已改数据库与 Redis 默认密码
渠道	至少一条上游测试调用成功
别名	产品名能映射到预期 upstream，模型列表含产品名
定价	按产品名扣费，而非只给上游名配价
重试	失败重试次数 ≥ 1 时主渠道故障可切备用
额度	手动加额后 `sk` 可调；清零后被拒绝
生产	HTTPS 反代；备份 Postgres volume / `./data`

9. 小结

要点	结论
定位	私有化 LLM 积分网关，OpenAI 兼容
许可	AGPL-3.0；原样部署负担小于 fork
支付	可纯线下加额度，不必接在线支付
客户端	只拿网关 `/v1` 与用户 `sk`，不持有厂商 Key
换模	改渠道映射即可，不必发版客户端

AI, LLM

AI LLM NewAPI

本文由作者按照 CC BY 4.0 进行授权

NewAPI大模型积分网关简介

NewAPI大模型积分网关简介

目录

1. 选型对照

2. 商用与 AGPL

3. 目标架构

4. Docker Compose 部署

5. 线下充值与用户令牌

6. 产品别名与失败切换

7. 与业务系统的职责划分

8. 验收要点

9. 小结

热门标签