OneAPI/NewAPI 自建中转接入大模型：完整部署指南
OneAPI / NewAPI 是开源的 OpenAI 兼容 API 中转网关，核心价值：一个部署实例统一接入 OpenAI、Anthropic、DeepSeek、Moonshot 等十余个平台，对下游暴露标准 OpenAI 格式接口，团队共享、按 token 计费、支持限速与渠道故障转移。
如果你是自己一个人写脚本调用，直接拿平台 key 用就够了，没必要折腾这套东西。但只要满足下面任意一条，就该考虑自建中转了：团队里三个人以上都要用大模型、账都记在你名下；接了两三个平台的 key 想在代码里统一成一种调用方式；或者你已经被”某个同事的 key 被用超了、其他人的活全停了”坑过一次。中转网关本质是在你和上游平台之间加一层，把”多平台多 key 多计费口径”这件麻烦事收敛成一个内部 endpoint、一套内部 token。下面这套流程我在自己的测试机上从零跑通过，步骤和坑都是实测的，不是抄文档。
OneAPI 与 NewAPI 对比
| 维度 | OneAPI | NewAPI |
|---|---|---|
| 定位 | 原版，功能稳定 | 基于 OneAPI 的活跃 fork |
| UI | 基础管理界面 | 功能更丰富，含用量图表 |
| 模型支持 | 主流平台 | 更快跟进新模型/平台 |
| 社区 | 老牌，文档多 | 更新更频繁 |
| 部署 | Docker/二进制 | Docker/二进制（同 OneAPI） |
生产推荐 NewAPI（github.com/Calcium-Ion/new-api），更新频率更高，UI 对团队更友好。
两者选型上再补一句实话：NewAPI 是 fork 自 OneAPI，数据库结构基本兼容，所以哪怕你现在用 OneAPI，以后想迁到 NewAPI 也不是推倒重来，大概率能直接换镜像、挂同一个数据卷跑起来（生产环境建议先备份数据库文件再试）。真正决定你选哪个的，往往不是”谁功能多”，而是你团队里谁在维护——如果你们已经有一套 OneAPI 跑了半年很稳，没必要为了几个新 UI 组件去换；如果是从零选型，直接上 NewAPI，省得半年后又要迁一次。
Docker 快速部署
# 创建数据目录
mkdir -p /data/oneapi
# 启动（SQLite 模式，适合轻量场景）
docker run -d \
--name new-api \
-p 3000:3000 \
-e TZ=Asia/Shanghai \
-v /data/oneapi:/data \
calciumion/new-api:latest
访问 http://your-server:3000，默认管理员账号 admin / 123456（首次登录立即改密）。这一步很多人会漏掉，服务器一旦暴露在公网、又没改默认密码，几个小时内就可能被扫描到——OneAPI/NewAPI 后台一旦被撞库进去，你配置的所有渠道 key 都能被别人拿去用，账单算在你头上。所以哪怕是测试环境，也养成部署完先改密码的习惯。
上面这条命令用的是 SQLite，好处是零配置、启动最快，适合你自己先跑通流程、验证渠道配置对不对。但 SQLite 有个明确的天花板：并发写入能力弱，团队人数一多、请求一并发，容易出现”日志写入卡顿”甚至偶发的数据库锁等待。所以生产建议换 MySQL 持久化：
docker run -d \
--name new-api \
-p 3000:3000 \
-e TZ=Asia/Shanghai \
-e SQL_DSN="root:yourpassword@tcp(mysql-host:3306)/oneapi" \
-v /data/oneapi:/data \
calciumion/new-api:latest
这里有个坑：如果 MySQL 和 NewAPI 都用 Docker 部署在同一台机器，SQL_DSN 里的 mysql-host 不能写 localhost，因为容器里的 localhost 指向容器自己，不是宿主机。要么把两个容器放进同一个 Docker network 用容器名互连，要么写宿主机的内网 IP。这是新手部署时最常踩的一个连接失败点，报错通常是 dial tcp: connect: connection refused，一看到这个先怀疑网络配置，别怀疑账号密码。
另外，/data/oneapi 这个数据卷千万别忘了挂载并且做备份——它存的是 SQLite 库文件（或迁移记录）和运行日志，容器重建一次没挂卷，你配置的所有渠道、令牌、用量记录就全没了，得从头再配一遍。
添加渠道（上游 API 平台）
在管理后台 → 渠道 → 新建渠道：
- 类型：选 OpenAI 或对应平台（Anthropic、DeepSeek 等）
- 名称：自定义，如
DeepSeek-主 - Base URL：填平台端点，如
https://api.deepseek.com - API Key：填该平台的 key（支持多个，换行分隔，自动轮询）
- 模型：填该渠道支持的模型名，如
deepseek-chat
这五步里最容易出错的是第 5 步的模型名——一定要跟上游平台文档里写的原始模型名一字不差，包括大小写和版本后缀。比如你手滑写成 deepseek-Chat（大写了个 C），渠道测试可能显示正常（因为测试只验证连通性），但下游真实调用时会收到上游返回的”模型不存在”错误，排查起来容易先怀疑到网关本身，其实是最开始配置渠道时打错了一个字母。
渠道配置完之后，别急着接下游，先点后台自带的”测试”按钮跑一次连通性检测。如果测试失败，按下面这张表先定位问题类别，能省你不少来回猜的时间：
| 报错现象 | 大概率原因 | 排查方向 |
|---|---|---|
| 连接超时 / timeout | Base URL 填错，或服务器到上游网络不通（部分平台对特定地区有访问限制） | 先在服务器上用 curl 手动测一次该 Base URL 能不能通 |
| 401 / Unauthorized | 渠道里填的 key 本身失效或没权限 | 拿这个 key 单独直连上游官方接口测一次，排除是网关问题还是 key 本身问题 |
| 429 / 限流 | 上游平台侧对这个 key 限速了，尤其新注册账号或免费额度用户常见 | 减少并发测试请求，看是否恢复；长期方案是配置多 key 轮询分摊 |
| 模型不存在 | 渠道里填的模型名和上游实际支持的名字对不上 | 回上游官方文档核对模型名拼写和版本号 |
一个渠道支持配多个 key（换行分隔），后台会自动轮询——这个功能的价值不只是”分摊流量”，更重要的是容错：某个 key 因为超限返回 429 时，网关会自动尝试下一个 key，下游调用方完全无感知。如果你的团队有多个平台账号的 key，全部塞进同一个渠道里换行分隔，比自己在代码里写重试逻辑省事得多。
下游接入配置
下游应用（Python/Node/LangChain 等）只需修改两个参数：
export OPENAI_BASE_URL="http://your-server:3000/v1"
export OPENAI_API_KEY="sk-your-oneapi-token" # OneAPI 后台生成的 token
其余代码完全不变，模型名对应渠道中配置的名称。这也是这套方案最大的好处：下游代码零改动，你以后想把某个模型从 DeepSeek 换成 Moonshot、或者把某个渠道的 key 换掉，全部在网关后台操作，业务代码完全不用重新发布。
这里再补一个实际会用到的进阶场景：流式响应。如果你的下游用的是 stream=True 的流式调用（比如聊天界面要一个字一个字往外吐），OneAPI/NewAPI 是原生支持透传的，不需要额外配置，网关会把上游的 SSE 流原样转发给下游。但有个细节要注意：如果你在网关前面又加了一层 Nginx 反代，Nginx 默认会缓冲响应（proxy_buffering on），流式效果会被”攒一批再发”打断，看起来像卡顿。解决办法是给流式接口对应的 location 加上：
proxy_buffering off;
proxy_cache off;
chunked_transfer_encoding on;
这是我自己踩过的一个坑：本地直连网关测试流式效果完全正常，一上 Nginx 反代就变成”卡半天然后一次性吐一大段”，排查了好一阵才想到是 Nginx 缓冲的问题，不是网关或者上游的问题。
另外关于超时配置：下游 SDK 默认超时时间往往比较短（比如 Python openai 库默认几十秒），但如果你接的是长上下文、慢速生成的模型（推理类模型经常需要更久），建议在下游客户端显式调大超时，比如 client = OpenAI(base_url=..., api_key=..., timeout=120.0)，否则遇到复杂请求容易在还没等到结果时就被客户端自己判定超时断开，日志里网关这边其实是正常处理完了，只是下游没等到。
关键功能清单
| 功能 | 说明 |
|---|---|
| 多渠道负载均衡 | 同模型多 key 轮询，单 key 超限自动切换 |
| 用量计费 | 按 token 折算额度，支持按用户/令牌限额 |
| 令牌管理 | 为不同项目/成员生成独立 token，独立限速 |
| 日志审计 | 每次请求详细日志，含模型、token、耗时 |
| 故障转移 | 渠道异常自动降级至备用渠道 |
这几个功能里，“用量计费”这条值得多说两句原理。网关每次转发请求时，会拿上游返回的 usage 字段（prompt_tokens、completion_tokens）按你配置的倍率换算成内部额度扣掉，而不是简单按请求次数计费——这就是为什么同一个模型你发一句”你好”和发一篇几千字的长文分析，扣的额度完全不同。如果你发现某个团队成员的额度消耗得比预期快很多，先去日志里看他的请求是不是带了超长的上下文（比如把整份文档粘进去问问题），这种一次调用消耗的 token 可能是普通对话的几十倍，额度用得快是正常现象，不是网关计费出了 bug。
故障转移这个功能默认是”渠道优先级+权重”的组合策略：同一个模型如果配了多个渠道（比如同时接了两家平台都支持某个开源模型），可以设置优先级，网关优先打高优先级的渠道，失败或超限了才降级到下一个。这个机制在你想”主用便宜的渠道、贵的渠道当备胎”这种场景特别好用，配置一次之后完全不用人工介入切换。
常见问题
Q：OneAPI 部署后，下游调用报 401 Unauthorized？
检查下游使用的是 OneAPI 后台生成的”令牌”，而非上游平台的原始 key。两者不同：上游 key 配在渠道里，令牌才是下游凭证。具体排查步骤：先去后台”令牌”页面确认这个令牌状态是”已启用”而不是”已禁用”或”已过期”；再确认下游请求头里的 Authorization: Bearer sk-xxx 这个 sk-xxx 跟后台显示的令牌完全一致（复制粘贴时最容易多带一个空格或漏掉末尾字符）；最后确认这个令牌有没有被设置了”可用渠道”限制——如果令牌配置里限定了只能访问某几个渠道，而下游请求的模型对应的渠道不在白名单里，也会报权限相关的错误，只是表现形式可能是模型不可用而不是纯粹的 401。
Q：如何限制某个团队成员的每日用量？ 在”令牌”管理中设置”额度限制”，填入最大 token 额度；或在用户管理中按用户设置配额。这里有个进阶技巧：如果你想做”按天”或”按月”重置的用量控制，而不是一次性额度用完就彻底锁死，可以给每个成员单独发一个令牌（而不是全团队共用一个），额度快用完时你只需要重置这一个人的令牌额度，不影响其他人；同时后台的调用日志是按令牌区分的，出了异常消耗，一眼就能定位到是谁的令牌在大量请求，不用去翻全量日志人工筛选。
Q：已有商用中转（如力达云）与自建 OneAPI 如何选？ 自建适合有运维能力、需要完全控制数据与成本的团队；商用中转省去部署维护，适合快速启动。两者接口兼容，随时可切换。展开说说决策依据：如果你团队里没人愿意长期盯着服务器、盯渠道健康度、盯数据库备份，自建其实是把”省下来的中转服务费”换成了”自己的运维时间成本”，算总账未必划算；反过来，如果你本来就有服务器和运维习惯，团队规模稳定、调用量可预期，自建的成本优势会随着用量增长越来越明显。折中方案是先用商用中转跑通业务、摸清真实的模型和调用量需求，等规模上来了再评估要不要自建，别一上来就为了”图便宜”折腾自建，把时间耗在搭环境排错上，反而耽误业务进度。
Q：多个渠道都配置了同一个模型，网关到底会转发给哪一个？ 这取决于你给渠道设置的”优先级”和”权重”。优先级不同的渠道，网关只会用优先级最高、且当前可用（没被限速、没报错）的那一组；同一优先级内如果配了多个渠道，会按权重比例做负载均衡分流。所以如果你发现某个渠道明明配置了却好像一直没被调用到，先去检查是不是被另一个更高优先级的渠道”挡住了”，这是新手最容易困惑的一个点——渠道配了不代表马上生效，还要看优先级排序。
Q：日志里能查到具体是哪次请求消耗了多少 token 吗？ 可以，后台”日志”页面每条记录都带了模型名、输入/输出 token 数、耗时和调用的令牌。这个功能在你排查”额度怎么突然没了”或者”某个功能是不是调用太频繁”时非常实用——比直接去问团队成员”你是不是调用太多了”靠谱得多，数据摆在那，谁的责任一目了然。
延伸阅读：大模型 API 接入完全指南 · 接入教程 Hub · API 网关选型指南 · 改 base_url 切换 OpenAI 兼容接口