NebulaGate 是一个在上游 new-api 基础上持续增强的 LLM 智能网关 & 运营中台。它把“多模型聚合中继”升级为“接入、治理、计费、审计、可观察的一站式平台”，面向个人开发者、团队与中小企业，聚焦以下核心价值：

• 统一接入：对外暴露 OpenAI 兼容接口，向内无缝对接多家模型服务（OpenAI、Claude、Gemini、Azure 等），简化上层业务接入成本。
• 稳定与合规：通过治理与分流（Governance Pipeline）将潜在违规请求降级、改路由或阻断，并留下可审计的链路证据。
• 商业化能力：内置计费域模型（Plan/Balance/Ledger），支持套餐与代金券（Voucher），完善用量生命周期管理，具备幂等与可回溯性。
• 可视化运营：在上游看板基础之上，对计费、治理、渠道健康度、失败原因等做更贴近运营人员心智的呈现。
• 运维友好：多阶段 Docker 构建、精简运行镜像、环境变量统一、日志脱敏与安全基线建议，降低部署与日常运维门槛。

一句话总结：NebulaGate = new-api 的稳定中继能力 + 计费&治理&审计的商业化增强。

• 背景与定位

• 与上游 new-api 的差异与优势

• 总体特性概览

• 系统架构与设计理念

• 关键模块详解

  • 计费域模型（Plan/Balance/Ledger/幂等）
  • 套餐与授权（Plans→User/Org）
  • 代金券 Voucher（发放/兑换/风控）
  • 治理与分流（Governance Pipeline）
  • 可观察性与运营看板

• 兼容性与支持矩阵

• 快速上手（部署方式综述）

• 典型应用场景与落地范式

• 安全加固与合规建议

• 性能与成本优化

• 运维与升级（SOP）

• 故障排查（Troubleshooting）

• FAQ 常见问题

• Roadmap 规划

• License

大模型生态快速演进，企业与团队常见痛点包括：

1. 多源接入成本高：不同厂商 API 规格差异大；权限、版本与配额管理分散。
2. 稳定性与可控性不足：请求命中风控/策略变更时业务受影响，缺少统一的降级与分流。
3. 商业化缺口：缺少可用的计费引擎，无法对“调用→消耗→账单→对账”进行闭环治理。
4. 审计与合规：对“谁、在什么时间、调用了什么、为什么失败/被拦截”缺乏结构化留痕。
5. 运营与可视化：指标看板与运营动作割裂，难以把产品运营策略落到数据与流程上。

NebulaGate 的使命，是把上游 new-api 优秀的“统一中继”能力演进为“可运营、可计费、可审计”的综合平台，让开发、运维、运营、财务在一套系统上建立协同语境。

总结：NebulaGate 在上游“稳定中继”的强项上，补齐“商业化运营与合规治理”的关键拼图。

• 对外协议：兼容 OpenAI 风格（Chat Completions / Responses / Streaming / Realtime / Rerank）。
• 多云聚合：OpenAI、Claude、Gemini、Azure/自建通道等；支持权重与故障切换。
• 计费闭环：Plan → Balance → Ledger（可审计账本），支持幂等、回滚与补偿。
• 套餐管理：为用户/组织分配套餐（额度/周期/结转），支持到期重置与通知。
• 代金券运营：批量生成、核销、风控校验；支持多维过滤与使用范围限制。
• 治理与分流：关键词/地域/路径/速率/模型/标签等策略；命中后降级、改路由或阻断。
• 可观察性：多维看板（渠道健康/失败原因/QPS/耗时/账本变更），供运营洞察与决策。
• 部署友好：多阶段 Docker，运行镜像极简；环境变量设计一致；日志与安全基线内置建议。

┌────────────────────────────┐
│        Client Apps         │  →  SDK / CURL / Server-side calls
└─────────────▲──────────────┘
              │  OpenAI-compatible APIs
              ▼
┌───────────────────────────────────────────────────────────┐
│                      NebulaGate Core                      │
│  ┌───────────┐   ┌──────────────┐   ┌──────────────────┐ │
│  │ Governance│→→│ Router/Policy │→→│ Provider Adapters │ │
│  │  Pipeline │   └──────────────┘   └──────────────────┘ │
│  └─────▲─────┘            │                   ▲          │
│        │                  │                   │          │
│  ┌─────┴────┐       ┌─────┴────┐       ┌──────┴─────┐   │
│  │  Billing │←──────│  Ledger   │─────→│  Admin UI  │   │
│  │ Plan/Acct│       └───────────┘       └───────────┘   │
└──┴──────────┴────────────────────────────────────────────┘
        │                        │
        ▼                        ▼
    Database                Redis/Cache
  (SQLite/MySQL/PG)        (Crypto/Rate/Temp)

核心设计理念：

1. 多层解耦：请求先过治理（可降级/分流），后进入路由与模型通道；计费变更全经 Ledger 留痕。
2. 幂等与补偿：所有影响余额/额度的写入都围绕幂等键与账本；失败可回滚。
3. 可插拔策略：治理与分流规则、套餐与结转策略、Voucher 风控均可演进。
4. 最小可运行集：单机可用（SQLite/无 Redis），生产建议 MySQL/PG+Redis。
5. 运维可落地：容器化、统一环境变量、标准健康检查与日志规范。

• Plan（套餐定义）：

  • 额度维度：可按 Token/调用次数/金额等指标度量（具体以实现为准）。
  • 周期维度：月度/季度/自定义周期。
  • 结转策略：到期是否结转、结转上限。
  • 通用属性：是否允许超用、到期行为（阻断/降级/提醒）。

• Balance（账户余额/额度）：

  • 与用户/组织关联，维护当前可用额度、冻结额度等。
  • 由 Ledger 驱动变更，禁止绕过记账直接写余额。

• Ledger（不可篡改账本）：

  • 记录每次“增/减”的来源、原因、时间、操作人或系统调用标识。
  • 支持幂等键避免重复记账；支持失败重试与补偿。
  • 与运营看板打通，形成闭环审计。

• 幂等策略：

  • 核心路径（充值、扣费、结转、Voucher 兑换）均要求幂等键。
  • 幂等键与外部业务单号/请求 ID 关联，避免并发/重放导致的重复变更。

为什么要这么设计？ 因为商业化运营下，资金/额度是“可计量资产”。任何一次误记账或重复记账都会引发对账风险，而幂等账本+回滚补偿是“时间久了仍然能解释清楚”的唯一办法。

• 创建 Plan 后，可分配至用户或组织，形成“授权关系”。
• 授权关系可设置开始/结束日期、初始额度、个性化上限。
• 支持批量操作（例如：某渠道异常后补偿全体用户 1000 Token）。
• 支持冻结/解冻（风控或欠费时常用）。
• 与治理联动：当某用户被策略判定为高风险，可临时降低额度或切换到“只允许基础模型”的 Plan。

• 发放：生成一个或多个批次（Batch），每批可设：

  • 面额（额度或金额）、总量、有效期、适用范围（指定 Plan/模型/路径/租户）。
  • 兑换上限（每账号最多兑换次数）与防刷策略（黑白名单、IP 频率等）。

• 兑换：用户侧输入兑换码，后端做幂等兑换，将额度写入 Ledger，并增加 Balance。

• 统计/回收：可按批次/渠道统计核销率；对于被判定为异常的兑换，可作“账本逆向记账”。

代金券不仅用于拉新，也常用于事故补偿与营销活动。有了 Ledger，补发/撤销才有据可查。

治理链路的目标是“在不打断业务目标的前提下，把坏事变小”。它通常包含：

1. 检测：关键词、地域、路径、模型、速率、账户信誉、风控标签等。
2. 动作：拒绝、降级（限模型/限速）、改路由（换到更稳的通道/更合规的区域）、记录审计。
3. 留痕：触发规则、命中细节、业务影响（是否成功降级/是否阻断）、操作人或自动化策略的版本号。

常见治理策略示例：

• 安全文本筛查：命中敏感词则切到审计模型或直接阻断。
• 地域合规：来自特定地域的请求仅可访问同地域合规的模型与数据中心。
• 速率与并发：超阈值时降级到低配通道，保证骨干业务可用。
• 成本护栏：当日花费超预算则将大模型请求降级到轻量模型，并在看板报警。

• 实时指标：QPS、成功率、P50/P95 时延、超时与错误分布、模型与通道健康度。
• 计费维度：账本变更、套餐消耗曲线、Voucher 核销、欠费/冻结概览。
• 治理维度：策略命中率、降级/改路由效果、误杀/漏拦趋势复盘。
• 运营动作：基于看板做“批量补偿、临时限流、渠道切换、套餐升级”的一键化操作（取决于你开放的后台能力）。

• 接口：OpenAI 兼容（Chat、Responses、Streaming、Realtime、Rerank）
• 模型厂商：OpenAI、Anthropic Claude、Google Gemini、Azure/OpenAI on Azure、以及社区/本地部署通道
• 数据库：SQLite（单机试用）、MySQL ≥ 5.7.8、PostgreSQL ≥ 9.6
• 缓存：Redis（生产强烈建议开启；使用共享 Redis 时必须配置 CRYPTO_SECRET）
• 时区：TZ=Asia/Shanghai 或你的本地时区

此节聚焦“介绍与理解”，详细命令与 Compose 样例可放到安装文档或下移到“快速开始”章节。要点如下：

• 单机体验：仅需 Docker，采用 SQLite，5 分钟可启动。
• 小规模生产：Docker Compose + MySQL/PG + Redis，支持水平扩容。
• CI/CD：建议配置 GitHub Actions（或私有 CI）自动构建与推送镜像；生产使用带版本 Tag 的镜像（如 vX.Y.Z），latest 仅作回归验证。
• 安全基线：SESSION_SECRET 严格要求强随机；使用共享 Redis 时必须提供 CRYPTO_SECRET；建议部署在反代（Nginx/Caddy）之后并强制 HTTPS。

1. 多团队统一网关

   • 场景：一个公司内多个项目分别向 OpenAI/Claude/Gemini 调用，成本失控、密钥暴露风险高。
   • 做法：各团队仅对接 NebulaGate，后者负责渠道聚合与治理；通过 Plan 管控配额，通过 Ledger 审计成本。

2. 对外部合作方开放 API

   • 场景：给合作伙伴/生态伙伴提供模型调用能力，但需严格控制额度与权限。
   • 做法：为每个合作方创建 Plan 与专属 Token，配上地域/模型白名单治理策略，代金券用于促销与定向补偿。

3. 教育/活动发券与核销

   • 场景：面向校园/活动人群发放免费额度，既要便捷又要防刷。
   • 做法：通过 Voucher 发行批次控制有效期、适用范围与核销上限；结合治理策略做风控。

4. 合规地区流量分流

   • 场景：不同国家/地区的合规要求不同，部分模型/路径受限。
   • 做法：治理策略按地域识别后，路由到合规通道或降级模型；留痕用于合规审计。

• 密钥管理：

  • 生产务必设置 SESSION_SECRET（强随机，建议 openssl rand -hex 32）。
  • 使用共享 Redis 时必须设置 CRYPTO_SECRET，用于对共享态数据加密/签名。

• 网络与反代：

  • 只在内网暴露服务端口，对外通过 Nginx/Caddy 反向代理并启用 TLS。
  • 使用 WAF/限速（limit_req）防止恶意爬取与暴力尝试。

• 权限最小化：

  • 运行用户使用最小权限；数据库账号仅授予所需权限；密钥保存在安全仓（CI Secret、Vault）。

• 日志脱敏：

  • 对用户输入、模型返回中的敏感字段（Token/账号/业务 ID）做掩码；遵守本地法律法规与数据合规要求。

• 审计与留痕：

  • 账本（Ledger）记录资金/额度变动，治理链路记录策略命中与动作；定期导出做归档。

• 渠道权重与自适应：

  • 根据成功率与 P95 时延定期调整通道权重；对抖动严重的通道自动降权。

• 超时与重试：

  • 针对不同厂商设置差异化超时与重试上限，避免级联雪崩；对可重入的推理任务采用指数退避。

• 缓存与连接池：

  • 使用 Redis 缓存元数据、热 Key；数据库连接池大小与最大空闲/生命周期合理配置。

• 成本护栏：

  • 设定预算上限与阈值告警；当日达阈值后自动将高价模型调用降级或延后。

• 版本管理：

  • 遵循语义化版本（MAJOR.MINOR.PATCH）；latest 用于回归验证，生产固定到具体版本。

• 灰度发布：

  • 先在非核心业务链路灰度，确认稳定后再切主流量；保留上一个版本可随时回滚。

• 数据迁移：

  • 涉及表结构变更时，在 Release Note 明确迁移脚本与回退策略；对 Ledger 类表谨慎处理。

• 备份策略：

  • SQLite：备份数据目录（冷备期间尽量停止写入）。
  • MySQL/PG：定期 dump + binlog/WAL；关键表开启行级审计与慢查询分析。

• 前端构建失败（Bun/Vite 依赖问题）

  • 现已在 Docker 多阶段构建中做了 bun.lockb/bun.lock 兼容；若依旧失败，确认依赖版本并清缓存重试。

• Go 编译报错（版本/特性差异）

  • 使用 golang:1.25-alpine 的构建镜像；若上游新特性升级，请同步 go.mod 与相关文件的 build constraints。

• 治理中间件类型冲突

  • 跟随仓库的治理文件版本；当你裁剪治理策略或新增字段时，务必与路由层改动同步。

• 镜像拉取/运行失败

  • manifest unknown 多半是镜像未推送或名称/Tag 不一致；本地构建后可直接运行，无需先 push。

• 会话与加密错误

  • 大概率是 SESSION_SECRET 或 CRYPTO_SECRET 未配置或配置不一致；多实例部署确保一致。

Q1：NebulaGate 与 new-api 最大不同在哪？ A：在继承稳定中继的基础上，补齐商业化三件套——计费引擎、治理分流、运营可视化，以及支撑这些能力所需的幂等账本与生命周期调度。这让它从“可用工具”升级为“可经营系统”。

Q2：一定要用 MySQL/PG 吗？ A：单机试用可用 SQLite；生产强烈建议 MySQL/PG + Redis，提升可靠性与扩展性。

Q3：为什么强制要求 SESSION_SECRET？ A：它用于签名/加密会话与部分敏感数据。弱口令会带来被伪造/重放的严重风险。

Q4：Voucher 会不会被刷？ A：可通过有效期、适用范围、单账号上限、黑白名单、频次限制等手段降低风险；并借助 Ledger 实现异常核销的回滚与追责。

Q5：如何做成本控制？ A：设预算与阈值告警；治理策略中注入“成本护栏”，在接近预算时自动降级/限流；结合看板观察模型与通道的“性价比”。

• 细颗粒度配额：支持到“模型/路径/地区/标签”的额度策略。
• 治理策略商店：沉淀行业通用策略模板，一键开关。
• 审计导出与 SIEM 对接：将 Ledger/治理命中导出到企业合规系统。
• 多租户报表：面向组织视角的成本、用量、发券、核销报表。
• 策略回放与 A/B：对治理策略做离线回放与在线 A/B，以降低误杀率。

• 继承上游协议（请在仓库中附上 LICENSE 文件并在此处明确协议类型，例如 MIT/Apache-2.0）。
• 若你希望为商业化部署提供额外条款或品牌要求，可在 NOTICE/ENTERPRISE.md 中补充。

NebulaGate 的目标不是替代模型厂商，而是把复杂性吸收在网关层：让上层业务“像调用一个稳定的 OpenAI 接口一样”接入多厂商模型，同时把合规、成本、运营、审计这些“非功能需求”产品化。如果你正在寻找一套能“支持业务成长、又能兜住底线”的中台，NebulaGate 值得一试。