New-API 自部署：搭建你自己的 AI 网关
用 AI 用得多了几乎一定会遇到这些痛点：
- 同时要用 OpenAI / Claude / Gemini / DeepSeek 等十几家 API，每家协议都不一样
- 一个 key 有限额，多个 key 想自动轮询
- 给团队 / 朋友共享，想按人统计用量
- 想统一走 OpenAI 兼容协议，让所有 AI 客户端都能用
New-API 就是解决这一切的工具——开源、自部署、Docker 一键起、Web UI 管理。
一、它能干什么
graph LR
C1[ChatBox] -->|OpenAI 协议| NA[New-API 网关]
C2[Cherry Studio] -->|OpenAI 协议| NA
C3[Cursor] -->|OpenAI 协议| NA
C4[自己代码] -->|OpenAI 协议| NA
NA --> O[OpenAI]
NA --> A[Anthropic Claude]
NA --> G[Google Gemini]
NA --> D[DeepSeek]
NA --> M[Mistral / Groq / ...]
| 功能 | 说明 |
|---|---|
| 协议统一 | 所有上游都被转成 OpenAI 兼容（chat/completions） |
| 多 key 轮询 | 一个上游可以挂 N 个 key，按权重 / 优先级调度 |
| 模型映射 | gpt-4 → 实际走 claude-3.5-sonnet，对客户端透明 |
| 用量统计 | 按 key / 模型 / 用户统计请求数、tokens、费用 |
| 限额配额 | 给每个用户/key 设月配额 |
| 余额管理 | 充值码 / 邀请码 / 签到 |
| 兑换码 | 给朋友发兑换码充值 |
二、对比同类工具
| 工具 | 重点 | 适合 |
|---|---|---|
| New-API | 格式转换、多 key、UI 完善 | 个人 / 小团队通用 |
| gpt-load | 负载均衡、高性能 | 大流量、性能敏感 |
| claude-code-router | Claude Code 模型路由 | Claude Code 用户 |
| CliProxyAPI | 反代 + 接入外部 API | CLI 用户 |
| One-API | New-API 的爹（老版本） | 已停更，不建议 |
💡 个人用 New-API 就够；要服务百万 tokens/天级别才考虑 gpt-load。
三、Docker Compose 部署（SQLite，最简单）
3.1 创建目录
mkdir -p /opt/new-api/data3.2 docker-compose.yml
services: new-api: image: calciumion/new-api:latest container_name: new-api restart: always ports: - "127.0.0.1:3012:3000" # 只绑本机，外网走 nginx environment: - TZ=Asia/Shanghai volumes: - /opt/new-api/data:/data3.3 启动
cd /opt/new-apidocker compose up -ddocker compose logs -f3.4 进阶：MySQL + Redis（多人 / 高并发）
services: new-api: image: calciumion/new-api:latest container_name: new-api restart: always ports: - "127.0.0.1:3012:3000" environment: - TZ=Asia/Shanghai - SQL_DSN=newapi:strong_password@tcp(mysql:3306)/new-api - REDIS_CONN_STRING=redis://redis:6379 volumes: - /opt/new-api/data:/data depends_on: - mysql - redis
mysql: image: mysql:8 restart: always environment: MYSQL_ROOT_PASSWORD: strong_root_password MYSQL_DATABASE: new-api MYSQL_USER: newapi MYSQL_PASSWORD: strong_password volumes: - /opt/new-api/mysql:/var/lib/mysql
redis: image: redis:alpine restart: always volumes: - /opt/new-api/redis:/data💡 个人用 SQLite 就够；多人/团队用 MySQL，性能差距明显。
四、Nginx 反代 + HTTPS
外网必须走 HTTPS，不能直接暴露 3012 端口。
4.1 1Panel 反代
网站 → 创建网站 → 反向代理：
| 字段 | 值 |
|---|---|
| 域名 | api.your-domain.com |
| 代理地址 | http://127.0.0.1:3012 |
| HTTPS | 开 + DNS 自动签 |
4.2 流式响应注意
AI API 大多走 SSE 流式响应，反代必须正确处理：
location / { proxy_pass http://127.0.0.1:3012; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header Connection ''; proxy_buffering off; # 关键：禁用缓冲 proxy_cache off; proxy_read_timeout 600s; # 流式响应可能长 chunked_transfer_encoding on;}🪤 没关
proxy_buffering，AI 输出会一段一段卡住——nginx 把流式响应缓冲到完整再发。
五、首次配置
5.1 创建管理员
第一次访问 https://api.your-domain.com，会让你创建初始管理员账号。用强密码 + 不要用默认用户名 admin / root。
5.2 添加上游渠道
渠道 → 添加渠道：
| 字段 | 值（以 OpenAI 为例） |
|---|---|
| 类型 | OpenAI |
| 名称 | 自取 |
| 分组 | default |
| Base URL | （留空走默认 https://api.openai.com） |
| 模型 | 选要支持的模型（gpt-4 / gpt-3.5-turbo 等） |
| 密钥 | 你的 OpenAI key（一行一个支持多 key） |
| 优先级 | 数字越大优先级越高 |
| 权重 | 同优先级时按权重分配 |
💡 多 key 轮询：密钥框里一行一个 key，New-API 自动按权重 / 优先级调度。
主流上游模板：
| 上游 | Base URL | 备注 |
|---|---|---|
| OpenAI | 默认 | 走代理：填中转地址 |
| Anthropic Claude | https://api.anthropic.com | 类型选 Claude |
| Google Gemini | https://generativelanguage.googleapis.com | 类型选 Gemini |
| DeepSeek | https://api.deepseek.com | 类型选 OpenAI |
| Groq | https://api.groq.com/openai | 类型选 OpenAI |
| 月之暗面 | https://api.moonshot.cn | 类型选 OpenAI |
5.3 渠道测试
加完之后点渠道列表的”测试”按钮，验证 key 是否能用。
六、用户和令牌
用户 → 添加用户：
| 字段 | 用途 |
|---|---|
| 用户名 / 密码 | 登录 |
| 分组 | 控制能用哪些渠道 |
| 额度 | 上限（单位：tokens 或自定义单位） |
令牌 → 添加令牌：
| 字段 | 用途 |
|---|---|
| 名称 | 区分用途 |
| 额度 | 这个令牌的上限 |
| 过期时间 | 可选 |
| IP 白名单 | 可选 |
| 模型限制 | 限制只能用某些模型 |
生成的令牌 sk-xxxxxx 就是你给客户端用的 API key。
七、客户端接入
任何支持 OpenAI 兼容协议的客户端都能接：
ChatBox
| 字段 | 值 |
|---|---|
| API Provider | OpenAI |
| API Host | https://api.your-domain.com |
| API Key | 你的 New-API 令牌 sk-xxx |
| Model | 渠道里启用的模型 |
Cherry Studio
| 字段 | 值 |
|---|---|
| 模型服务 | OpenAI |
| API 域名 | https://api.your-domain.com/v1 |
| API 密钥 | sk-xxx |
Cursor
设置 → Models → Override OpenAI Base URL：
| 字段 | 值 |
|---|---|
| URL | https://api.your-domain.com/v1 |
| API Key | sk-xxx |
自己代码
from openai import OpenAI
client = OpenAI( api_key="sk-your-newapi-token", base_url="https://api.your-domain.com/v1",)
resp = client.chat.completions.create( model="gpt-4", messages=[{"role": "user", "content": "hi"}],)print(resp.choices[0].message.content)八、模型映射（关键功能）
让客户端以为自己在用 gpt-4，实际请求转发给 claude-3.5-sonnet：
渠道编辑 → 模型重定向：
{ "gpt-4": "claude-3.5-sonnet", "gpt-3.5-turbo": "deepseek-chat"}之后客户端请求 gpt-4，New-API 自动转给 Claude。
💡 这功能特别适合绕过客户端的模型白名单——Cursor 只支持 OpenAI 模型？用 New-API 把
gpt-4映射到 Claude，照常用 Claude。
九、监控和统计
监控 页面看：
- 各模型 24h / 7d / 30d 调用量
- 各用户消耗
- 各渠道成功率
- 实时请求日志
发现有渠道大量失败要立刻去渠道列表看 key 是不是炸了。
十、踩坑清单
| 现象 | 原因 | 解决 |
|---|---|---|
| 流式响应一段段卡 | nginx 没关 buffering | proxy_buffering off |
| 上游 401 | key 失效 / 上游封号 | 渠道测试 + 换 key |
| 重启后用户数据没了 | volume 没挂 / 改了路径 | 检查 volumes |
| 国内 VPS 拉 OpenAI 超时 | 需要走代理 | Docker daemon 配代理 或 上游填中转 URL |
| 流量监控不准 | tokens 计算和上游略有差 | 看趋势别看绝对值 |
| 模型映射不生效 | JSON 格式错 | 用合法 JSON |
| 兑换码总是失效 | 兑换码有过期时间 | 别批量生成放半年才发 |
十一、安全加固清单
⚠️ AI 网关一旦被打穿 = 别人用你的 key 烧你的钱。安全比功能更重要。
- 管理员账号用强密码 + 2FA
- 绑定 IP 限制管理员登录（New-API 设置里有）
- 令牌设过期时间，过期自动失效
- 渠道按需启用模型，别把所有模型都给所有人
- 设月度配额上限，被滥用也烧不光
- 监控异常调用模式：突然某个令牌每分钟几百次请求 = 出问题了
- 数据库定期备份：SQLite 直接 cp 文件 / MySQL 用 mysqldump
- 不要把令牌 commit 到 GitHub
十二、几条实用经验
- 个人用 SQLite 就够：MySQL 是过度设计。
- 多 key 轮询 + 优先级 是杀手锏，给主 key 优先级 10、备用 key 优先级 5。
- 模型映射 比折腾客户端配置好太多——一次设置，所有客户端通用。
- 令牌按用途分：写代码一个 key、Cursor 一个 key、共享给朋友一个 key，出事能精准吊销。
- DeepSeek + Claude + Gemini 三家配齐，覆盖 95% 场景且性价比最佳。
- 定期清日志：跑久了日志表会很大，进数据库手动
DELETE FROM logs WHERE created_at < ...。
跑起来之后你会发现 AI 的使用体验大幅提升——所有客户端共用一套 key，所有模型一个入口，所有用量一目了然。