New API 中转站操作与运维手册#

基于 QuantumNous/new-api（原 Calcium-Ion/new-api）源码与官方文档整理。
适用场景：自用 / 团队内部 / 企业私有化的 AI API 网关 + 用量与成本管理。
镜像：calciumion/new-api:latest · 默认端口：3000

0 · 文档说明与合规#

合规要点（运维必读）

• 仅使用合法授权的上游 API Key / 账号
• 对外提供生成式 AI 服务时，自行完成备案、内容安全、实名、日志留存等义务
• 生产环境务必修改默认密码、SESSION_SECRET、数据库/Redis 密码

1 · 系统架构（结合源码）#

健康检查（compose 已配置）

GET /api/status  →  期望含 "success": true

2 · 角色与权限#

控制台路径习惯：/console/*（如令牌 /console/token）。

3 · 部署与初始化#

3.1 环境要求#

服务器放哪、买多大：主站默认落在 日本东京源站（香港仅作盾机入口），规格与下单顺序见架构方案 §8 服务器选型。起步常见 2～4C / 4～8G + Docker（Postgres/Redis）；不需要 GPU。
对象存储：生图/附件默认 Cloudflare R2（S3 兼容、出站便宜）；与 S3/B2/OSS/MinIO 等对比见架构 §8.9；API 入口仍走盾机，不要把整站 API 橙云和 R2 图床混为一谈。

3.2 Docker Compose（推荐生产）#

源码自带 docker-compose.yml，默认：

• 应用：calciumion/new-api:latest，端口 3000
• PostgreSQL：root/123456，库 new-api
• Redis：密码 123456
• 数据卷：./data、./logs、pg_data

git clone https://github.com/QuantumNous/new-api.git
cd new-api
# 务必修改密码、SESSION_SECRET 等
nano docker-compose.yml
docker compose up -d
docker compose ps
docker compose logs -f new-api

访问：http://服务器IP:3000 → 首次进入初始化页，设置 Root 账号密码。

3.3 单容器快速体验（SQLite）#

docker pull calciumion/new-api:latest
docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

3.4 生产初始化检查清单#

1. 修改 DB / Redis 密码，勿暴露 5432/6379 到公网
2. 设置 SESSION_SECRET（禁止使用字面量 random_string，程序会拒绝启动）
3. 多机时所有节点 SESSION_SECRET、CRYPTO_SECRET、SQL_DSN、REDIS_CONN_STRING 一致
4. 配置 FRONTEND_BASE_URL=https://你的域名（邮件、回调、前端跳转）
5. Nginx 反代 HTTPS，并配置 WebSocket（Realtime 需要）
6. 打开 ERROR_LOG_ENABLED=true 便于排障
7. 开启 BATCH_UPDATE_ENABLED=true 降低高并发写库压力

3.5 常用运维命令#

# 状态 / 日志
docker compose ps
docker compose logs --tail=200 -f new-api
curl -s http://127.0.0.1:3000/api/status

# 更新
docker compose pull
docker compose up -d
# 滚动：先从节点后主节点（集群时）

# 备份（PostgreSQL 示例）
docker exec postgres pg_dump -U root new-api > backup-$(date +%F).sql

# 停止
docker compose down   # 不加 -v 可保留数据卷

4 · 核心概念：配额、分组、渠道、令牌#

理解这四者关系，是运维与排障的基础。

按量计费公式（源码/文档一致）

配额 = (输入 tokens + 输出 tokens × 补全倍率) × 模型倍率 × 分组倍率

预扣 + 结算：请求前预扣，结束后按实际 token 多退少补。

5 · 功能详解：渠道管理（Admin）#

控制台：渠道管理 · 源码：controller/channel.go、model/channel.go、router/channel-router.go

5.1 渠道字段与运维含义#

5.2 推荐配置流程#

1. 系统设置 → 分组：先建好 default / vip 等
2. 添加渠道：填 Key、BaseURL、勾选/填写模型、选分组
3. 点「测试」：验证连通与延时（controller/channel-test.go）
4. 刷新余额（支持的上游）：监控上游额度
5. 设 Priority/Weight：主渠道高优先级，备用低优先级
6. 修改分组后若路由异常：执行控制台 修复数据库一致性，并刷新相关令牌分组缓存

5.3 路由策略（运维视角）#

「无可用渠道」常见原因

• 令牌分组下没有启用渠道
• 渠道 Models 未包含请求模型
• 渠道被禁用 / 自动封禁
• 分组改了但缓存未刷新

5.4 参数覆盖（高级）#

渠道编辑中的 Param Override 支持 set/delete/move/append 等操作，可按条件改写 body。
用途：强制 stream=true、注入 system prompt、按模型改 max_tokens。
详见官方：渠道管理 / 参数覆盖

6 · 功能详解：令牌管理（用户/Admin）#

路径：/console/token · 源码：model/token.go、controller/token.go

6.1 字段说明#

6.2 创建与使用#

1. 控制台 → 令牌 → 创建
2. 立即复制完整 Key（关闭后无法再看明文，仅掩码）
3. 客户端配置示例：

export OPENAI_BASE_URL="https://你的域名/v1"
export OPENAI_API_KEY="sk-你的令牌"

curl https://你的域名/v1/chat/completions \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}'

6.3 安全运维#

• Key 等同密码：勿提交 Git、勿写进前端公开仓库
• 泄露：立即删除/禁用令牌并新建
• 生产与测试令牌分离；测试用低配额 + 模型限制

7 · 功能详解：用户管理（Admin）#

源码：controller/user.go、model/user.go · 路由：/api/user/*

注册相关运维

• 可关注册、开邮箱验证、Turnstile 防刷（系统设置）
• 新用户初始配额：运营设置
• 邀请码 / 返利：运营设置中的邀请奖励与返利比例

8 · 功能详解：分组管理#

分组是 计费倍率 与 渠道路由 的枢纽。

推荐落地

修改分组后：同步检查渠道归属、令牌分组、倍率 JSON，必要时「修复数据库一致性」。

9 · 功能详解：倍率与计费（Root）#

系统设置 → 倍率设置

9.1 三层倍率#

1. 模型倍率 ModelRatio：模型基础贵贱
2. 补全倍率 CompletionRatio：输出相对输入的倍数
3. 分组倍率 GroupRatio：客户档位折扣/溢价

9.2 运维操作#

1. 为每个实际上线模型配置倍率，避免报错：倍率或价格未配置
2. 可用可视化编辑或 JSON 批量改
3. 支持从上游同步倍率后人工微调
4. 按次计费模型（如部分绘图）：固定价格 × 分组倍率 × 500000

9.3 自查算费#

日志中每条请求有消耗配额；用公式反推是否配置错误。
示例：输入 1000、输出 500、模型倍率 1.25、补全 4、分组 1.0：

(1000 + 500×4) × 1.25 × 1.0 = 3750 配额

10 · 功能详解：系统设置（Root）#

源码选项接口：/api/option（middleware.RootAuth）

环境变量与界面设置分工

• 部署级（DB、Redis、节点角色、超时）：环境变量 / compose
• 业务级（倍率、公告、支付开关）：控制台系统设置

11 · 功能详解：兑换码（Admin）#

路径：兑换码管理 · controller/redemption.go

运维：大额兑换码限制单用户次数；活动码设合理面值与批次名便于审计。

12 · 功能详解：日志、看板、任务#

高日志量可将 LOG_SQL_DSN 指到独立库或 ClickHouse（compose 中有示例）。

13 · 功能详解：中继 API（对外服务）#

源码：router/relay-router.go + controller/relay.go

13.1 常用端点#

另有 Gemini：/v1beta/models 等。

13.2 鉴权#

• Header：Authorization: Bearer sk-xxx
• 部分 Claude/Gemini 客户端用 x-api-key / x-goog-api-key（路由内已分支处理）

13.3 客户端对接注意#

14 · 支付、订阅与充值#

运维：支付回调域名加入可信列表；先小额测通再开放。

15 · 安全与限流#

密钥轮换流程：新建渠道 Key → 测试 → 提高优先级 → 观察 → 删旧 Key。

16 · 集群与高可用#

关键四同

1. 同一 SQL_DSN
2. 同一 REDIS_CONN_STRING
3. 同一 SESSION_SECRET / CRYPTO_SECRET
4. 主 NODE_TYPE=master，从 NODE_TYPE=slave，SYNC_FREQUENCY 如 60s

前面加 Nginx 上游负载均衡；会话靠统一 SECRET + Redis。
扩容：加 slave → 加入 LB → 观察 /api/status 与日志。
更新：先滚动从节点，再主节点。

16.5 · 对接 Sub2API 号池渠道（主副站）#

当需要把 ChatGPT Plus / Claude / Coding Plan 等订阅账号接进来时，推荐用 NewAPI 作主站、Sub2API 作副站：NewAPI 管用户/令牌/计费与渠道编排，Sub2API 专做订阅号池（负载均衡、粘性会话、每账号独立代理）。客户端只连主站。

客户端 → NewAPI（主站）→ 渠道
                         ├─ 官方 / Azure API Key（可选稳仓）
                         ├─ 三方中转（可选兜底）
                         └─ Sub2API（副站，Pro/订阅号池，内网）
                              └─ 每账号独立静态家宽代理 → 上游

编码场景默认（Pro20x）——优先这样配：

可选再加一条低优先级三方中转作 fallback。真 Azure/官方 Key 作后续 vip 稳仓，非编码默认。

通用号池渠道字段：

要点

• 一个 Sub2API 分组（池） 对应一把 Key，建议在 NewAPI 建多条渠道分别对应不同池（Pro20x、Claude…）。
• 副站必须 1 账号 1 静态家宽代理（Sub2API IP 管理）；详见《Sub2API 号池运维手册》§4.4。
• Sub2API 只对主站 IP 白名单开放；主副站数据库与密钥隔离。
• 号池渠道与官方/三方渠道分开监控：订阅失效/封号/代理挂只影响号池渠道，可自动降级。
• 副站部署见《Sub2API 号池运维手册》；编排见《AI 中转站架构方案》§10、§11。

16.6 · 对接 Adobe 生图渠道（Firefly 网关）#

当 AZ / 官方 gpt-image-2 受限时，可用 Adobe Firefly 兼容网关（如 adobe2api、image2api）作生图上游：网关副站把 Firefly 账号池能力暴露为 OpenAI 兼容 API，主站 NewAPI 只配一条渠道。

客户端 → NewAPI → adobe-firefly-image 渠道 →（内网）Adobe 网关副站
                                              → Firefly 账号池（积分）
                                              → GPT Image / nano-banana / Firefly Image…
         └─（可选低优先级）azure-gpt-image-2

NewAPI 渠道示例：

要点

• 与文本 Pro20x 号池分渠道、分分组、分计费倍率。

• Pro20x 不做 4K 生图：gpt-image* / firefly-*-4k-* 只挂本 Adobe（及可选 AZ）渠道；4K 用网关 4k 模型 id，勿映射到 Sub2API。见架构 §11.5。

• 451 / 审核：官方 API、AZ 等模式易内容/地区策略拒绝（含 HTTP 451）；网页逆向 / Firefly 网页通道过图率往往更高。451 与 content_policy 不要对同一渠道死磕重试，应降级到网页线或明确报错。见架构 §12.6。

• 客户端模型名与网关 id 不一致时用映射，勿假设上游就叫 gpt-image-2。

• 确认网关支持的路径：/v1/images/generations 和/或 chat 出图；比例/分辨率参数以网关文档为准。

• 积分耗尽、账号失效要能自动禁用，避免重试打爆。

• 合规：订阅转 API、网页逆向、号池共享风险自担；企业合规优先正式 API（接受更严审核）。

• 架构说明与对比见《AI 中转站架构方案》§12（含 §12.6 审核通道）。

• 对象存储：生图结果转存优先 Cloudflare R2；与 S3/B2/OSS/MinIO 等对比见架构 §8.9；勿把大图长期堆在源站磁盘。

17 · Nginx 反代示例#

server {
    listen 443 ssl http2;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        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 X-Forwarded-Proto $scheme;

        # 流式输出
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;

        # WebSocket (Realtime)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

18 · 日常运维 Runbook#

每日#

• 看看板消耗是否异常尖峰
• 看错误日志 401/429/5xx 是否集中某渠道
• 抽测主模型：chat/completions

每周#

• 批量「测试渠道」
• 核对上游余额与本地消耗
• 备份数据库

变更窗口#

• 改倍率：先小流量令牌验证算费
• 改分组：改完测令牌 + 必要时修一致性
• 升级镜像：pull → 起新容器 → 观察日志 → 保留回滚镜像 tag

19 · 故障排查速查#

20 · 推荐上线最小路径（实操）#

1. Compose 部署 PostgreSQL + Redis + new-api
2. 初始化 Root，改密，开 2FA
3. 系统设置：新用户配额、重试次数、限流
4. 配置模型倍率（至少覆盖要上线的模型）
5. 添加 1 条 default 渠道并测试通过
6. 建测试用户 / 用 Root 建令牌，curl 调通
7. Nginx HTTPS + 域名
8. 再按需开支付、OAuth、多渠道主备

21 · 源码对照速查#

22 · 参考链接#

本文结合 new-api 源码结构与公开文档编写，版本迭代较快，具体字段以你部署的镜像版本文档与控制台为准。