chore: initial public snapshot for github upload

docs/sub2api_integration_readiness_checklist_2026-03-16.md

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