结论先行:只要你在两个以上 LLM 供应商(或同一家的多个账号/key)之间做选择,就该在前面放一个统一网关。new-api 是 one-api 的活跃分支,提供 OpenAI 兼容端点、渠道管理、令牌分发、额度计费和失败重试。对所有应用来说只有一个 OpenAI 格式的 base_url 和 key,供应商切换、key 池、用量统计全部收在网关层。

痛点对号入座

没有网关时的典型困境:每个应用硬编码各家的 SDK 和 key;某家限流了要逐应用换配置;想比较两个模型的效果,成本数据散在各处对不上;团队共用一个 key,用量、限额、审计全无从谈起。这些问题的解法在后端工程里是现成的——API 网关模式,new-api 就是 LLM 领域的 Kong。直连与网关的差别逐项对比:

维度直连各家 API统一网关
接入成本每应用集成各家 SDK 与 key应用只认一个 OpenAI 格式端点
供应商切换逐应用改代码/配置改渠道配置,应用无感
限流应对手工迁移流量多渠道自动重试与切换
用量统计散落各处,口径不一按令牌/渠道统一聚合
key 泄漏止损轮换所有上游 key重签单个令牌即可
审计与限额基本无从谈起令牌级额度、模型范围、日志

判断标准很简单:个人玩票直连即可;多人、多应用、多供应商中占任意两个,网关就从可选变成必选。

部署:一个 docker-compose

new-api 部署很轻,默认 SQLite 即可起步(生产建议接 MySQL/PostgreSQL):

services:
  new-api:
    image: calciumion/new-api:latest
    container_name: new-api
    restart: always
    ports:
      - "3000:3000"
    environment:
      - TZ=Asia/Shanghai
      # 生产环境建议外部数据库
      - SQL_DSN=root:password@tcp(mysql:3306)/new-api
    volumes:
      - ./data:/data

渠道与令牌:两个核心概念

起来之后访问 3000 端口进管理台,两个核心概念要先分清:

  • 渠道(Channel):上游。一家供应商或一个中转站是一个渠道,配置上游 base_url、key、支持的模型列表、权重与优先级。同模型可配多渠道实现负载均衡和故障切换。
  • 令牌(Token):下游凭证。发给每个应用/每人一个令牌,可设额度上限、过期时间、可用模型范围。应用拿令牌访问网关,网关再选渠道转发。

两者的关系可以用一句话固定:渠道管上游资产,令牌管下游边界。上游 key 是共享资产,令牌是给每个应用切分出去的权限切片——任何一处泄漏都靠令牌粒度来止损,泄漏后重签令牌即可,不用轮换所有上游 key。新接一个应用的标准动作因此可以固定成三步:领一个独立令牌(设额度和模型范围)、应用配置指向网关地址、管理台里确认该令牌的用量曲线正常。三步之外不需要动任何渠道配置——渠道是平台管理员的领域,应用永远不碰。

概念方向配置内容作用
渠道对上游base_url、上游 key、模型列表、权重优先级供应商管理、负载均衡、故障切换
令牌对下游额度上限、过期时间、可用模型范围应用边界、限额、审计、泄漏止损
模型映射两者之间上游模型名 → 规范模型名对应用统一命名,切换透明

接入方式:OpenAI 兼容

应用侧只需把 base_url 指向网关,key 用网关签发的令牌。绝大多数工具链和 SDK 都兼容 OpenAI 格式,这也是选这类网关而不是各家原生 SDK 的关键原因——换模型不改代码:

curl http://gateway.internal:3000/v1/chat/completions \
  -H "Authorization: Bearer sk-team-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "ping"}]
  }'

对比错误写法与正确写法——问题不在能不能跑,在泄漏面和止损速度:

# 错误写法:上游 key 直接下发到每个应用的环境里
export OPENAI_API_KEY=sk-upstream-real-key     # 每个应用都拿着真 key
export ANTHROPIC_API_KEY=sk-ant-real-key       # 换供应商 = 全员换配置
# 任何一台机器泄漏,只能轮换全部上游 key,所有应用一起重配

# 正确写法:应用只见网关令牌,上游 key 只存在网关配置里
export OPENAI_BASE_URL=http://gateway.internal:3000/v1
export OPENAI_API_KEY=sk-team-ci-xxxx          # 网关签发,带额度和模型范围
# 泄漏只需在管理台重签这一个令牌;换供应商改渠道配置,应用零改动

实践要点

模型名统一规划。 渠道配置里可以做模型映射(上游叫什么不重要,对应用统一暴露规范名)。给团队定一份模型命名规范,渠道增删、上游切换对应用透明。

故障切换靠多渠道。 同一个模型挂两个渠道(不同供应商),上游限流或宕机时网关自动重试下一个渠道。注意在网关侧设置合理的超时和重试次数,避免把延迟放大。

额度与成本看板。 按令牌维度看用量,每个应用的 token 消耗、按渠道看上游花费。做 Agent 平台的团队尤其需要:一篇任务花多少钱,要先有数据才能谈优化。

别把网关当关键路径依赖。 网关挂了所有 AI 应用一起挂,所以它自身要做高可用(容器重启策略 + 数据库外置 + 备份)。反过来,它的延迟开销(一层反代 + 计费记录)相对 LLM 秒级的响应时间可以忽略。

令牌即权限边界。 按应用分发令牌,别共用一把管理员令牌到处塞。给 CI 流水线的令牌只勾选它用的模型并设月度额度,给实验项目的令牌设过期时间。

两条补充提醒。一是合规视角:所有请求内容都会经过网关,网关日志里天然存在 prompt 与响应的记录——如果业务涉及敏感数据,网关日志的存储位置、保留期、访问权限要和安全团队对齐,别把它当成无状态的转发层对待。二是升级纪律:new-api 社区迭代很快,升级前备份外置数据库、先在测试实例上验证渠道配置兼容性,网关是所有 AI 应用的单点,它的故障半径值得用一次预演来量化。

一句话总结选型逻辑:个人玩票可以直接用各家原生接口;只要涉及多人、多应用、多供应商中的任意两个,网关就是必选项,new-api 是这个位置上社区里最常被选的开源答案之一。

实战场景

一个十来人的工程团队的接入过程:早期各家 key 以"发一个环境变量文件"的方式散在七八个应用里,某次一家供应商突发限流,团队花了一下午逐应用改配置切换——第二天就下单了 new-api。部署半小时完成,配置了两个渠道(主供应商 + 备用中转)做同模型互备,给 CI、内部平台、实验项目各签了一个令牌并设了月度额度。一个月后的收益清单:供应商侧的一次故障被多渠道自动切换消化,应用侧无人感知;管理台第一次给出"哪个应用花了多少"的排行,实验项目因额度触顶被自然限额,反而促成了模型分级改造;期间一个实验项目的令牌误提交进了公开仓库,处理动作只是在管理台禁用并重签,上游 key 全程无恙(以上为过程描述,具体用量数字从略)。团队事后把"新应用接入必领独立令牌"写进了规范——权限边界靠流程固化,而不是靠自觉。

检查清单

  • 应用侧只持有网关令牌,上游 key 只存在于网关渠道配置中
  • 每个应用/每人独立令牌,按需设额度上限、过期时间、可用模型范围
  • 模型名统一规范,通过渠道映射对应用暴露,切换供应商不改代码
  • 同一模型至少配两个渠道(不同供应商)做故障切换,并设合理超时重试
  • 生产环境外置数据库并纳入备份,网关自身按关键依赖做高可用
  • 每月按令牌与渠道两个维度核对用量与花费
  • 令牌泄漏预案:管理台即时禁用重签,无需轮换上游 key