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