不上前十不改名如果你管过三个以上大模型 API Key，应该能体会到那种隐藏在控制台背后的混乱：各家平台的密钥规则不同、账单口径不同、团队里谁调了多少完全靠猜，月底对账更是灾难。这个问题在我这边发展到什么程度呢？光是记录密钥的表格就有四五个版本，后来不得不写脚本去各平台拉用量再手工合并。直到我决定换一种思路，把目光投向了一个开源项目——New API，一款可以自托管的 AI 网关。它做的事情简单说就是：把多个模型厂商的接口统一收口到一个入口，让团队内部所有请求都走同一个门，密钥管理、模型路由、额度分配、调用日志全都集中在一起。这篇文章我会从我的实际使用经历出发，把这套网关的部署、配置、踩坑和运维经验完整梳理一遍，适合正在被多模型管理折磨的开发者、小团队技术负责人，也适合想给自建应用加一层统一 API 入口的独立开发者。
1. 我的场景就是从"钥匙串"变成"门禁系统"
1.1 散落各处的 API Key 是混乱的根源
我很长时间没意识到问题的本质。表面看，团队有 OpenAI 的 Key，有 Anthropic 的 Key，有 DeepSeek 的 Key，再加上国产几家大模型的 Key，工具齐全，想用什么模型就用什么模型。但深入用起来就会发现，Key 越多，管理成本不是线性增长，而是爆炸式增长。
首先是密钥权限无法收口。任何一个同事离职，他手里可能攒了三四个平台的 Key，你没法确定他是不是已经把这些 Key 存在了某个笔记软件里，只能全部重置再逐个通知相关系统修改配置。其次是调用数据分散在各厂商后台，每次想统计某个功能一个月花了多少钱，要登录五六个平台，把时间范围对齐，再把不同币种、不同计量单位的账单手工整理到一张表里。
最让我崩溃的是没有一个统一的"熔断"机制。某个 Key 因为欠费或者触发了限流，上游报错只会出现在对应服务的日志里，前台用户感知到响应变慢或失败，我们再去翻日志找是哪个环节出问题，效率极低。
1.2 New API 做了什么：把各家厂商的后端抽象成一扇统一的门
后来我了解到 New API 这个开源项目。它最初是从 One API 这个项目 fork 出来的，作者在原有基础上做了大量增强，核心定位就是做一个可自托管的 AI 网关。你把它部署在自己的服务器上，它对外暴露一套兼容 OpenAI 接口规范的 API，对内可以对接多个模型提供方。
也就是说，团队内部所有业务服务统一只配置网关的地址和网关下发的 Token，由网关在中间完成路由转发、鉴权、限流、重试、计量计费。业务侧不再关心上游到底是 OpenAI、Anthropic 还是 DeepSeek，也不关心 Key 是否存在某个环境变量里。所有密钥、调用量、费用明细全部集中在网关的控制台里。
这个抽象的价值，用一句大白话讲就是：以前每个人手里攥着一大把钥匙，哪个门坏了还要挨个试；现在门口装了一套门禁系统，进门刷卡，谁刷的、什么时候刷的、去了哪一层，系统全都有记录。
1.3 为什么我推荐自托管而不是用厂商控制台
有些厂商自己的控制台也带了用量统计和密钥管理功能，为什么还要自建网关？我的理由很直接，第一是数据归属权。厂商后台只保留"我的账号下发生了什么"，而网关记录的是"我的业务里谁在什么场景下调用了什么模型"，后者带着业务维度，对成本核算和性能调优更有价值。第二是切换成本。今天某个模型的价格政策调整了，我可以直接在网关里调整倍率、切换渠道，业务代码一行不用动。第三是权限粒度。我可以给不同项目、不同成员分配不同令牌，设置不同额度，而不是把主 Key 直接给他们。
当然，自托管也有代价，比如需要你自己维护一台服务器、处理升级和备份。但从投入产出比来看，对于调用量大、团队人数多的场景，这个代价完全值得。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. New API 的控制台与核心对象：渠道、令牌、分组
2.1 渠道（Channel）是什么：一张"上游连接表"
第一次打开 New API 的控制台，左上角第一个进入视线的概念就是"渠道"。渠道这个词可能对新手有点抽象，我的理解是：渠道就是一条通往某个上游模型服务的连接配置。
在控制台里创建渠道时，你需要指定渠道类型，比如 OpenAI、Anthropic、Google Gemini、DeepSeek、智谱、通义千问等，然后填入对应的 API Key，再声明这个渠道提供哪些模型。New API 支持把多个同类型渠道配置成一组，它会自动做负载均衡和健康检查，某个渠道挂了就自动切换到另一个可用渠道。
New API 支持的渠道类型非常多，这也是我坚持选它的一个重要原因。市面上不少网关工具只支持 OpenAI 格式的接口，一旦要接 Anthropic 的原生接口或者国内厂商的私有协议，就得自己写适配层。New API 把这些接入协议都内置了，控制台里点选类型、粘贴 Key 就能用。
2.2 令牌（Token）不是密钥，是权限策略
在 New API 里，"令牌"这个词和大部分人的直觉有点偏差。它不是简单的"一串密钥"，而是一个包含权限策略的载体。创建令牌时，你可以给它绑定分组、设置额度上限、指定可用模型、设定每分钟请求数（RPM）和每分钟 Token 数（TPM）上限、配置过期时间。
这意味着你可以为每一个调用方创建一套独立的令牌，比如前端 App 用一个令牌、后端数据分析任务用一个令牌、同事的调试脚本单独用一个令牌。每一个令牌的用量和消耗都被独立记录，出了问题可以精确追溯到是哪个令牌在哪个时间点调用失败。更关键的是，令牌可以随时删除，删掉之后对应的访问立即失效，不需要重启服务或者改配置。
我最常用的做法是给每个项目创建独立令牌，然后把额度和速率限制都设好，这样即使某个项目的代码被泄露了 Token，损失也只会被控制在一个可控范围内，而不是整个账户的 Key 裸奔。
2.3 分组（Group）怎么用：隔离成本与场景
分组是 New API 里另一个容易被人忽略的功能。它把渠道和令牌连接在一起，规则是：令牌属于哪个分组，它就只能使用那个分组下的渠道。这样的设计非常实用，因为不同模型的成本差异巨大。
举个例子，我把 GPT-4o 这类高端模型放进"pro"分组，把 DeepSeek 和通义这类性价比模型放进"basic"分组。日常给普通员工分配的令牌挂在 basic 分组，只有核心研发人员的令牌挂到 pro 分组。这样既保证了大多数场景的成本可控，又不妨碍少数高端场景使用更强的模型。控制台里每个渠道和每个令牌都可以独立设置分组归属，权限隔离做得很细。
3. 从零部署：Docker Compose 一段配置跑起来
3.1 部署前要确定的几个参数
New API 的部署方式很灵活，官方提供了 Docker 镜像，也支持直接编译二进制文件运行。我的建议是，如果没有特殊要求，直接用 Docker Compose 部署，升级维护都方便。部署前需要确定几个关键参数：第一个是数据存储方式，单机小规模场景默认用 SQLite 就够了，但如果打算做多实例部署或者并发量预期较高，建议一开始就上 MySQL；第二个是是否需要 Redis，Redis 主要用于多实例场景下的数据同步和缓存，单实例可以不用；第三个是访问方式，如果只在内网使用，直接映射端口就行，如果要公网访问，提前准备域名和 HTTPS 证书。
我推荐的最小配置是 1 核 2G 内存的服务器，SQLite 存储，不加 Redis。这个配置足够支撑一个小团队几十人规模的日常调用，实测非常稳定。
3.2 docker-compose.yml 与初始化配置
下面是我实际用过的 docker-compose.yml 配置，我直接把关键部分贴出来：
yaml复制version: "3"
services:
new-api:
image: calciumion/new-api:latest
container_name: new-api
restart: always
ports:
- "3000:3000"
environment:
- TZ=Asia/Shanghai
- SESSION_SECRET=your_random_secret
- SQL_DSN=root:yourpassword@tcp(mysql:3306)/new-api
- REDIS_CONN_STRING=
depends_on:
- mysql
volumes:
- ./data:/data
networks:
- newapi_net
mysql:
image: mysql:8.0
container_name: new-api-mysql
restart: always
environment:
- MYSQL_ROOT_PASSWORD=yourpassword
- MYSQL_DATABASE=new-api
volumes:
- ./mysql-data:/var/lib/mysql
networks:
- newapi_net
networks:
newapi_net:
几个环境变量值得说一下。SESSION_SECRET 是用来加密登录会话的随机字符串，务必设置成长随机串，否则存在会话伪造风险。SQL_DSN 是数据库连接串，如果只是单实例实验，可以注释掉这行，默认使用 SQLite，数据文件会写到 /data 目录下。TZ 一定要设置，否则容器默认使用 UTC 时区，后面看日志时间会很痛苦，这个我在踩坑部分会单独说。
启动命令很简单，docker compose up -d 即可。首次启动会自动初始化数据库表结构，不用手工执行 SQL 脚本。启动完成后访问 http://服务器IP:3000，能看到登录页面。
3.3 首次登录与必须马上做的事
New API 的默认管理员账号是 root，默认密码是 123456。这组默认凭证只是用来给你做首次进入的，进入控制台后第一件事就是修改密码，然后去"用户管理"里创建一个日常使用的管理员账号，最好把 root 的登录权限严格限制下来。
接下来建议进入"系统设置"面板，把站点名称改成自己的，配置一下通知邮箱或者 Webhook 地址，这样后面有用户额度不足、渠道异常等情况时可以及时收到通知。如果打算让团队其他人注册使用，还需要在"系统设置"里选择注册方式，默认可能是关闭注册，需要按需打开。
我踩过一个小坑是刚部署完没改默认密码，内网扫描工具直接撞库成功了，好在当时网关里还没接入真实渠道，没有造成实际损失。从那次以后，我把改默认密码列为部署后的第一优先级操作，没有例外。
4. 接入渠道与模型：从控制台到第一个聊天请求
4.1 创建渠道的完整步骤与字段含义
在控制台左侧菜单找到"渠道"，点击"添加渠道"，就会看到渠道配置表单。这里的选择比较多，我从最常用的"OpenAI"类型开始说。
第一步选类型，第二步填名称，这个名称是给你自己看的，建议包含平台和用途，比如"OpenAI 主力"或者"DeepSeek 备线"。第三步填上游 API Key，这是最核心的凭证，New API 会用它去上游服务换取真正的模型响应。第四步填模型列表，多个模型名用英文逗号分隔，比如 gpt-4o,gpt-4o-mini。这里有个细节：模型名必须和上游平台官方名称完全一致，填错了即使渠道测试通过，真正调用时也会报 model not found。
第五步是分组设置，可以选多个分组，这里就用到前面说的按场景隔离的逻辑。其他字段里，模型倍率、最大并发、超时时间这些参数建议保持默认，等你对业务流量有了实际感知后再调。填完点击"提交"，然后在渠道列表页点那个"测试"按钮，New API 会向该渠道发一条最小请求来验证连通性。
我遇到过一种情况：渠道测试返回正常，但正式调用就是失败。后来排查发现是模型列表里填了上游不支持的模型名，测试按钮只验证渠道连通性，不会逐模型验证，所以填模型列表时一定要和上游控制台核对。
4.2 对外统一接口：兼容 OpenAI 格式
渠道接好之后，网关对外提供了一个统一的接口入口，默认路径是 /v1 开头的那些接口，包括 /v1/chat/completions、/v1/models、/v1/embeddings 等。这意味着几乎所有支持 OpenAI SDK 的编程语言都可以无缝接入，只需要修改两个东西：Base URL 和 API Key。
我把直连厂商和走网关的差异整理成了一张表，方便理解：
| 对比项 | 直连厂商 | 走 New API 网关 |
|---|---|---|
| API Key | 每个厂商独立配置 | 统一使用网关分配的令牌 |
| Base URL | 各厂商专属地址 | 固定为网关地址加 /v1 路径 |
| 模型切换 | 修改代码 | 网关渠道切换或模型路由 |
| 用量统计 | 各平台后台分别看 | 网关控制台统一查询 |
| 熔断重试 | 需要自己实现 | 网关内置自动重试机制 |
这个设计给我带来的直接好处是，团队里以前为直连 OpenAI 写的代码，只需要换一个 baseURL，就可以全部切换到网关，完全不需要改动业务逻辑。
4.3 用 curl 验证一把，再接入聊天前端
渠道配置完成后，我习惯先用 curl 做一次完整的冒烟测试，确认令牌、模型、计费链路都没问题后再接入上层应用。下面是一个最小验证命令：
bash复制curl http://your-domain:3000/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-你创建的令牌" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "你好，请回复一句话"}]
}'
如果返回结果里包含 choices 字段，说明链路全通。此时去控制台的"日志"页面，能看到这次请求的完整记录，包括用户、令牌、模型、输入 Token 数、输出 Token 数、耗时、费用等详细信息。这一步验证完成后，就可以放心接入上层应用了。
我自己用的是开源聊天前端配合网关一起使用，把前端的 API 地址指向网关，密钥填网关分配的令牌，再用管理员账号给不同成员分配独立令牌，整条链路就完整了。成员之间的聊天记录互不可见，消费各自独立计量。
4.4 把网关接入自建前端
如果你也在用 NextChat 或 LobeChat 这类开源前端，配置思路是相通的。在设置里找到"自定义接口地址"或"Base URL"选项，填成 http://你的网管地址/v1，模型列表直接选网关里有的模型名，API Key 填网关令牌。
这里要提醒一句：不要在聊天前端里面直接填渠道的上游 Key，而是创建专用的网关令牌来填。这样即使前端配置被同事看到，他拿到的也只是一个受限令牌，而不是上游全量权限。后面如果这同事不再需要访问权，直接在网关里删掉令牌即可，不需要改前端配置。
5. 令牌、计费与速率限制：网关的核心价值
5.1 令牌额度与倍率换算逻辑
New API 内部有一套积分系统，令牌的额度就是以积分形式存在的。积分数值可以直接映射成你配置的倍率。控制台里每个渠道都有"模型倍率"字段，倍率乘以实际消耗的 Token 数，再经过一定的换算，就是一次请求扣除的积分。
举一个具体例子：假设模型 A 的倍率是 1，表示输入 1000 个 Token 扣除 1 个积分，输出 1000 个 Token 也扣除 1 个积分；如果模型 B 的倍率是 5，则同样 Token 数会扣 5 个积分。这样设计的好处是，你可以灵活调整模型的价格策略，比如给某个新模型做促销，把倍率调低，而不用担心上游涨价。
创建令牌时，额度填 -1 表示不限制额度，填具体数字则表示这个令牌最多可以消耗这么多积分。等额度用尽，令牌自动失效，对上层应用来说会收到 402 或 401 错误。我建议给测试环境、临时脚本的令牌都加上额度上限，防止写了个死循环把预算打光。
5.2 RPM/TPM 限制是怎么回事
RPM 是 Requests Per Minute（每分钟请求数），TPM 是 Tokens Per Minute（每分钟 Token 数）。New API 支持在令牌级别限制这两个指标，这是很多自建应用容易忽略但到了生产环境又非常关键的能力。
我之前的场景里，有同事写了一个批量任务，同时发起几十个并发请求，直接把上游渠道的速率限制打满了，导致其他正常业务请求也跟着失败。后来我给他的令牌设置了合理的 RPM 和 TPM 后，批量任务被网关限流，最多只能占用一部分配额，其他业务基本不受影响。
设置的时候要考虑业务实际需求。比如一个聊天机器人应用，交互是实时的，RPM 可以设置得高一些，但单次请求 Token 量不大；而离线批量处理任务，RPM 可以相对低，但单请求可能很大，TPM 要适当放宽。没有通用的固定值，主要是根据上游渠道的承载能力和业务优先级来平衡。
5.3 用户体系与告警：谁在调用、花了多少
New API 内置了完整的用户管理模块。管理员可以创建用户，用户登录后可以创建自己的令牌、查看自己的调用日志和消费记录，但互相之间数据隔离。这个功能非常适合公司内部"平台化"的使用方式：每个部门或项目分配一个用户，各部门自己管理自己的令牌额度，管理员只在全局层面做总控。
配合告警通知功能，当用户额度低于某个阈值或者渠道连续失败时，网关会通过 Webhook 或邮件推送告警。我把告警 Webhook 接到了内部通知系统，现在每个月月底都不用再发人工对账邮件，直接在网关后台导出一份消费统计 Excel 就行，省了很多时间。
6. 实测中踩过的坑：完整排查链路还原
6.1 坑：渠道测试通过，但实际请求报 model not found
这是我第一次接入网关就遇到的魔幻问题。渠道测试按钮返回成功，但是 curl 调用的时候一直报 model not found，卡了我快半天。一开始怀疑是网关版本问题，升级了也没解决；后来反复看请求体，发现请求里的 model 字段写的是 gpt-4o，但渠道模型列表里填的是 gpt-4o-mini,gpt-4，并没有 gpt-4o，于是网关拿着这个模型名去上游匹配，自然匹配不到。
这个问题之所以隐蔽，是因为"渠道测试"这个动作只验证上游 Key 是否有效，并不会检查你填的模型列表是否都真实存在。排查链路也很简单：先看网关日志确认请求确实到达了网关，再对比请求模型名与渠道模型列表，最后去上游平台确认该账号是否有权限访问这个模型。经验就一句话：模型名要逐个与上游核对，别想当然。
6.2 坑：日志时间差 8 小时
次遇到这个问题是部署后第二天看调用日志，发现所有请求时间都显示为格林尼治时间，比北京时间慢 8 小时。排查方向很明确，容器默认时区是 UTC，而宿主机是东八区。解决方式也有好几种，我的做法是在 docker-compose 的环境变量里加上 TZ=Asia/Shanghai，然后重建容器。改完之后还需要注意，如果数据库里已经写入了旧日志，时间戳不会自动转换，需要清掉旧日志再观察新的时间戳是否正常。
这个坑很小，但影响却是持续性的。如果你要做按时间段统计的费用报表，时间基准错误会导致报表数据偏差，所以建议部署当天就把时区设置好。
6.3 坑：单机多实例部署直接把 SQLite 搞崩
项目跑了一段时间后，我想做多实例部署来提升可用性，于是在同一台机器上多跑了一个容器。结果没跑多久就报 database is locked 错误，一开始以为是配置问题，后来才意识到是 SQLite 的写入锁机制在多个进程同时写数据库时会出现锁冲突。SQLite 本身就适合单进程读写简单场景，多实例并发写就会出现问题，这是它的天生局限，不是程序 bug。
排查链路是这样的：查看容器日志，发现大量 SQLite 报错，确认是数据库层面的问题；检查官方文档，发现多实例部署要求使用 MySQL 或者 PostgreSQL 作为底层存储。解决方案也很直接，把数据库从 SQLite 迁移到 MySQL，修改 SQL_DSN 环境变量后重启所有实例。
迁移步骤不复杂：先在 MySQL 里建好库，再启动一个仅连接 MySQL 的实例，它会自动建表；然后用 New API 自带的导入导出功能，把原 SQLite 数据导出，再导入到新实例。我实际操作下来整个过程大概十几分钟。所以如果你预见到将来要上多实例，不如第一天就直接用 MySQL，省得后面再返工。
6.4 坑：Nginx 反向代理设置不当导致上传失败
网关本身直接暴露端口可以工作，但生产环境我习惯在前面加一层 Nginx 做 HTTPS 终结和域名转发。结果加了 Nginx 之后，本地 curl 直连网关一切正常，通过域名访问却总是在请求体比较大的时候失败。
排查过程很有意思，我先用 curl 小请求测试通过，然后把消息内容变大，就报 413 Request Entity Too Large。原因是 Nginx 默认限制客户端请求体大小是 1MB，而大上下文对话很容易超过这个限制。解决方式是在 Nginx 的 server 配置里加上一行：
nginx复制client_max_body_size 20m;
重载配置后问题解决。这件事也给我一个提醒：自托管应用放到反向代理后面，很多奇奇怪怪的问题其实是反向代理层自己加上去的限制，排查时要把链路拆成"客户端到 Nginx"和"Nginx 到网关"两段分别验证。
7. 进阶玩法：多实例、备份与持续运维
7.1 备份策略：数据都在哪
New API 的数据核心就是配置信息和调用日志。如果用的是 SQLite，所有数据都在一个数据库文件里，备份方式最简单，定时拷贝 /data 目录下的数据库文件和配置即可。如果用了 MySQL，就靠 mysqldump 做逻辑备份。
我的备份策略是每天凌晨做一次数据库全量备份，保留最近 7 天，同时每周导出一份消费统计数据存到对象存储里，方便做月度对比。下面是我在服务器上挂的定时任务示例：
bash复制0 2 * * * docker exec new-api-mysql mysqldump -uroot -pyourpassword new-api > /backup/new-api-$(date +%Y%m%d).sql
find /backup -name "*.sql" -mtime +7 -delete
另外提醒一点，New API 的渠道配置里包含上游 API Key，属于高度敏感数据，备份文件要注意权限控制，别顺手传到公开仓库里。
7.2 多实例部署与 Redis
如果流量真的上来了，单实例不够用，New API 支持水平扩展。多实例部署的前提是使用 MySQL 作为共享存储，并且接入 Redis 来协调缓存和限流。架构上就是在前面加一个负载均衡，后面挂两个及以上 New API 容器实例，配置相同的环境变量指向同一套 MySQL 和 Redis。
我在这个模式上的经验是：先小范围验证，再放开流量。具体做法是把一个实例先接入，跑一天观察日志和数据库连接，确认没有异常后再逐步增加实例。另外多实例模式下各实例的 SESSION_SECRET 必须保持一致，否则用户在实例间切换登录状态会失效。
7.3 持续运维：版本升级与渠道健康状况
New API 这个项目迭代速度很快，几乎隔一段时间就会发布新版本，修复 bug、增加新渠道支持。升级流程我一般这样做：先在本机 Docker 拉取最新镜像，跑一个临时容器连测试库验证关键功能，确认没问题后再在生产环境执行 docker compose pull 和 docker compose up -d，整个过程业务无感知，因为容器重建很快。
渠道健康监控方面，我除了依赖网关自带的重试机制外，还会额外写一个定时脚本，每隔五分钟调用一次 /v1/models 接口检查网关可用性，如果连续三次失败就通知值班群。这个脚本的逻辑很简单，但确实帮我提前发现了两次上游服务故障，避免了用户大面积投诉。
从我个人的使用体验来说，New API 已经从一个"实验性质的开源工具"变成我日常工作流里的基础设施。如果你也正在被多模型管理的问题困扰，我建议先把最小部署跑起来，接入一个渠道、创建一个令牌、用一个 curl 请求打通全链路，然后逐步迁移业务。随着对控制台的熟悉，你会慢慢发现它真正顺手的地方在于，所有密钥、额度、日志都被收口到一起，那种掌控感是直接用各家厂商控制台完全体会不到的。