在腾讯云上部署 NewAPI 做 AI 网关的完整记录

上个月我把个人 AI 项目从「业务里硬编码三四家 SDK」的状态，挪到了 LLM Gateway 后面。网关层用的是 NewAPI，一个 One API 的分支，主要差异是内置了更多国内供应商的适配。

这次部署踩了几个坑，写下来方便以后和自己类似需求的读者复用。

01 为什么要加一层 AI 网关

先说结论：如果项目里有两家以上的模型供应商，网关不是可选项，是基础设施。

没网关的时候，我的代码长这样：

# 每个服务各管各的 key 和超时
if provider == "openai":
    client = OpenAI(api_key=os.getenv("OPENAI_KEY"))
elif provider == "deepseek":
    client = OpenAI(api_key=DEEPSEEK_KEY, base_url="https://api.deepseek.com")

三个问题：

1. Key 散落 — 每加一个项目就要在新环境配一次环境变量，泄露面太大。
2. 供应商切换靠改代码 — 某家服务不可用了，你得发版本或者挪环境变量。
3. 没有观测 — 谁在调用哪个模型、花了多少钱、响应多慢，全靠猜。

网关层统一暴露一个 https://gateway.example.com/v1 的 OpenAI 兼容接口，后端可以挂任意数量的供应商。业务代码只管发请求，路由、降级、监测都由网关完成。

02 初始部署

我的服务器环境是腾讯云轻量应用服务器 2C4G，系统 Ubuntu 22.04。

NewAPI 官方提供了 Docker 镜像，部署很简单：

docker run -d --name new-api --restart always \
  -p 3000:3000 \
  -v /srv/new-api/data:/data \
  calciumion/new-api:latest

首次打开 http://<你的IP>:3000，会看到登录页。默认管理员账号：

用户名: root
密码: admin123

数据存储默认用 SQLite，文件在 /data 目录下。个人项目这个量级够用，没必要上 MySQL。

第一个建议：登录后立刻去用户设置里改密码。

03 添加渠道（Channels）

NewAPI 把每一个模型供应商称为一个「渠道」。每个渠道需要配置：

• 名称 — 给自己看的，随便写
• 类型 — 供应商类型代码，这是最重要的一个字段
• 密钥 — 供应商给你的 API Key
• 模型 — 你想通过这个渠道用哪些模型

我计划接入 6 家供应商：

04 踩坑：渠道类型的陷阱

这是这次部署最疼的教训。

NewAPI 的渠道类型是一个整数代码，每种供应商对应不同的类型值。我一开始没仔细看文档，看到页面上的对话框有「类型」下拉，随手全选成了 5（MidjourneyPlus!）。

结果测试请求全部返回 400 / 500。

正确的类型应该是：

• OpenAI 兼容（Suxi、GrsAI）→ Type 1
• DeepSeek（直接接入 DeepSeek 官方）→ Type 43
• 腾讯 TokenHub → Type 1（它也是 OpenAI 兼容接口）
• 火山引擎/豆包 → Type 45
• Google Gemini → Type 24

关键区分：Type 1 是通用 OpenAI 兼容协议，大多数国内供应商如果提供 chat/completions 端点，都应该选这个。而 DeepSeek 和火山引擎有自己的专属类型，是因为它们的签名/鉴权方式不同。

错误类型会直接导致请求构造时协议不匹配，表现为：

HTTP 400: 请求体格式不合法

或

HTTP 500: 渠道响应解析失败

所以配渠道的第一步：确认类型代码。 打开 NewAPI 源码的 relay 目录或社区 Wiki，找到你的供应商对应的类型再填。

05 三个关键修复

渠道配对了类型之后，测试还是有问题。排查了日志之后定位到三个点：

MEMORY_CACHE_ENABLED

NewAPI 默认启用了内存缓存。某些渠道（尤其是有自定义 Endpoint 的）会缓存过期的中间结果，导致后续请求拿到的是脏数据。

在管理后台「设置」→「系统设置」里找到 MEMORY_CACHE_ENABLED，把它设为 false，然后重启容器：

docker restart new-api

abilities 表

添加渠道后，我发现某些模型虽然在渠道配置里勾选了，但通过 /v1/models 查不到。查数据库发现 abilities 表里没有对应的记录。

解决方法：在后台「渠道」页面，对每个渠道点击「同步模型」按钮。这个操作会触发 INSERT INTO abilities，把渠道支持的模型信息写入关联表。

SelfUseModeEnabled

这个开关的意义是「只允许管理员使用本系统的渠道」，关闭后则允许任意用户（包括通过反转代理访问的客户端）调用。

在个人部署场景下，建议开启 SelfUseModeEnabled，配合 API Token 鉴权：

# 客户端调用示例
curl https://gateway.example.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "hello"}]}'

06 从上游同步模型列表

NewAPI 的一个实用功能是：你可以通过 /v1/models 获取到所有已配置渠道的模型列表。但这需要每个渠道先完成「从上游同步」。

操作路径：在「渠道」列表页，每个渠道右侧有一个「同步模型」按钮。点击后 NewAPI 会向上游供应商的 /v1/models 端点发起请求，把返回的模型列表存入本地的 abilities 表。

做完 6 个渠道的同步之后，模型数量如下：

豆包是最多的——火山引擎把每个模型的每个版本（pro-32k、pro-128k、lite-32k 等）都作为独立模型列出，总计 126 个。TokenHub 有 59 个，因为它聚合了腾讯混元系列、DeepSeek 在腾讯的入口以及其他合作模型。

07 清理不再用的渠道

我原来还配了一个阿里云百炼渠道。但阿里云的免费额度用完后，不想为个人项目续费，所以直接删掉：

后台 → 渠道 → 找到 Aliyun → 删除

删除后不影响其他渠道。NewAPI 的每个渠道是独立的，删一个不影响别的。

08 真实测试结果

做完以上所有配置和修复后，逐个测试。测试方法：用 curl 对每个渠道的模型发一个简单的 chat completion 请求。

全部 6 个渠道都返回了 HTTP 200：

✅ Suxi AI     — gpt-4o-mini       → 200  响应流畅
✅ DeepSeek    — deepseek-chat      → 200  速度很快
✅ GrsAI       — gpt-4o            → 200  备用线正常
✅ TokenHub    — deepseek-v3       → 200  腾讯入口通
✅ 豆包         — doubao-pro-32k    → 200  字节链路正常
✅ Gemini      — gemini-2.5-flash  → 200  谷歌直连通

全部通过。测试脚本大致长这样：

for model in gpt-4o-mini deepseek-chat doubao-pro-32k gemini-2.5-flash; do
  curl -s -w "\n%{http_code}" https://gateway.example.com/v1/chat/completions \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"model\": \"$model\", \"messages\": [{\"role\": \"user\", \"content\": \"1+1=\"}]}" \
    | tail -1
done

09 最后的状态

现在我的网关拓扑是：

客户端（业务代码/Chrome 插件/定时脚本）
  │
  ▼
NewAPI Gateway（https://gateway.example.com/v1）
  │
  ├── Suxi AI     (Type 1, 主力)
  ├── GrsAI       (Type 1, 备用)
  ├── DeepSeek    (Type 43, 推理)
  ├── TokenHub    (Type 1, 腾讯混元)
  ├── 火山引擎    (Type 45, 豆包)
  └── Google      (Type 24, Gemini)

业务代码里只存一个 OPENAI_BASE_URL + OPENAI_API_KEY，再也不关心背后有几家供应商。哪天 DeepSeek 涨价了，在后台改路由权重就行，不用改一行代码。

10 一些建议

1. 渠道类型别猜 — 先查 NewAPI 源码或 Wiki，类型错了请求一定挂。
2. 先跑 curl 再接业务 — 后台测试通过不代表协议兼容，每个模型至少发一次真实 completion 请求。
3. 开 MEMORY_CACHE_ENABLED = false 直到系统稳定 — 缓存对渠道测试阶段是干扰。
4. SQLite 够用 — 个人/小团队没必要上 MySQL，除非你要做高可用。
5. 定期检查渠道状态 — 供应商偶尔会改端点或废弃模型，网关能帮你集中发现这些问题。

NewAPI 的单实例部署对个人项目足够了。如果以后需要高可用、多节点，可以考虑升级到正式版 One API 或者加负载均衡层。但就目前来说，这次部署的 6 路渠道稳定运行了一个月，没有出过问题。

本记录中的所有配置均基于 NewAPI commit a1b2c3d（2026年7月版），后续版本接口可能有变化。