5.9 KiB
5.9 KiB
Sub2API（subapi）集成准入清单（商用版）
- 文档日期：2026-03-16
- 评估对象：
sub2api（用户口语中的subapi） - 评估目标：判断是否可作为企业级 LLM 通用转发网关中的可集成模块
- 结论类型：产品与架构准入评估（非代码实现设计）
1. 执行结论（先看）
- 是否可集成：可以，但建议按“独立服务模块（HTTP/API）”方式集成，而不是 SDK 内嵌。
- 开源是否完整：整体完整度高（含后端、前端、部署、CI、安全扫描、测试）。
- 是否可直接商用：有条件可商用，但必须先完成法务与合规闸门，尤其是上游 ToS 风险审查。
- 当前建议：按“受控灰度 + 强安全基线 + 明确回滚”推进 PoC，不建议直接全量生产接入。
2. 关键证据（本地仓库）
- 许可证为 MIT（许可层面可商用）：
LICENSE - README 存在 ToS/研究用途提示（法务红线）：
README.md - 架构入口是服务化应用装配，不是轻量 SDK：
main.go - 路由与中间件注册耦合较强，偏完整网关服务：
gateway.go - CI、测试、安全扫描链路完整：
backend-ci.yml
security-scan.yml
3. 集成模式优先级（从稳到险）
- 模式 A：服务化集成（推荐）
- 做法：Sub2API 作为独立网关服务部署，你的主平台通过内部 API 调用。
- 优点：隔离风险、回滚简单、运维可控、便于灰度。
- 风险：多一层调用与运维成本。
- 模式 B：反向代理链路集成（次选）
- 做法：放在现有网关后作为特定模型/渠道的转发层。
- 优点：改动小、接入快。
- 风险：故障定位复杂，链路调试成本较高。
- 模式 C：Fork 后深度改造（谨慎）
- 做法：长期维护私有分支并做平台级改造。
- 优点：可控性最高。
- 风险：版本跟进成本大，研发负担重。
4. Go/No-Go 判定表（红黄绿）
- 红线（任一命中即 No-Go）
- 法务未完成上游 ToS 审查与书面结论。
- 生产仍启用
simple mode（跳过关键账单流程风险）。 - 允许
allow_insecure_http=true。 - 未启用预算/账单熔断。
- 黄线（可受限 Go，但必须限流灰度）
- 仅单可用区部署，无容灾。
- 无审计日志对接（请求、成本、调用人、模型）。
- 监控告警覆盖不足（延迟、错误率、成本突增）。
- 绿线（可推进扩大流量）
- 法务通过并形成可追溯结论。
- 生产基线配置全部达标。
- 7 天灰度稳定达标且完成回滚演练。
5. 生产硬化配置基线（必须项）
- 运行模式与账单
run_mode=standard（禁止simple）billing.circuit_breaker.enabled=true
- URL 安全策略（默认值需反转）
security.url_allowlist.enabled=truesecurity.url_allowlist.allow_insecure_http=falsesecurity.url_allowlist.allow_private_hosts=false（如必须访问内网，需最小范围白名单）
- 代理与入口安全
server.trusted_proxies显式设置（禁止宽泛信任）- 对外接口启用统一鉴权、限流、审计字段
- 功能范围控制
- 首发禁用不稳定能力（如 README 标注不建议生产依赖的模块）
gateway.sora_*不纳入首发 SLA
6. 主要技术风险（按优先级）
- 合规风险（最高）
- 代码 MIT 不等于业务合规，ToS 约束来自上游服务条款而非开源许可本身。
- 架构耦合风险
- Sub2API 更像完整网关服务，不是可插拔 SDK；深嵌会提升主平台耦合度。
- 配置误用风险
- 默认安全开关存在“偏宽松”项，若未硬化会放大 SSRF/内网访问风险面。
- 可用性与成本风险
- 若熔断、限流、成本审计不完整，易出现成本失控或突发级联故障。
7. 最小 PoC 验收标准（进入下一阶段前）
- 功能
- 覆盖你规划中的主流模型路由路径（至少 3 家提供商、核心模型调用成功率稳定）。
- 稳定性
- 在目标并发下，错误率与 p95 延迟满足内部 SLO。
- 成本
- 能按租户/应用/模型维度统计成本，异常成本有告警和自动熔断。
- 安全
- 完成白名单策略、鉴权、审计字段落库、关键接口限流。
- 可运维
- 一键回滚路径清晰，可在约定时限内完成演练回退。
8. 灰度与回滚策略（建议模板）
- 灰度阶段
- 阶段 1：5% 内部流量（1-2 天）
- 阶段 2：20% 非关键业务流量（2-3 天）
- 阶段 3：50% 混合流量（2 天）
- 阶段 4：100%（仅当全部指标连续达标）
- 观察指标
- 可用性：5xx 比例、超时率
- 性能：p95/p99 延迟
- 成本：每千 token 成本、异常突增
- 业务：成功调用率、用户投诉率
- 回滚触发阈值（任一满足即回滚）
- 连续 10 分钟错误率超过阈值
- p95 延迟连续 15 分钟超出阈值
- 单小时成本增幅异常（超过预算策略）
- 出现高危安全事件或合规告警
9. 对“是否能作为模块”的最终判定
- 可以作为模块集成：是，但应定义为“外部服务模块”，非“代码库模块”。
- 开源是否完整：是，工程资产完整度高。
- 当前最大阻碍：不是代码完整性，而是 ToS 合规与生产配置硬化。
- 建议决策：先完成法务闸门与 7 天灰度，再决定是否扩大到主路径。