功能建议：支持无需长期维护 CDN 回源 IP 段的安全真实客户端 IP 信任模式

提交前必读（请勿删除本节）

• 文档：https://docs.newapi.ai/
• 使用问题先看或先问：https://deepwiki.com/QuantumNous/new-api
• 开启透传后的转发相关反馈不接受 issue；透传模式会直接转发请求，请自行确认上游行为。
• 不接受 Coding Plan、翻译代码渠道、第三方封装接口，以及将 Codex 接口反代为通用 API 后产生的兼容性问题；Codex API 自身特有的协议或行为也不应被当作标准 OpenAI API 行为，相关问题请先向渠道或接口提供方确认。
• 警告：删除本模板、删除小节标题或随意清空内容的 issue，可能会被直接关闭；重复恶意提交者可能会被 block。

您当前的 newapi 版本

v1.0.0-rc.22

提交确认

• 非重复 issue: 我已搜索现有 Issues，确认目前没有类似 issue。
• 提交前必读: 我已完整阅读上方“提交前必读”，并已查看文档、README 且向 AI 提问，确认这是现有配置之外的功能改进建议。
• 模板完整: 我未删除此模板中的任何引导内容或小节标题，并会按要求完整填写。
• 维护成本: 我理解项目维护者精力有限，不遵循模板要求的 issue 可能会被无视或直接关闭。

功能描述

当前 TRUSTED_PROXIES + Nginx realip 的 CIDR 信任链是正确且安全的方案；本建议不是要求无条件信任 X-Forwarded-For / X-Real-IP。

问题在于常见部署拓扑为：

CDN → Nginx → New API（仅本机/私网监听）

当 CDN 使用动态或较大的回源 IP 段时，运营方必须持续同步 CDN 的 CIDR 到 Nginx。若遗漏新回源网段，Nginx 会把 CDN 节点地址作为客户端地址传入 New API；多个无关用户会被合并到同一 IP 限流桶。

这会影响基于 ClientIP() 的功能，例如：

• GLOBAL_API_RATE_LIMIT
• GLOBAL_WEB_RATE_LIMIT
• CRITICAL_RATE_LIMIT
• 邮箱验证码发送的 IP 限流
• IP 审计与 IP 黑白名单

提高限流阈值只能缓解，不能恢复按真实用户隔离。另一方面，直接信任所有转发 Header 又会让可以直连源站的请求伪造 IP，因此不应作为推荐方案。

建议新增并文档化一个可选的“已验证回源 Header”模式，作为 CIDR 信任链之外的安全替代方案：

1. 可配置专用真实客户端 IP Header，例如 TRUSTED_CLIENT_IP_HEADER；
2. 可配置回源鉴权 Header 名和值，例如 TRUSTED_ORIGIN_TOKEN_HEADER / TRUSTED_ORIGIN_TOKEN；
3. 仅当回源鉴权 Header 精确匹配时，才采用专用客户端 IP Header；否则继续使用现有 ClientIP() / TCP 对端逻辑；
4. 明确要求 CDN 覆盖这两个 Header，Nginx/源站拒绝未鉴权直连；
5. 保持 TRUSTED_PROXIES + 精确 CIDR 作为默认和推荐方案；
6. 提供 Cloudflare、EdgeOne 等 CDN 的完整示例，以及未通过鉴权时的启动/运行日志提示。

这样不会无条件信任任意用户提交的 Header，也可以让支持“回源固定鉴权 Header”的 CDN 部署避免长期人工维护回源 IP 段。

应用场景

面向国内/海外双 CDN 的公开面板部署。国内 CDN 的请求经节点回源后，如果真实 IP 未恢复，很多真实用户会共用同一 CDN 节点 IP；新版认证、网页/API 限流和验证码限流会让无关用户互相触发 429。

现有 CIDR 方案仍可用，但动态网段维护是长期运维负担：网段变更漏同步后，服务通常不会完全不可用，却会退化为 CDN 节点 IP 维度的限流和审计，问题难以及时发现。

希望上游评估是否接受这种基于回源鉴权 Header 的可选模式；若不适合放进核心，也希望文档明确推荐的、无需持续人工维护 CIDR 的安全替代方案。

No source files or tests are named. Start by locating the existing ClientIP() handling, TRUSTED_PROXIES configuration, and rate-limit callers, then trace how forwarded headers are processed. Done should include the optional authenticated-header behavior, preserved default CIDR trust, logging for failed authentication, documentation, and CDN examples described in the issue.