new-api 系列（一）：认识 new-api——新一代 AI API 管理网关

2026年6月6日 10:00 CST new-apiAPI网关AI中转OpenAI兼容教程

这是 new-api 系列教程的第一篇，从概念到 5 分钟快速上手。

系列目录

（一）认识 new-api——新一代 AI API 管理网关（本文）

（二）安装部署——从零搭建 new-api

（三）渠道配置——接入各类模型提供商

（四）令牌与用户管理

（五）计价模型与成本控制

（六）监控、日志与告警

（七）生产环境部署与安全加固

（八）进阶——多实例、负载均衡与 SSO

（九）接入国内支付——支付宝、微信与自动充值

（十）接入国际支付——Stripe、PayPal 与海外收银

# new-api 概述 ## 是什么 - AI API 管理与分发系统 - one-api 的下一代继任者 - Go 语言编写，单二进制部署 - 开源 MIT 协议 ## 核心功能 - 多提供商统一端点（OpenAI 兼容） - 用户管理 + 令牌鉴权 - 额度配额管理 - 请求限流（QPM / 并发） - 用量日志与统计 - Web 管理面板 ## 架构 - 客户端 → new-api :3000 → 渠道（上游 API） - 渠道 = 上游提供商 + 密钥 - 令牌 = 用户访问凭证 ## 适用场景 - 团队共享 API 额度 - 个人多设备统一接入 - 小规模 AI API 转售 - 企业内部模型网关 ## 对比 one-api - 代码重写，架构更清晰 - 性能优化（Go 原生并发） - 渠道健康检查更完善 - 计价模型更灵活 - 社区更活跃

什么是 new-api

new-api（GitHub：Calcium-Ion/new-api）是 one-api 的下一代版本，由社区开发者用 Go 从头重写。它本质上是一个 AI API 管理与分发系统——在你的服务器上运行，作为上游模型提供商和下游用户之间的中间层。

它的核心价值可以用一句话概括：把多个模型提供商的 API Key 统一成你自己的 API 服务，对外只暴露一个端点、一套令牌体系。

flowchart LR U1["用户 A\n令牌 sk-aaa"] --> NW["new-api :3000\n鉴权 / 计费 / 限流"] U2["用户 B\n令牌 sk-bbb"] --> NW U3["用户 C\n令牌 sk-ccc"] --> NW NW --> CH1["渠道 1\nOpenAI 官方"] NW --> CH2["渠道 2\nAzure OpenAI"] NW --> CH3["渠道 3\nClaude API"] NW --> CH4["渠道 4\n本地 Ollama"]

核心功能一览

多提供商统一端点

new-api 对外提供标准的 OpenAI 兼容 API（/v1/chat/completions、/v1/models 等），任何支持 OpenAI 格式的客户端都可以直接接入。背后你可以接入几十种不同的模型提供商——OpenAI、Anthropic、Google、Azure、DeepSeek、通义千问、Ollama、vLLM 等等——用户只需要关心模型名，不需要知道背后是哪个提供商。

用户管理与令牌鉴权

new-api 内置用户系统和基于令牌（API Key）的鉴权。管理员在后台创建用户、生成令牌、设置额度上限，然后分发给团队成员。每个令牌独立计费、独立限流，互不影响。

灵活的计价与额度控制

支持按 Token 计费、按次计费、按模型差异化定价。可以设置无限额度、固定额度、或按时间重置的周期额度（如每月 100 万 Token）。余额低于阈值时触发预警。

请求限流与并发控制

支持全局 QPM（每分钟请求数）限制、单用户 QPM 限制、并发连接数限制。超过限制返回 429 Too Many Requests，防止上游 API 被单个用户打爆。

用量统计与日志

每一次请求都会记录：哪个令牌、哪个模型、消耗多少 Token、耗时多少、走的是哪个渠道。支持按时间范围过滤、按用户聚合、导出 CSV 做账单。

Web 管理面板

内置基于 React 的管理界面，支持桌面端和移动端。可以在面板上完成渠道配置、用户管理、额度调整、日志查看等所有运维操作，无需手写 SQL。

整体架构

new-api 内部有几个核心概念，理解它们就掌握了使用方式：

概念	说明	类比
渠道（Channel）	上游模型提供商的连接配置，含 API 地址、密钥、模型列表	上游供应商
模型（Model）	可在渠道中勾选的具体模型名，如 `gpt-4o`、`claude-opus-4-8`	商品 SKU
令牌（Token）	分发给用户的访问凭证，`sk-` 开头	用户的会员卡
用户（User）	令牌的归属，可以有多个令牌	会员账号
日志（Log）	每次 API 请求的详细记录	消费流水

flowchart LR TK["令牌 sk-xxx"] --> AUTH["new-api 鉴权"] AUTH --> QUOTA["额度检查"] QUOTA --> RATE["限流检查"] RATE --> ROUTE["渠道路由"] ROUTE --> CH["上游渠道 A / B / C"] ADM["管理员 Web 面板"] -.-> AUTH

5 分钟快速上手

第一步：登录后台

浏览器打开 http://127.0.0.1:3000，默认账号：

用户名：root
密码：123456

上来就改密码：点右上角头像 → 个人设置，修改默认用户名和密码。不要在生产环境保留默认凭证。

第二步：添加渠道

左侧菜单 →「渠道」→「添加渠道」：

字段	填写
类型	选择你的提供商（如 OpenAI）
名称	自定义，如 `OpenAI-官方`
密钥	你的 API Key（多个 Key 换行分隔）
模型	勾选你想提供的模型（可先点「从服务器获取」自动拉列表）

点「测试」确认连通，通过后保存。

第三步：创建令牌

左侧菜单 →「令牌」→「添加令牌」：

字段	填写
名称	如 `test`
剩余额度	先填 `1`（1 美元不限制）

创建后复制生成的 sk- 令牌。

第四步：发起测试请求

curl http://127.0.0.1:3000/v1/chat/completions \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "你好"}]
  }'

返回正常 JSON 即代表整条链路通了。

flowchart LR A["curl 请求\nBearer sk-xxx"] --> B["new-api :3000\n验证令牌 → 扣额度 → 查渠道"] B --> C["上游 API\nOpenAI / Anthropic / ..."] C --> D["返回 JSON 给客户端"]

new-api vs one-api

one-api 是这一品类的开创者，但已经一年多没有实质性更新。new-api 由社区接手后做了大量改进：

对比维度	one-api	new-api
语言	Go	Go（代码重写）
渠道健康检查	基础探测	自动禁用 + 定时恢复 + Webhook 通知
计价	固定倍率	多模型独立定价 + 自定义规则
模型映射	不支持	支持来源别名 → 实际模型名
渠道优先级	权重	权重 + 优先级 + 故障自动切换
用户分组	无	支持用户角色（管理员 / 普通用户）
社区活跃度	停滞	持续更新，Issue 响应快

如果你从 one-api 迁移，new-api 提供了数据库兼容模式，可以平滑过渡（见后续安装篇）。

典型部署拓扑

场景一：个人使用（最简）

一台机器跑 new-api，自己用，不需要反代，不需要域名。

场景二：小团队共享

flowchart LR M1["成员 1"] --> NW["new-api :3000"] M2["成员 2"] --> NW M3["成员 3"] --> NW NW --> CH1["OpenAI"] NW --> CH2["Claude"] NW --> CH3["DeepSeek"]

内网部署，成员通过局域网 IP 访问。适合 3~20 人团队。

场景三：公网服务（对外提供 API）

flowchart LR U1["公网用户"] --> NG["Nginx / Caddy\nHTTPS 反代"] U2["公网用户"] --> NG NG --> NW["new-api :3000"] NW --> UP["上游模型池"]

加上反代 + HTTPS + 域名 + 限流，可以对外提供付费 API 服务。

场景四：new-api + CLIProxyAPI（OAuth 订阅池）

用 CLIProxyAPI 把 OAuth 订阅账号转成 API，再用 new-api 做用户管理和计费。适合没有商业 API Key、只靠订阅配额运转的场景。详见 CLIProxyAPI 系列第六篇。

系列导航

下一篇直接进入安装部署——二进制、Docker、systemd，三种方式任选。

实操清单

理解 new-api 的核心概念：渠道、令牌、用户、日志
明确自己的使用场景（个人 / 团队 / 公网服务）
确认服务器系统环境（Linux / macOS / Windows）
准备好至少一个上游 API Key（OpenAI / Anthropic / DeepSeek 等）
阅读下一篇安装部署，选择适合自己的安装方式