尧图网站建设 
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 TZAsia/Shanghai \ -v ./data:/data \ calciumion/new-api:latest # 使用 MySQL docker run --name new-api -d --restart always \ -p 3000:3000 \ -e SQL_DSNroot:123456tcp(localhost:3306)/oneapi \ -e TZAsia/Shanghai \ -v ./data:/data \ calciumion/new-api:latest 提示-v ./data:/data会把数据保存到当前目录的data文件夹也可改为绝对路径如-v /your/custom/path:/data。部署完成后访问http://localhost:3000即可开始使用。从源码看SQLite 模式下数据目录/data是必须挂载的否则容器重建后数据即丢失TZAsia/Shanghai用于统一日志与统计的时区口径。部署环境要求组件要求本地数据库SQLiteDocker 需挂载/data目录远程数据库MySQL ≥ 5.7.8 或 PostgreSQL ≥ 9.6容器引擎Docker / Docker Compose系统架构仅支持 64 位amd64 / arm64不支持 32 位系统默认 compose 编排中的 PostgreSQL 为postgres:15、MySQL 为mysql:8.2均满足上述版本下限要求数据库选型直接决定了后续SQL_DSN的连接串格式。环境变量配置详解New API 的环境变量读取集中在 common/env.go通过GetEnvOrDefault/GetEnvOrDefaultString/GetEnvOrDefaultBool三个助手解析变量缺失或解析失败时回退默认值并在启动日志中输出告警因此漏配不会导致崩溃但会静默降级生产环境务必逐项核对。常用环境变量表变量名说明默认值SESSION_SECRET认证签名密钥所有节点必须一致-SESSION_COOKIE_SECUREfalse/未设置关闭 refresh/logout 的 OriginGuard适用于本地 HTTP 反代true启用 Secure Cookie 与严格 Origin 校验falseSESSION_COOKIE_TRUSTED_URLSecure 模式下必填允许 refresh/logout 的精确 HTTPS Origin多个用逗号分隔不是relay CORS 白名单-TRUSTED_PROXIES未配置/空信任回环、RFC 1918 与 IPv6 ULA 并输出启动告警none不信任任何代理显式 IP/CIDR 列表则完全替代默认值127.0.0.0/8, ::1, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7USER_SESSION_ACTIVE_LIMIT单用户最大活跃登录会话数50USER_SESSION_ISSUANCE_LIMIT窗口内单用户可创建的会话总数含已撤销100USER_SESSION_ISSUANCE_WINDOW_SECONDS会话签发计数窗口若超过已撤销会话保留期则被钳制86400USER_SESSION_REVOKED_RETENTION_DAYS已撤销会话的审计保留天数7USER_SESSION_HOURLY_ALERT_THRESHOLD全局小时级签发量告警阈值仅告警不阻断5000CRYPTO_SECRET缓存键的 HMAC 密钥共享 Redis 的节点必须一致默认取SESSION_SECRETSQL_DSN数据库连接串-REDIS_CONN_STRINGRedis 连接串-STREAMING_TIMEOUT流式响应超时时间秒300STREAM_SCANNER_MAX_BUFFER_MBSSE 扫描器单行最大缓冲MB大体积 base64/图片输出如 4K 图需调大64MAX_REQUEST_BODY_MB请求体最大体积MB解压后计数防止超大请求与 zip 炸弹占满内存超限返回41332AZURE_DEFAULT_API_VERSIONAzure API 版本2025-04-01-previewERROR_LOG_ENABLED错误日志开关falsePYROSCOPE_URLPyroscope 服务端地址-PYROSCOPE_APP_NAMEPyroscope 应用名new-apiPYROSCOPE_BASIC_AUTH_USERPyroscope Basic Auth 用户名-PYROSCOPE_BASIC_AUTH_PASSWORDPyroscope Basic Auth 密码-PYROSCOPE_MUTEX_RATEPyroscope mutex 采样率5PYROSCOPE_BLOCK_RATEPyroscope block 采样率5HOSTNAMEPyroscope 主机标记名new-api关键变量的源码级解读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 可用于本地 HTTPrefresh/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 命令使用 SQLitedocker run --name new-api -d --restart always \ -p 3000:3000 \ -e TZAsia/Shanghai \ -v ./data:/data \ calciumion/new-api:latest使用 MySQLdocker run --name new-api -d --restart always \ -p 3000:3000 \ -e SQL_DSNroot:123456tcp(localhost:3306)/oneapi \ -e TZAsia/Shanghai \ -v ./data:/data \ calciumion/new-api:latest 路径说明./data:/data为相对路径数据保存在当前目录的 data 文件夹也可用绝对路径如/your/custom/path:/data。方法三宝塔面板安装宝塔面板版本 ≥ 9.2.0在应用商店中搜索New-API一键安装图文教程详见 docs/installation/BT.md。多机部署注意事项核心架构章节[!WARNING]所有节点必须使用同一个主数据库和同一个SESSION_SECRET否则 Access Token、Refresh 会话与临时鉴权流程无法被一致校验。连接同一 Redis 的节点还必须使用同一个CRYPTO_SECRET否则缓存键摘要不一致共享条目无法被一致复用。登录会话的权威数据在数据库中会话的 active/签发限额以数据库为准因此这些限制在应用节点间全局生效。Redis 中的会话条目只是短生命周期缓存其 TTL 取Session 剩余寿命与有效SYNC_FREQUENCY默认 60 秒见 common/redis.go 的初始化逻辑中的较小值且读取缓存不会续期。Redis 拓扑与传播/限流语义Redis 拓扑会话传播限流语义共享 Redis撤销与版本发布通过同一缓存即时传播Redis 限流额度在所有节点间共享每节点独立 Redis节点在有效SYNC_FREQUENCY内自数据库重新同步Token 轮换后新 Token 在缓存陈旧的节点上可能短暂收到 401各节点独立计数聚合容量最坏约为单节点阈值 × 节点数无 Redis每次会话校验直接读数据库各节点内存限流独立调小SYNC_FREQUENCY可缩短独立 Redis 部署的陈旧窗口但代价是每个活跃 SID 在每个节点上回源数据库的频率上升默认配置下约每 60 秒一次主键点查。需要说明的是这些保证只覆盖登录会话鉴权的有界陈旧语义限流额度及控制平面其他依赖 Redis 的缓存仍受拓扑影响。更完整的 Token 契约、Origin 校验与 PAT 调用约定参见 docs/authentication.md。核心功能概览基础能力功能说明 全新界面现代化的 UI 设计 多语言支持简体中文、繁体中文、英文、法语、日语 数据兼容与 One API 原数据库完全兼容 数据面板可视化控制台与统计分析 权限管理Token 分组、模型限制、用户管理多语言国际化实现位于 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、AudioTTS/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 MessagesOpenAI 兼容 → Google GeminiGoogle 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 等级并在转发前合并显式参数与后缀意图保证改模型名即改推理档位的体验。模型支持与接口列表模型类型说明 OpenAI 兼容各类 OpenAI 兼容模型 OpenAI ResponsesOpenAI Responses 格式 Midjourney-ProxyMidjourney-Proxy(Plus) 接入 Suno-APISuno API 音乐生成 RerankCohere、Jina ClaudeMessages 格式 GeminiGoogle Gemini 格式 DifyChatFlow 模式 自定义上游合法授权上游端点配置支持的接口全集包括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_STRINGRedis 缓存推荐MEMORY_CACHE_ENABLED内存缓存Redis 连接失败会直接触发FatalLog终止启动见 common/redis.go 的InitRedisClient因此生产环境务必保证 Redis 可用性内存缓存适合单机小规模部署多节点场景请优先 Redis。相关项目与许可上游项目项目说明One API原始项目基础Midjourney-ProxyMidjourney 接口支持配套工具项目说明new-api-key-tool密钥用量查询工具new-api-horizonNew API 的高性能优化版本许可证本项目基于 One API 开源协议。如果组织政策不允许使用 AGPLv3 软件或希望规避 AGPLv3 的开源义务可通过supportquantumnous.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 New API 统一模型网关：从部署到多节点架构的完整实践指南（基于 README 与源码解读）
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 TZAsia/Shanghai \ -v ./data:/data \ calciumion/new-api:latest # 使用 MySQL docker run --name new-api -d --restart always \ -p 3000:3000 \ -e SQL_DSNroot:123456tcp(localhost:3306)/oneapi \ -e TZAsia/Shanghai \ -v ./data:/data \ calciumion/new-api:latest 提示-v ./data:/data会把数据保存到当前目录的data文件夹也可改为绝对路径如-v /your/custom/path:/data。部署完成后访问http://localhost:3000即可开始使用。从源码看SQLite 模式下数据目录/data是必须挂载的否则容器重建后数据即丢失TZAsia/Shanghai用于统一日志与统计的时区口径。部署环境要求组件要求本地数据库SQLiteDocker 需挂载/data目录远程数据库MySQL ≥ 5.7.8 或 PostgreSQL ≥ 9.6容器引擎Docker / Docker Compose系统架构仅支持 64 位amd64 / arm64不支持 32 位系统默认 compose 编排中的 PostgreSQL 为postgres:15、MySQL 为mysql:8.2均满足上述版本下限要求数据库选型直接决定了后续SQL_DSN的连接串格式。环境变量配置详解New API 的环境变量读取集中在 common/env.go通过GetEnvOrDefault/GetEnvOrDefaultString/GetEnvOrDefaultBool三个助手解析变量缺失或解析失败时回退默认值并在启动日志中输出告警因此漏配不会导致崩溃但会静默降级生产环境务必逐项核对。常用环境变量表变量名说明默认值SESSION_SECRET认证签名密钥所有节点必须一致-SESSION_COOKIE_SECUREfalse/未设置关闭 refresh/logout 的 OriginGuard适用于本地 HTTP 反代true启用 Secure Cookie 与严格 Origin 校验falseSESSION_COOKIE_TRUSTED_URLSecure 模式下必填允许 refresh/logout 的精确 HTTPS Origin多个用逗号分隔不是relay CORS 白名单-TRUSTED_PROXIES未配置/空信任回环、RFC 1918 与 IPv6 ULA 并输出启动告警none不信任任何代理显式 IP/CIDR 列表则完全替代默认值127.0.0.0/8, ::1, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7USER_SESSION_ACTIVE_LIMIT单用户最大活跃登录会话数50USER_SESSION_ISSUANCE_LIMIT窗口内单用户可创建的会话总数含已撤销100USER_SESSION_ISSUANCE_WINDOW_SECONDS会话签发计数窗口若超过已撤销会话保留期则被钳制86400USER_SESSION_REVOKED_RETENTION_DAYS已撤销会话的审计保留天数7USER_SESSION_HOURLY_ALERT_THRESHOLD全局小时级签发量告警阈值仅告警不阻断5000CRYPTO_SECRET缓存键的 HMAC 密钥共享 Redis 的节点必须一致默认取SESSION_SECRETSQL_DSN数据库连接串-REDIS_CONN_STRINGRedis 连接串-STREAMING_TIMEOUT流式响应超时时间秒300STREAM_SCANNER_MAX_BUFFER_MBSSE 扫描器单行最大缓冲MB大体积 base64/图片输出如 4K 图需调大64MAX_REQUEST_BODY_MB请求体最大体积MB解压后计数防止超大请求与 zip 炸弹占满内存超限返回41332AZURE_DEFAULT_API_VERSIONAzure API 版本2025-04-01-previewERROR_LOG_ENABLED错误日志开关falsePYROSCOPE_URLPyroscope 服务端地址-PYROSCOPE_APP_NAMEPyroscope 应用名new-apiPYROSCOPE_BASIC_AUTH_USERPyroscope Basic Auth 用户名-PYROSCOPE_BASIC_AUTH_PASSWORDPyroscope Basic Auth 密码-PYROSCOPE_MUTEX_RATEPyroscope mutex 采样率5PYROSCOPE_BLOCK_RATEPyroscope block 采样率5HOSTNAMEPyroscope 主机标记名new-api关键变量的源码级解读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 可用于本地 HTTPrefresh/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 命令使用 SQLitedocker run --name new-api -d --restart always \ -p 3000:3000 \ -e TZAsia/Shanghai \ -v ./data:/data \ calciumion/new-api:latest使用 MySQLdocker run --name new-api -d --restart always \ -p 3000:3000 \ -e SQL_DSNroot:123456tcp(localhost:3306)/oneapi \ -e TZAsia/Shanghai \ -v ./data:/data \ calciumion/new-api:latest 路径说明./data:/data为相对路径数据保存在当前目录的 data 文件夹也可用绝对路径如/your/custom/path:/data。方法三宝塔面板安装宝塔面板版本 ≥ 9.2.0在应用商店中搜索New-API一键安装图文教程详见 docs/installation/BT.md。多机部署注意事项核心架构章节[!WARNING]所有节点必须使用同一个主数据库和同一个SESSION_SECRET否则 Access Token、Refresh 会话与临时鉴权流程无法被一致校验。连接同一 Redis 的节点还必须使用同一个CRYPTO_SECRET否则缓存键摘要不一致共享条目无法被一致复用。登录会话的权威数据在数据库中会话的 active/签发限额以数据库为准因此这些限制在应用节点间全局生效。Redis 中的会话条目只是短生命周期缓存其 TTL 取Session 剩余寿命与有效SYNC_FREQUENCY默认 60 秒见 common/redis.go 的初始化逻辑中的较小值且读取缓存不会续期。Redis 拓扑与传播/限流语义Redis 拓扑会话传播限流语义共享 Redis撤销与版本发布通过同一缓存即时传播Redis 限流额度在所有节点间共享每节点独立 Redis节点在有效SYNC_FREQUENCY内自数据库重新同步Token 轮换后新 Token 在缓存陈旧的节点上可能短暂收到 401各节点独立计数聚合容量最坏约为单节点阈值 × 节点数无 Redis每次会话校验直接读数据库各节点内存限流独立调小SYNC_FREQUENCY可缩短独立 Redis 部署的陈旧窗口但代价是每个活跃 SID 在每个节点上回源数据库的频率上升默认配置下约每 60 秒一次主键点查。需要说明的是这些保证只覆盖登录会话鉴权的有界陈旧语义限流额度及控制平面其他依赖 Redis 的缓存仍受拓扑影响。更完整的 Token 契约、Origin 校验与 PAT 调用约定参见 docs/authentication.md。核心功能概览基础能力功能说明 全新界面现代化的 UI 设计 多语言支持简体中文、繁体中文、英文、法语、日语 数据兼容与 One API 原数据库完全兼容 数据面板可视化控制台与统计分析 权限管理Token 分组、模型限制、用户管理多语言国际化实现位于 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、AudioTTS/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 MessagesOpenAI 兼容 → Google GeminiGoogle 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 等级并在转发前合并显式参数与后缀意图保证改模型名即改推理档位的体验。模型支持与接口列表模型类型说明 OpenAI 兼容各类 OpenAI 兼容模型 OpenAI ResponsesOpenAI Responses 格式 Midjourney-ProxyMidjourney-Proxy(Plus) 接入 Suno-APISuno API 音乐生成 RerankCohere、Jina ClaudeMessages 格式 GeminiGoogle Gemini 格式 DifyChatFlow 模式 自定义上游合法授权上游端点配置支持的接口全集包括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_STRINGRedis 缓存推荐MEMORY_CACHE_ENABLED内存缓存Redis 连接失败会直接触发FatalLog终止启动见 common/redis.go 的InitRedisClient因此生产环境务必保证 Redis 可用性内存缓存适合单机小规模部署多节点场景请优先 Redis。相关项目与许可上游项目项目说明One API原始项目基础Midjourney-ProxyMidjourney 接口支持配套工具项目说明new-api-key-tool密钥用量查询工具new-api-horizonNew API 的高性能优化版本许可证本项目基于 One API 开源协议。如果组织政策不允许使用 AGPLv3 软件或希望规避 AGPLv3 的开源义务可通过supportquantumnous.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考