# 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 天灰度，再决定是否扩大到主路径。