深入解析 New API：下一代大模型网关的架构设计与实现
一个聚合 40+ AI 服务商的统一网关是如何设计的？本文将从架构、设计模式、技术选型等维度全面剖析 New API 项目。
前言
在 AI 应用开发中，我们经常面临一个痛点：不同的 AI 服务商有着不同的 API 格式、认证方式和计费模式。OpenAI、Claude、Gemini、Azure、AWS Bedrock... 每接入一个新平台，都意味着重新学习一套 API 规范。
New API 正是为了解决这个问题而诞生的------它是一个下一代大模型网关与 AI 资产管理系统，将 40+ 家 AI 服务商统一在一个标准化的 API 接口之后，让开发者只需要学习一套 API 就能调用所有主流模型。
本文将深入分析 New API 的技术架构，揭示其如何优雅地解决多平台适配、统一计费、智能路由等核心问题。
一、项目定位与核心能力
1.1 项目定位
New API 基于 One API 二次开发，定位为企业级 AI 资产管理平台，具备三大核心能力：
| 能力维度 | 描述 |
|---|---|
| 统一接入 | 通过单一入口对接多家 AI 服务提供商，屏蔽上游差异 |
| 统一计费 | 支持按量计费、订阅计费、缓存计费与灵活策略配置 |
| 统一治理 | 提供权限分组、模型限制、速率限制、审计日志与可视化看板 |
1.2 支持的上游服务
New API 目前支持 50+ 种通道类型，覆盖：
- 国际厂商：OpenAI、Azure OpenAI、Claude (Anthropic)、Google Gemini、AWS Bedrock、Cohere
- 国内厂商：百度文心、智谱 AI、阿里通义、腾讯混元、字节豆包
- 任务型服务：Midjourney、Suno、可灵视频、即梦视频
- 其他：Dify、Replicate、Ollama、自定义 API
二、整体架构设计
2.1 分层架构
New API 采用经典的 MVC 分层架构，结合微服务设计理念：
┌─────────────────────────────────────────────────────────────┐
│ 客户端 / 浏览器 │
└─────────────────────────┬───────────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────────┐
│ Gin HTTP 服务器 │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ 路由层 (router/) ││
│ │ api-router │ relay-router │ web-router │ video-router ││
│ └─────────────────────────────────────────────────────────┘│
└─────────────────────────┬───────────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────────┐
│ 中间件层 (middleware/) │
│ 认证 │ 限流 │ 日志 │ 国际化 │ CORS │ 请求分发 │
└─────────────────────────┬───────────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────────┐
│ 控制器层 (controller/) │
│ 用户管理 │ 通道管理 │ 令牌管理 │ 计费 │ 统一代理 │
└─────────────────────────┬───────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌─────────▼─────┐ ┌───────▼─────┐ ┌───────▼───────┐
│ 服务层 │ │ 适配器层 │ │ 数据层 │
│ (service/) │ │ (relay/) │ │ (model/) │
│ 计费服务 │ │ OpenAI适配 │ │ GORM ORM │
│ 配额管理 │ │ Claude适配 │ │ │
│ 任务轮询 │ │ Gemini适配 │ │ │
└───────────────┘ └─────────────┘ └───────┬───────┘
│
┌───────────────┼───────────────┐
│ │ │
┌───────▼───────┐ ┌─────▼─────┐ ┌───────▼───────┐
│ SQLite │ │ MySQL │ │ PostgreSQL │
└───────────────┘ └───────────┘ └───────────────┘2.2 请求处理流程
一个典型的 AI 请求在系统中的流转过程：
1. 客户端发送 OpenAI 格式请求
↓
2. Gin 路由匹配到 relay-router
↓
3. 中间件链处理：认证 → 限流 → 日志
↓
4. 控制器校验请求、预估费用、预扣费
↓
5. 根据分组和亲和度选择可用通道
↓
6. 适配器转换请求格式（如 OpenAI → Claude）
↓
7. 发送请求到上游服务
↓
8. 适配器处理响应、标准化格式
↓
9. 结算费用、记录日志
↓
10. 返回响应给客户端三、核心设计模式：适配器模式
3.1 为什么选择适配器模式？
面对 40+ 家不同 API 规范的 AI 服务商，最大的挑战是如何屏蔽差异、统一接口 。New API 选择了适配器模式作为核心设计模式。
适配器模式的优势：
- 解耦：上层业务逻辑与底层平台实现完全分离
- 可扩展：新增平台只需实现适配器接口
- 透明切换：客户端无需感知底层平台差异
- 标准化：统一的请求转换和响应处理机制
3.2 适配器接口设计
系统定义了两个核心接口：
go
// Adaptor 接口 - 标准对话型 AI 服务
type Adaptor interface {
Init(info *RelayInfo)
GetRequestURL(info *RelayInfo) (string, error)
SetupRequestHeader(c *gin.Context, req *http.Request, info *RelayInfo) error
ConvertOpenAIRequest(c *gin.Context, info *RelayInfo, request *dto.GeneralOpenAIRequest) (any, error)
ConvertClaudeRequest(c *gin.Context, info *RelayInfo, request *dto.ClaudeRequest) (any, error)
ConvertGeminiRequest(c *gin.Context, info *RelayInfo, request *dto.GeminiRequest) (any, error)
DoRequest(c *gin.Context, info *RelayInfo, requestBody io.Reader) (*http.Response, error)
DoResponse(c *gin.Context, resp *http.Response, info *RelayInfo) (*dto.Usage, *dto.OpenAIErrorWithStatusCode)
GetModelList() []string
GetChannelName() string
}
// TaskAdaptor 接口 - 异步任务型 AI 服务（如视频生成）
type TaskAdaptor interface {
ValidateRequestAndSetAction(c *gin.Context, info *RelayInfo) *dto.TaskError
EstimateBilling(c *gin.Context, info *RelayInfo) map[string]float64
BuildRequestURL(info *RelayInfo) (string, error)
FetchTask(baseUrl, key string, body io.Reader, proxy string) (*http.Response, error)
ParseTaskResult(respBody []byte) (*dto.TaskInfo, error)
}3.3 协议互转能力
New API 最强大的特性之一是协议互转------你可以用 OpenAI 的格式调用 Claude，也可以用 Claude 的格式调用 Gemini：
┌──────────────────────────────────────────────────────────────┐
│ 协议转换矩阵 │
├──────────────┬───────────────────────────────────────────────┤
│ 输入格式 │ 输出格式 │
├──────────────┼──────────────┬──────────────┬─────────────────┤
│ OpenAI │ ✓ │ Claude 转换 │ Gemini 转换 │
│ Claude │ OpenAI 转换 │ ✓ │ Gemini 转换 │
│ Gemini │ OpenAI 转换 │ Claude 转换 │ ✓ │
└──────────────┴──────────────┴──────────────┴─────────────────┘这意味着：
- 客户端只需学习 OpenAI API
- 后端自动将请求转换为目标平台格式
- 响应也会自动转换回 OpenAI 格式
四、技术栈深度解析
4.1 技术选型总览
| 层级 | 技术选型 | 选型理由 |
|---|---|---|
| 后端语言 | Go 1.25+ | 高并发、低延迟、编译为单二进制 |
| Web 框架 | Gin | 轻量、高性能、中间件生态丰富 |
| ORM | GORM v2 | 多数据库支持、自动迁移、链式 API |
| 前端框架 | React 18 + Vite | 现代开发体验、热更新、Semi Design UI |
| 包管理器 | Bun | 比 npm/yarn 更快的安装和构建 |
| 缓存 | Redis + 内存 | 双通道缓存，支持分布式部署 |
| 认证 | JWT + WebAuthn + OAuth | 多因素认证，支持无密码登录 |
| 容器化 | Docker 多阶段构建 | 镜像体积小，部署简单 |
4.2 多数据库兼容策略
New API 同时支持 SQLite、MySQL、PostgreSQL 三种数据库，这是一个非常有挑战性的设计决策。
兼容性处理要点：
go
// 1. 数据库类型检测
var (
common.UsingPostgreSQL bool
common.UsingSQLite bool
common.UsingMySQL bool
)
// 2. 保留字处理（如 group、key 是 MySQL/PostgreSQL 的保留字）
var commonGroupCol = "`group`" // MySQL/SQLite
var commonGroupCol = `"group"` // PostgreSQL
// 3. 布尔值差异
var commonTrueVal = "1" // MySQL/SQLite
var commonTrueVal = "true" // PostgreSQL
// 4. 迁移限制
// SQLite 不支持 ALTER COLUMN，只能用 ADD COLUMN + 数据迁移开发规范：
- 优先使用 GORM 抽象方法，避免原生 SQL
- 禁止使用特定数据库的专有函数（如
GROUP_CONCAT） - JSON 字段统一使用
TEXT类型存储
4.3 Dockerfile 多阶段构建
dockerfile
# 阶段 1：前端构建
FROM oven/bun:1 AS builder
WORKDIR /build
COPY web/package.json web/bun.lock ./
RUN bun install
COPY ./web .
RUN VITE_REACT_APP_VERSION=$(cat VERSION) bun run build
# 阶段 2：后端编译
FROM golang:1.26.1-alpine AS builder2
ENV GO111MODULE=on CGO_ENABLED=0
WORKDIR /build
COPY go.mod go.sum ./
RUN go mod download
COPY . .
COPY --from=builder /build/dist ./web/dist
RUN go build -ldflags "-s -w" -o new-api
# 阶段 3：运行时镜像
FROM debian:bookworm-slim
COPY --from=builder2 /build/new-api /
EXPOSE 3000
ENTRYPOINT ["/new-api"]这种构建方式的优势：
- 最终镜像只包含运行时必需的文件
- 前端代码被嵌入到 Go 二进制中
- 单一可执行文件，部署极其简单
五、特色功能亮点
5.1 Reasoning Effort 支持
对于支持推理能力的模型（如 o3-mini、GPT-5），可以通过模型名后缀控制推理强度：
bash
# 高推理强度
curl -X POST /v1/chat/completions \
-d '{"model": "o3-mini-high", "messages": [...]}'
# 中等推理强度
curl -X POST /v1/chat/completions \
-d '{"model": "o3-mini-medium", "messages": [...]}'
# 低推理强度
curl -X POST /v1/chat/completions \
-d '{"model": "o3-mini-low", "messages": [...]}'5.2 Thinking 模式转换
Claude 和 Gemini 的思维模式可以自动转换为 OpenAI 兼容格式：
claude-3-7-sonnet-20250219-thinking→ 启用思维模式gemini-2.5-flash-thinking→ 启用思维模式gemini-2.5-pro-thinking-128→ 思维预算 128 tokens
5.3 缓存计费支持
对于支持缓存的模型（OpenAI、Claude、DeepSeek 等），系统会自动识别缓存 Token 并按照不同费率计费：
总费用 = 输入 Token × 输入单价
+ 缓存命中 Token × 缓存单价
+ 输出 Token × 输出单价5.4 智能路由与重试
go
// 通道选择策略
1. 根据用户分组筛选可用通道
2. 按通道权重进行加权随机
3. 考虑通道亲和度（优先使用上次成功的通道）
4. 失败时自动重试其他通道
5. 记录失败日志用于后续优化六、安全架构设计
6.1 多层次安全体系
┌─────────────────────────────────────────────────────────────┐
│ 安全防护体系 │
├─────────────────────────────────────────────────────────────┤
│ 第 1 层：网络层 │
│ - CORS 跨域控制 │
│ - SSRF 防护 │
│ - IP 白名单 │
├─────────────────────────────────────────────────────────────┤
│ 第 2 层：认证层 │
│ - JWT Token 认证 │
│ - Cookie Session 认证 │
│ - WebAuthn/Passkey 无密码登录 │
│ - OAuth (GitHub, Discord, OIDC) │
├─────────────────────────────────────────────────────────────┤
│ 第 3 层：授权层 │
│ - 角色权限 (User/Admin/Root) │
│ - 用户分组 │
│ - 令牌权限控制 │
├─────────────────────────────────────────────────────────────┤
│ 第 4 层：限流层 │
│ - 全局 API 限流 │
│ - 用户级限流 │
│ - 关键操作限流（注册、重置密码等） │
└─────────────────────────────────────────────────────────────┘6.2 双因素认证
支持 TOTP（基于时间的一次性密码）双因素认证，兼容 Google Authenticator、Microsoft Authenticator 等主流应用。
七、部署与运维
7.1 快速部署（Docker Compose）
yaml
version: '3'
services:
new-api:
image: calciumion/new-api:latest
ports:
- "3000:3000"
volumes:
- ./data:/data
environment:
- TZ=Asia/Shanghai
- SQL_DSN=postgres://user:pass@postgres:5432/newapi
- REDIS_CONN_STRING=redis://redis:6379
- SESSION_SECRET=your-random-secret
- CRYPTO_SECRET=your-crypto-secret
depends_on:
- postgres
- redis
healthcheck:
test: ["CMD", "wget", "-q", "-O", "-", "http://localhost:3000/api/status"]
interval: 30s
timeout: 10s
retries: 3
postgres:
image: postgres:15
environment:
POSTGRES_DB: newapi
POSTGRES_USER: user
POSTGRES_PASSWORD: pass
volumes:
- postgres_data:/var/lib/postgresql/data
redis:
image: redis:7-alpine
volumes:
- redis_data:/data
volumes:
postgres_data:
redis_data:7.2 关键环境变量
| 变量名 | 用途 | 必需性 |
|---|---|---|
SESSION_SECRET |
会话加密密钥 | 多机部署必需 |
CRYPTO_SECRET |
Redis 数据加密密钥 | 共享 Redis 必需 |
SQL_DSN |
数据库连接串 | 可选（默认 SQLite） |
REDIS_CONN_STRING |
Redis 连接串 | 可选 |
STREAMING_TIMEOUT |
流式响应超时(秒) | 默认 300 |
PYROSCOPE_URL |
性能分析服务地址 | 可选 |
7.3 可观测性
- 健康检查 ：
GET /api/status - 性能分析：内置 pprof，可选 Pyroscope 集成
- 系统监控：CPU、内存、Goroutine 数量等指标
- 日志系统：支持错误日志独立存储，便于问题排查
八、代码组织结构
new-api/
├── main.go # 应用入口，初始化与启动
├── router/ # 路由层：URL 到处理器的映射
│ ├── main.go # 路由聚合
│ ├── api-router.go # 管理 API（/api/*）
│ ├── relay-router.go # AI 代理（/v1/*）
│ └── web-router.go # 静态资源
├── middleware/ # 中间件：横切关注点
│ ├── auth.go # 认证授权
│ ├── rate-limit.go # 限流
│ └── distributor.go # 请求分发
├── controller/ # 控制器：业务入口
│ ├── relay.go # 统一代理
│ ├── user.go # 用户管理
│ └── billing.go # 计费管理
├── service/ # 服务层：业务逻辑
│ ├── billing/ # 计费服务
│ └── funding_source.go # 资金来源
├── relay/ # 适配器层：核心！
│ ├── channel/ # 各厂商适配器
│ │ ├── adapter.go # 接口定义
│ │ ├── openai/ # OpenAI 适配器
│ │ ├── claude/ # Claude 适配器
│ │ └── gemini/ # Gemini 适配器
│ └── common/ # 公共转换逻辑
├── model/ # 数据模型：ORM 映射
├── dto/ # DTO：请求/响应结构
├── setting/ # 配置中心
├── common/ # 通用工具
├── constant/ # 常量定义
├── i18n/ # 后端国际化
├── oauth/ # OAuth 提供商
└── web/ # React 前端九、总结与展望
9.1 项目优势总结
| 维度 | 优势 |
|---|---|
| 架构设计 | 清晰的分层架构，适配器模式解耦上游差异 |
| 生态支持 | 40+ 上游厂商，覆盖主流 AI 服务 |
| 企业特性 | 多数据库兼容、完善计费、多因素认证 |
| 开发体验 | OpenAI 兼容 API、多语言 UI、详尽文档 |
| 运维友好 | Docker 一键部署、健康检查、性能监控 |
9.2 适用场景
- 企业 AI 平台：统一管理多个 AI 服务商，实现成本可控
- API 网关：为内部应用提供标准化的 AI 能力接入
- 个人开发者：一站式管理多个 AI 账户，避免频繁切换
- 二次开发基础：作为 AI 应用的底层基础设施
9.3 未来展望
- 更多平台支持：持续接入新兴 AI 服务商
- 智能路由优化：基于历史数据的自动路由决策
- 边缘部署：支持本地化、边缘计算场景
- 插件系统：更灵活的功能扩展机制
参考资料
本文基于 New API 项目源码分析撰写，如有疏漏欢迎指正。
作者：技术分析团队 | 日期：2026年4月