企业官网建设流程全解析

New API 统一模型网关：从部署到多节点架构的完整实践指南（基于 README 与源码解读）

【免费下载链接】new-apiA unified AI model hub for aggregation & distribution. It supports cross-converting various LLMs into OpenAI-compatible, Claude-compatible, or Gemini-compatible formats. A centralized gateway for personal and enterprise model management.项目地址: https://gitcode.com/gh_mirrors/ne/new-api

导读

New API 是一个面向聚合与分发的统一 AI 模型网关系统，也是下一代的模型扩展网关与 AI 资产管理平台：它能够把 OpenAI、Claude、Gemini、Midjourney、Suno、Dify 等各类上游模型服务统一接入，向下提供 OpenAI 兼容、Claude 兼容、Gemini 兼容等多种消费端格式，同时内置令牌分组、权限管理、用量统计、成本计费与私有化部署能力。本文以 README.fr.md 为核心骨架，结合仓库中的 docker-compose.yml、common/env.go、common/redis.go、docs/authentication.md 等源码与配置，系统讲解项目定位、快速部署、环境变量、三种部署方式、多节点架构、核心功能与模型接入，读完即可完成从单机试跑到多节点生产化的全流程搭建。

项目定位与合规前提

New API 定位于AI API 网关、组织级鉴权、多模型管理、用量分析、成本核算与私有化部署场景。README 开篇即以重要提示划定了使用边界（见 README.fr.md）：

• 项目仅面向合法授权的 AI API 网关、组织认证、多模型管理、使用分析、成本核算与私有部署场景；
• 用户必须合法获取上游 API 密钥、账户、模型服务与接口权限，并遵守上游服务条款及适用法律法规；
• 向公众提供生成式 AI 服务时，须满足所在司法辖区的备案、许可、内容安全、实名认证、日志留存、税务及上游授权等全部义务。

快速开始：两条 Docker 上手路径

方式一：Docker Compose（推荐）

# 克隆项目 git clone https://github.com/QuantumNous/new-api.git cd new-api # 修改 docker-compose.yml 配置 nano docker-compose.yml # 启动服务 docker-compose up -d

仓库根目录的 docker-compose.yml 默认编排了三类服务：new-api主服务（镜像calciumion/new-api:latest）、redis（用于缓存与限流）和postgres（默认主数据库）。该文件还内置了 MySQL、ClickHouse 的注释化切换模板：若要改用 MySQL，注释掉postgres服务及其SQL_DSN，取消mysql服务、对应SQL_DSN、depends_on与volumes的注释即可。Compose 文件同时为new-api服务配置了healthcheck，通过wget探测http://localhost:3000/api/status是否返回"success": true，每 30 秒检查一次。

⚠️ Compose 文件中所有默认密码（PostgreSQL、Redis、MySQL 等）部署前必须修改。

方式二：纯 Docker 命令

# 拉取最新镜像 docker pull calciumion/new-api:latest # 使用 SQLite（默认） docker run --name new-api -d --restart always \ -p 3000:3000 \ -e TZ=Asia/Shanghai \ -v ./data:/data \ calciumion/new-api:latest # 使用 MySQL docker run --name new-api -d --restart always \ -p 3000:3000 \ -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" \ -e TZ=Asia/Shanghai \ -v ./data:/data \ calciumion/new-api:latest

💡 提示：-v ./data:/data会把数据保存到当前目录的data文件夹，也可改为绝对路径，如-v /your/custom/path:/data。

部署完成后访问http://localhost:3000即可开始使用。从源码看，SQLite 模式下数据目录/data是必须挂载的，否则容器重建后数据即丢失；TZ=Asia/Shanghai用于统一日志与统计的时区口径。

部署环境要求

默认 compose 编排中的 PostgreSQL 为postgres:15、MySQL 为mysql:8.2，均满足上述版本下限要求；数据库选型直接决定了后续SQL_DSN的连接串格式。

环境变量配置详解

New API 的环境变量读取集中在 common/env.go，通过GetEnvOrDefault/GetEnvOrDefaultString/GetEnvOrDefaultBool三个助手解析：变量缺失或解析失败时回退默认值，并在启动日志中输出告警，因此漏配不会导致崩溃，但会静默降级，生产环境务必逐项核对。

常用环境变量表

关键变量的源码级解读

SESSION_SECRET 与 CRYPTO_SECRET（多节点一致性）：按 docs/authentication.md 的说明，SESSION_SECRET用于派生 Access Token、Security Proof、Refresh Token 摘要和 AuthFlow 摘要的用途分离密钥，生产与多节点环境必须在所有节点配置相同的高强度随机值，更换它会令现有登录、临时鉴权流程与 Security Proof 全部失效。而CRYPTO_SECRET决定缓存键摘要：共享同一 Redis 的节点若CRYPTO_SECRET不一致，生成的缓存键不同，共享缓存将无法复用——这解释了 README 多机部署警告中两条"必须一致"的深层原因。

SESSION_COOKIE_SECURE / SESSION_COOKIE_TRUSTED_URL（生产 HTTPS 必读）：非 Secure 模式下 Refresh Cookie 可用于本地 HTTP，refresh/logout 的 OriginGuard 关闭，便于http://localhost上不同端口的 Rsbuild/Vite 开发代理转发；Secure 模式下 Refresh Cookie 仅经 HTTPS 发送，并强制校验浏览器的Origin，缺少 Origin 时仅接受合法单一Referer回退。允许来源为请求自身的精确 Origin 加上SESSION_COOKIE_TRUSTED_URL中列出的精确 HTTPS Origin（如https://panel.example.com、https://panel.example.com:8443），不支持通配符、路径、查询参数或域名后缀匹配。注意它不会改变 relay、旧计费面板、/api/usage/token、/api/log/token的 CORS 行为，浏览器使用sk-密钥直连 relay 的场景不受影响。

TRUSTED_PROXIES（反代拓扑三态）：Gin 默认信任所有代理提供的客户端 IP 头，本项目改为三态配置：未配置时信任回环、RFC 1918 私网与fc00::/7并告警；none为严格直连模式，ClientIP()只使用 TCP 直连地址；显式列表则按英文逗号解析为代理 IP/CIDR完全替代默认值，且应填写反向代理自身地址而非客户端网段，非法 CIDR、空列表或将none与其他值混用都会阻止服务启动。

限流相关：仓库 common/rate-limit.go 实现了带闲置键淘汰的 LRU 内存滑动窗口限流器（InMemoryRateLimiter），用于节点内限流；而 Redis 限流采用原子 Lua 固定窗口（见 common/limiter/limiter.go 与 common/limiter/lua 目录），固定窗口在边界两侧可各打满一次，极短时间内通过量最高约为配置值两倍，属于有意的语义取舍。

三种部署方法

方法一：Docker Compose（推荐）

# 克隆项目 git clone https://github.com/QuantumNous/new-api.git cd new-api # 修改配置 nano docker-compose.yml # 启动服务 docker-compose up -d

方法二：Docker 命令

使用 SQLite：

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

使用 MySQL：

docker run --name new-api -d --restart always \ -p 3000:3000 \ -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" \ -e TZ=Asia/Shanghai \ -v ./data:/data \ calciumion/new-api:latest

💡 路径说明：./data:/data为相对路径，数据保存在当前目录的 data 文件夹；也可用绝对路径，如/your/custom/path:/data。

方法三：宝塔面板

1. 安装宝塔面板（版本 ≥ 9.2.0）
2. 在应用商店中搜索New-API
3. 一键安装

图文教程详见 docs/installation/BT.md。

多机部署注意事项（核心架构章节）

[!WARNING]

• 所有节点必须使用同一个主数据库和同一个SESSION_SECRET；否则 Access Token、Refresh 会话与临时鉴权流程无法被一致校验。
• 连接同一 Redis 的节点还必须使用同一个CRYPTO_SECRET；否则缓存键摘要不一致，共享条目无法被一致复用。

登录会话的权威数据在数据库中：会话的 active/签发限额以数据库为准，因此这些限制在应用节点间全局生效。Redis 中的会话条目只是短生命周期缓存，其 TTL 取"Session 剩余寿命"与有效SYNC_FREQUENCY（默认 60 秒，见 common/redis.go 的初始化逻辑）中的较小值，且读取缓存不会续期。

Redis 拓扑与传播/限流语义

调小SYNC_FREQUENCY可缩短独立 Redis 部署的陈旧窗口，但代价是每个活跃 SID 在每个节点上回源数据库的频率上升（默认配置下约每 60 秒一次主键点查）。需要说明的是，这些保证只覆盖登录会话鉴权的有界陈旧语义；限流额度及控制平面其他依赖 Redis 的缓存仍受拓扑影响。更完整的 Token 契约、Origin 校验与 PAT 调用约定参见 docs/authentication.md。

核心功能概览

基础能力

多语言国际化实现位于 i18n/ 目录（含 i18n/locales/en.yaml、i18n/locales/zh-CN.yaml 等五个语言文件）；"与 One API 数据兼容"意味着旧 One API 的渠道、令牌、用户数据可平滑迁移，降低了从既有部署升级的成本。

计费与结算（授权使用场景）

• ✅ 合法授权场景下的内部充值与配额分配（EPay、Stripe）
• ✅ 组织级按请求、按用量、按缓存命中计费
• ✅ 支持 OpenAI、Azure、DeepSeek、Claude、Qwen 等模型计费的缓存统计
• ✅ 面向内部管理或企业客户的灵活计费策略

计费表达式引擎位于 pkg/billingexpr/，其中 pkg/billingexpr/compile.go 负责编译计费表达式、pkg/billingexpr/settle.go 负责结算，配合 pkg/billingexpr/expr.md 可了解表达式语法，适合需要自定义企业计费规则的高级用户继续深入。

授权与安全

• 😈 Discord 授权登录（实现见 oauth/discord.go）
• 🤖 LinuxDO 授权登录（oauth/linuxdo.go）
• 📱 Telegram 授权登录（oauth/telegram.go）
• 🔑 统一 OIDC 认证（oauth/oidc.go）
• 🔍 密钥用量配额查询（配合 new-api-key-tool 使用）

各 OAuth 提供方通过 oauth/provider.go 与 oauth/registry.go 统一注册，新增登录源时只需实现 Provider 接口并注册即可。

高级功能：多格式协议与智能路由

支持的 API 格式

• ⚡ OpenAI Responses
• ⚡ OpenAI Realtime API（含 Azure）
• ⚡ Claude Messages
• ⚡ Google Gemini
• 🔄 Rerank 模型（Cohere、Jina）

从 relay/constant/relay_mode.go 的中继模式定义可见，网关按请求路径与模式分发：/v1/chat/completions映射到 Chat Completions 模式，其余如 Embeddings、Images、Audio（TTS/Whisper）、Video、Rerank、Responses、Realtime、Gemini、Midjourney 系列（Imagine/Describe/Blend/Change/Shorten 等）均有独立中继模式，逐一路径落到对应 handler（见 relay/ 目录下的各 handler 文件）。

智能路由

• ⚖️ 按权重随机选择渠道（渠道亲和与选择逻辑见 service/channel_select.go 与 service/channel_affinity.go）
• 🔄 失败自动重试
• 🚦 用户级模型限流（middleware/model-rate-limit.go）

格式转换

• 🔄OpenAI 兼容 ⇄ Claude Messages
• 🔄OpenAI 兼容 → Google Gemini
• 🔄Google Gemini → OpenAI 兼容——仅文本，函数调用暂不支持
• 🚧OpenAI 兼容 ⇄ OpenAI Responses——开发中
• 🔄思考内容（thinking）转正文内容

格式转换的底层实现在 relay/common/request_conversion.go 与 relay/common/outbound_body.go，并在 relay/common/request_conversion.go 对应的*_test.go中有大量双向转换用例；"thinking 转 content"功能则在 relaykit/relayconvert/reasoning 下实现，由 relay/channel/openai/adaptor.go 中的thinking_to_content开关控制。

推理强度（Reasoning Effort）支持

OpenAI 系列模型：

• o3-mini-high—— 高推理强度
• o3-mini-medium—— 中推理强度
• o3-mini-low—— 低推理强度
• gpt-5-high—— 高推理强度
• gpt-5-medium—— 中推理强度
• gpt-5-low—— 低推理强度

Claude 思考模型：

• claude-3-7-sonnet-20250219-thinking—— 开启思考模式

Google Gemini 系列：

• gemini-2.5-flash-thinking—— 开启思考模式
• gemini-2.5-flash-nothinking—— 关闭思考模式
• gemini-2.5-pro-thinking—— 开启思考模式
• gemini-2.5-pro-thinking-128—— 开启思考模式并限定 128 token 思考预算
• 还可以给 Gemini 模型追加-low、-medium或-high后缀固定推理强度等级（不附加额外预算后缀）

从源码看，推理强度的解析与合并逻辑位于 setting/reasoning/（含 setting/reasoning 目录下的模型后缀解析实现），relay/channel/openai/adaptor.go 会从模型后缀解析reasoning_effort，再经 relaykit/relayconvert/reasoning 生成统一的推理意图（thinking 模式开/关 + effort 等级），并在转发前合并显式参数与后缀意图，保证"改模型名即改推理档位"的体验。

模型支持与接口列表

支持的接口全集包括：Chat Completions 对话、Responses 响应、Image 图像、Audio 音频（转写/翻译/TTS）、Video 视频、Embeddings 嵌入、Rerank 重排、Realtime 实时会话、Claude 对话、Google Gemini 对话。各类型对应的渠道适配器集中在 relay/channel/ 目录（含 openai、claude、gemini、midjourney、dify、cohere、jina 等子目录），新增模型类型只需实现 relay/channel/adapter.go 定义的适配器接口并注册。

渠道重试与缓存配置

重试配置：设置 → 运行设置 → 通用设置 → 失败重试次数

缓存配置：

• REDIS_CONN_STRING：Redis 缓存（推荐）
• MEMORY_CACHE_ENABLED：内存缓存

Redis 连接失败会直接触发FatalLog终止启动（见 common/redis.go 的InitRedisClient），因此生产环境务必保证 Redis 可用性；内存缓存适合单机小规模部署，多节点场景请优先 Redis。

相关项目与许可

上游项目

配套工具

许可证

本项目基于 One API 开源协议。如果组织政策不允许使用 AGPLv3 软件，或希望规避 AGPLv3 的开源义务，可通过support@quantumnous.com联系项目方（见 README.fr.md 许可证章节）。

帮助与支持

官方仓库提供 FAQ、社区交流渠道、问题反馈与完整文档等支持资源；对源码内部机制感兴趣的读者，可结合本文引用的仓库路径（docs/authentication.md、docs/installation/BT.md、common/redis.go、relay/constant/relay_mode.go 等）继续深入。所有形式的贡献（报告 Bug、提议新功能、改进文档、提交代码）均受欢迎，贡献前请先阅读仓库根目录的 AGENTS.md 与 CLAUDE.md，了解项目的开发约定与构建方式。

【免费下载链接】new-apiA unified AI model hub for aggregation & distribution. It supports cross-converting various LLMs into OpenAI-compatible, Claude-compatible, or Gemini-compatible formats. A centralized gateway for personal and enterprise model management.项目地址: https://gitcode.com/gh_mirrors/ne/new-api