深入解析 New API：下一代大模型网关的架构设计与实现

张

张建站

2026/4/24 17:22:28

10分钟阅读

深入解析 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 适配器接口设计系统定义了两个核心接口// Adaptor 接口 - 标准对话型 AI 服务typeAdaptorinterface{Init(info*RelayInfo)GetRequestURL(info*RelayInfo)(string,error)SetupRequestHeader(c*gin.Context,req*http.Request,info*RelayInfo)errorConvertOpenAIRequest(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()[]stringGetChannelName()string}// TaskAdaptor 接口 - 异步任务型 AI 服务如视频生成typeTaskAdaptorinterface{ValidateRequestAndSetAction(c*gin.Context,info*RelayInfo)*dto.TaskErrorEstimateBilling(c*gin.Context,info*RelayInfo)map[string]float64BuildRequestURL(info*RelayInfo)(string,error)FetchTask(baseUrl,keystring,body io.Reader,proxystring)(*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轻量、高性能、中间件生态丰富ORMGORM v2多数据库支持、自动迁移、链式 API前端框架React 18 Vite现代开发体验、热更新、Semi Design UI包管理器Bun比 npm/yarn 更快的安装和构建缓存Redis 内存双通道缓存支持分布式部署认证JWT WebAuthn OAuth多因素认证支持无密码登录容器化Docker 多阶段构建镜像体积小部署简单4.2 多数据库兼容策略New API 同时支持SQLite、MySQL、PostgreSQL三种数据库这是一个非常有挑战性的设计决策。兼容性处理要点// 1. 数据库类型检测var(common.UsingPostgreSQLboolcommon.UsingSQLiteboolcommon.UsingMySQLbool)// 2. 保留字处理如 group、key 是 MySQL/PostgreSQL 的保留字varcommonGroupColgroup// MySQL/SQLitevarcommonGroupColgroup// PostgreSQL// 3. 布尔值差异varcommonTrueVal1// MySQL/SQLitevarcommonTrueValtrue// PostgreSQL// 4. 迁移限制// SQLite 不支持 ALTER COLUMN只能用 ADD COLUMN 数据迁移开发规范优先使用 GORM 抽象方法避免原生 SQL禁止使用特定数据库的专有函数如GROUP_CONCATJSON 字段统一使用TEXT类型存储4.3 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 GO111MODULEon CGO_ENABLED0 WORKDIR /build COPY go.mod go.sum ./ RUN go mod download COPY . . COPY --frombuilder /build/dist ./web/dist RUN go build -ldflags -s -w -o new-api # 阶段 3运行时镜像 FROM debian:bookworm-slim COPY --frombuilder2 /build/new-api / EXPOSE 3000 ENTRYPOINT [/new-api]这种构建方式的优势最终镜像只包含运行时必需的文件前端代码被嵌入到 Go 二进制中单一可执行文件部署极其简单五、特色功能亮点5.1 Reasoning Effort 支持对于支持推理能力的模型如 o3-mini、GPT-5可以通过模型名后缀控制推理强度# 高推理强度curl-XPOST /v1/chat/completions\-d{model: o3-mini-high, messages: [...]}# 中等推理强度curl-XPOST /v1/chat/completions\-d{model: o3-mini-medium, messages: [...]}# 低推理强度curl-XPOST /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 tokens5.3 缓存计费支持对于支持缓存的模型OpenAI、Claude、DeepSeek 等系统会自动识别缓存 Token 并按照不同费率计费总费用输入 Token × 输入单价缓存命中 Token × 缓存单价输出 Token × 输出单价5.4 智能路由与重试// 通道选择策略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 Composeversion:3services:new-api:image:calciumion/new-api:latestports:-3000:3000volumes:-./data:/dataenvironment:-TZAsia/Shanghai-SQL_DSNpostgres://user:passpostgres:5432/newapi-REDIS_CONN_STRINGredis://redis:6379-SESSION_SECRETyour-random-secret-CRYPTO_SECRETyour-crypto-secretdepends_on:-postgres-redishealthcheck:test:[CMD,wget,-q,-O,-,http://localhost:3000/api/status]interval:30stimeout:10sretries:3postgres:image:postgres:15environment:POSTGRES_DB:newapiPOSTGRES_USER:userPOSTGRES_PASSWORD:passvolumes:-postgres_data:/var/lib/postgresql/dataredis:image:redis:7-alpinevolumes:-redis_data:/datavolumes:postgres_data:redis_data:7.2 关键环境变量变量名用途必需性SESSION_SECRET会话加密密钥多机部署必需CRYPTO_SECRETRedis 数据加密密钥共享 Redis 必需SQL_DSN数据库连接串可选默认 SQLiteREDIS_CONN_STRINGRedis 连接串可选STREAMING_TIMEOUT流式响应超时(秒)默认 300PYROSCOPE_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 GitHub 仓库官方文档One API 原始项目本文基于 New API 项目源码分析撰写如有疏漏欢迎指正。作者技术分析团队 | 日期2026年4月