new-api 系列（八）：进阶——多实例、负载均衡与 SSO

new-api多实例负载均衡SSOOIDC进阶教程

系列目录

  1. （一）认识 new-api——新一代 AI API 管理网关
  2. （二）安装部署——从零搭建 new-api
  3. （三）渠道配置——接入各类模型提供商
  4. （四）令牌与用户管理
  5. （五）计价模型与成本控制
  6. （六）监控、日志与告警
  7. （七）生产环境部署与安全加固
  8. （八）进阶——多实例、负载均衡与 SSO（本文）
  9. （九）接入国内支付——支付宝、微信与自动充值
  10. （十）接入国际支付——Stripe、PayPal 与海外收银
# 进阶玩法 ## 多实例渠道 - 多个 CLIProxyAPI / Ollama 实例 - 不同地区、不同账号池 - new-api 优先级 + 权重调度 ## 跨区域部署 - 就近接入 + 降低延迟 - 区域故障自动 failover - 全局负载均衡 ## 单点登录（SSO） - OIDC 协议集成 - GitHub / GitLab OAuth - 企业微信 / 飞书登录 - 统一身份认证 ## 自定义路由 - 根据模型名路由到指定渠道组 - 根据令牌分组路由 - 基于成本的智能调度 ## 生态组合 - new-api + CLIProxyAPI = 订阅转 API 网关 - new-api + Ollama = 本地模型统一入口 - new-api + LiteLLM = 双网关容灾

多实例渠道与跨区域部署

当团队规模扩大到几十人以上，或者需要覆盖不同地区的用户时，单实例 new-api + 单一渠道池可能不够。进阶做法是部署多个上游代理实例作为渠道，让 new-api 在不同实例之间做调度。

场景一：多 CLIProxyAPI 实例作为渠道

你有多个 CLIProxyAPI 实例跑在不同地区，每个实例绑定了不同地区的订阅账号：

渠道名 CLIProxyAPI 地址 账号池 适用地区
CPA-US http://us-proxy:8317/v1 美区 Claude Max x3 北美用户
CPA-HK http://hk-proxy:8317/v1 港区账号 x2 亚太用户
CPA-EU http://eu-proxy:8317/v1 欧区 Claude Pro x2 欧洲用户

在 new-api 中添加三个 OpenAI 兼容渠道，配置相同的模型名，通过权重控制流量分布：

CPA-US：权重 60，优先级 1
CPA-HK：权重 30，优先级 1
CPA-EU：权重 10，优先级 1
flowchart LR RT["new-api 路由引擎"] -->|"权重 60"| US["美区 CLIProxyAPI\n3 个 Claude Max"] RT -->|"权重 30"| HK["港区 CLIProxyAPI\n2 个 Claude Max"] RT -->|"权重 10"| EU["欧区 CLIProxyAPI\n2 个 Claude Pro"] US --> UA["上游 Anthropic"] HK --> UA EU --> UA

场景二：多 Ollama 实例

公司内部有多台 GPU 服务器跑 Ollama，每台加载了不同的模型：

渠道名 Ollama 地址 模型
GPU-1 http://gpu1:11434/v1 llama3:70b, qwen2.5:72b
GPU-2 http://gpu2:11434/v1 codellama:34b, mistral:7b
GPU-3 http://gpu3:11434/v1 llama3:70b（备份）

llama3:70b 在 GPU-1 和 GPU-3 上都有。通过权重在两者之间做负载均衡：

GPU-1：权重 60
GPU-3：权重 40

场景三：跨区域低延迟

对于分布在不同地区的团队，可以在每个区域部署一套 new-api + 上游代理：

flowchart LR U1["北美用户"] --> NA1["new-api-US\nus.api.example.com"] U2["亚太用户"] --> NA2["new-api-HK\nhk.api.example.com"] NA1 --> UP1["美区上游"] NA2 --> UP2["亚太上游"] UP1 <--> UP2["数据库同步\n（可选）"]

每个区域的 new-api 独立运行，用户连接最近的节点。如果需要统一计费，可以让所有实例共享一个 MySQL 数据库（需确保网络延迟可接受）。

OIDC / OAuth 单点登录（SSO）

如果你的团队已经在用企业微信、飞书、GitHub 等平台管理成员，可以通过 OIDC 协议让 new-api 对接这些平台的账号系统，用户不需要单独注册 new-api 账号。

支持的 SSO 方式

平台 协议 说明
GitHub OAuth 用 GitHub 账号登录
GitLab OAuth 用 GitLab 账号登录
企业微信 OAuth 扫码登录
飞书 OAuth 扫码登录
通用 OIDC OIDC 对接任意 OIDC Provider（如 Keycloak、Auth0）

配置 OIDC SSO

后台 →「设置」→「通用设置」→「OIDC 设置」：

字段 说明 示例
启用 OIDC 开关 开启
Provider URL OIDC 发现端点 https://accounts.google.com
Client ID OIDC 客户端 ID xxx.apps.googleusercontent.com
Client Secret OIDC 客户端密钥 GOCSPX-xxx
重定向 URI 回调地址 https://api.example.com/oidc/callback

配置完成后，new-api 的登录页会出现「通过 SSO 登录」按钮。

sequenceDiagram participant U as 用户 participant NA as new-api participant OIDC as OIDC Provider U->>NA: 点击 SSO 登录 NA->>U: 302 重定向到 OIDC Provider U->>OIDC: 登录 / 授权 OIDC->>NA: 回调 code NA->>OIDC: 用 code 换 token OIDC->>NA: id_token + userinfo NA->>NA: 创建/关联用户 NA->>U: 登录成功，跳转面板

SSO 用户权限

通过 SSO 首次登录的用户默认是普通用户角色。管理员可以在后台手动提升为管理员。

可以配置「SSO 自动注册」，让团队成员首次登录时自动创建 new-api 账号，无需管理员手动操作。

自定义路由策略

new-api 的默认路由逻辑是：模型名匹配 → 渠道优先级 → 渠道权重。如果你需要更复杂的路由规则，可以通过渠道组合实现。

策略一：按模型类型分组渠道

# 高成本模型走主渠道（保证质量）
gpt-4o / claude-opus-4-8 → 渠道优先级 1：OpenAI 官方 + Anthropic 官方

# 低成本模型走备份渠道（省钱）
gpt-4o-mini / claude-haiku → 渠道优先级 1：Azure（有额度折扣）

策略二：按用户级别分组

给不同等级的用户创建不同的令牌，每个令牌限制不同的模型：

免费用户令牌：模型限制 = [gpt-4o-mini, deepseek-chat, claude-haiku]
付费用户令牌：模型限制 = 全部模型

策略三：时间段路由

new-api 原生不支持按时间段路由，但可以通过外部脚本定时调整渠道权重实现。例如：

#!/bin/bash
# 白天高峰期：降低昂贵模型的渠道权重
# 夜间低谷期：恢复权重
# 通过 new-api 的管理 API（如果暴露）或直接操作数据库

如果需要复杂的路由策略，大多数场景可以通过渠道优先级 + 权重 + 令牌模型限制的组合来间接实现。

生态组合：new-api 与其他工具的配合

new-api + CLIProxyAPI = 订阅转 API 网关

这是 CLIProxyAPI 系列第六篇详细介绍过的组合，核心思路：

  • CLIProxyAPI：把 Claude Pro / Gemini CLI 等 OAuth 订阅账号转成 OpenAI 兼容 API
  • new-api：在 CLIProxyAPI 前面加一层用户管理、计费、限流

适合没有商业 API Key、只用订阅配额的团队。

flowchart LR T1["成员 A\n令牌 sk-aaa"] --> NA["new-api :3000\n鉴权 / 计费"] T2["成员 B\n令牌 sk-bbb"] --> NA NA --> CPA["CLIProxyAPI :8317\nOAuth 轮询"] CPA --> SUB["Claude Pro x3\nGemini x2"]

new-api + Ollama = 本地模型统一入口

公司内部有多台 Ollama 服务器，每台加载不同模型。用 new-api 统一对外暴露，用户只需要填一个 API 地址。

new-api + LiteLLM = 双网关容灾

两个 AI 网关实例互为主备，Nginx 做健康检查和 failover：

upstream ai-backend {
    server 127.0.0.1:3000 max_fails=3 fail_timeout=30s;  # new-api
    server 127.0.0.1:4000 max_fails=3 fail_timeout=30s;  # LiteLLM（备用）
}

new-api + Cloudflare Tunnel = 零端口暴露

不想在服务器上开公网端口？用 Cloudflare Tunnel 暴露 new-api：

cloudflared tunnel create new-api
cloudflared tunnel route dns new-api api.example.com
cloudflared tunnel run --url http://127.0.0.1:3000 new-api

免去反代、HTTPS 证书的配置，Cloudflare 全包了。

高可用架构总结

当你走到「团队规模 50 人 + 对外提供 API 服务」这个级别时，推荐的完整架构：

flowchart LR U1["内部成员"] --> CF["Cloudflare CDN"] U2["外部客户"] --> CF CF --> NG["Nginx/Caddy\nHTTPS 反代"] NG --> NA1["new-api 主 :3000"] NG -.-> NA2["new-api 备 :3001"] NA1 --> CPA1["CLIProxyAPI-US"] --> SUB["OAuth 订阅\nClaude Pro/Gemini"] NA1 --> CPA2["CLIProxyAPI-HK"] --> SUB NA1 --> API["商业 API\nOpenAI/Anthropic"] NA1 --> OLL["Ollama 集群"] --> LOCAL["本地模型"]

核心原则：

  • 接入层：CDN + 反代，处理 HTTPS 和基础安全
  • 网关层：new-api 做主备，共享 MySQL 数据库
  • 代理层：按地区和账号池分布上游代理
  • 上游：商业 API + 订阅 OAuth + 本地模型，混合使用

系列导航

系列导航

实操清单

  • 添加更多 CLIProxyAPI 实例（当前只有 1 个），实现多账号轮询
  • 为多渠道配置权重（weight，当前两个渠道均为 0，即等权轮询）
  • 为多渠道配置优先级（priority，当前两个渠道均为 0，即同级竞争）
  • 测试渠道故障自动切换：手动禁用一个渠道，确认流量转移到另一个
  • 数据库规模评估：当前 SQLite 612KB，远低于瓶颈，无需迁移 MySQL
  • 磁盘缓存已启用（disk_cache_enabled = true，上限 5GB）
  • （可选）配置 OIDC/OAuth SSO 单点登录（系统设置 → 身份认证，当前未配置）
  • （可选）部署第二个 new-api 实例 + 共享数据库，实现热备