lijiaoqiao/docs/subapi_integration_compat_security_reliability_design_v1_2026-03-17.md

Subapi 集成兼容性、安全与运维可靠性设计（v1.1）

• 版本：v1.1
• 日期：2026-03-24
• 适用阶段：S1-S2
• 关联文档：
  • subapi_connector_contract_v1_2026-03-17.md
  • sub2api_integration_readiness_checklist_2026-03-16.md
  • router_core_takeover_execution_plan_v3_2026-03-17.md
  • acceptance_gate_single_source_v1_2026-03-18.md（v1.1）
  • llm_gateway_subapi_evolution_plan_v4_2_2026-03-24.md

1. 结论先行（回答四个核心问题）

1. 我们是否考虑了与 subapi 的技术兼容性：

• 已考虑了“契约层兼容”和“灰度回滚”，但还缺“版本漂移自动检测 + 协议回归自动阻断 + 兼容风险分级”的闭环。

2. 我们是否了解 subapi 的安全风险：

• 已识别部分风险，但需要把风险从“清单级”升级到“强制控制级”。
• 典型高风险包括：URL allowlist 默认关闭、私网/HTTP 默认放开、Gemini 路径保留 query key 兼容、Simple 模式会跳过关键计费校验。

3. 集成 subapi 如何防止风险：

• 必须采用“外部服务模块化 + 网络隔离 + 配置硬化 + 双层鉴权 + 契约测试闸门 + 安全告警”组合拳，不接受单点措施。

4. 架构是否兼顾运维简单和可靠性：

• 当前方向正确（灰度、回滚、观测已有），但还需补齐“最小化运维复杂度”的具体机制：单一控制面、统一配置发布、标准化 runbook、以及故障域隔离（cell 化）。

2. 兼容性设计（防止实施期协议翻车）

2.1 已有基础（可复用）

1. Connector 契约已定义 canonical 端点、错误归一、流式边界、重试约束。
2. S2 迁移路径已定义 Wave 灰度与 stop/go 条件。
3. 已有接管率与验收用例文档可做质量门禁基础。

2.2 仍需补齐的兼容闭环

新增三层闸门（必须全部启用）：

1. Schema Gate（接口形态）

• 校验请求/响应 JSON 结构、必填字段、字段类型、错误码结构。
• 重点接口：/v1/messages、/v1/chat/completions、/v1/responses、/v1beta/models/*。

2. Behavior Gate（行为语义）

• 校验 streaming 行为、首 token 前后错误处理、no-replay 规则。
• 校验 header 优先级、模型映射、会话粘性、fallback 行为。

3. Performance Gate（性能与稳定）

• 校验 P95、5xx、超时率、账务差错率、幂等冲突率。
• 不达标直接阻断升级，回退上一稳定版本。

2.3 兼容性风险分级（建议）

等级	定义	示例	处理策略
P0	会导致错误计费、协议不可用或大面积失败	流式 replay、错误码语义变化导致无限重试	立即阻断上线，强制回退
P1	影响部分场景或部分租户	某端点字段新增导致旧 SDK 解析失败	灰度暂停，48h 内修复
P2	非核心功能偏差	次要元数据缺失	记录并进入下个迭代

3. subapi 安全风险台账（针对当前代码事实）

3.1 配置默认值风险

1. security.url_allowlist.enabled=false（默认关闭）。
2. allow_private_hosts=true、allow_insecure_http=true（默认放开）。
3. 这意味着若不硬化，SSRF/内网访问风险面会扩大。

3.2 认证与参数风险

1. 常规 API 已拒绝 query key（key/api_key）。
2. 但 Gemini 路径保留了 query key 兼容（/v1beta*），需要在我方入口再做强制拦截与改写策略。

3.3 运行模式风险

1. run_mode=simple 下，认证后会跳过部分计费/订阅校验流程。
2. 生产若误用 simple，会带来额度与计费控制失效风险。

3.4 代理与来源 IP 风险

1. server.trusted_proxies 默认空数组。
2. 虽有告警日志，但若部署链路未正确设置，来源 IP 信任链可能失真，影响风控与审计。

3.5 合规与法律风险

1. 上游仓库 README 明确提示 ToS 风险与研究用途声明。
2. MIT 许可仅覆盖开源代码使用，不覆盖上游模型服务条款合规。

4. 风险防护设计（集成必须项）

4.1 网络与边界隔离

1. subapi 只允许内网访问，不直接暴露公网。
2. 主网关与 subapi 之间启用 mTLS（至少双向证书校验）。
3. 出网层做 egress allowlist（域名/IP 双层），禁直连内网和不受信目的地。

4.2 配置硬化基线（生产强制）

1. run_mode=standard。
2. security.url_allowlist.enabled=true。
3. security.url_allowlist.allow_private_hosts=false。
4. security.url_allowlist.allow_insecure_http=false。
5. billing.circuit_breaker.enabled=true。
6. server.trusted_proxies 必须显式配置。

4.3 认证与密钥策略

1. 我方北向入口禁止 query key；统一只接收 header 鉴权。
2. 对 Gemini 兼容流量，在入口层将 query key 转换为 header 后再转发，外部请求直接带 query key 一律拒绝。
3. API Key 与上游凭证分离管理，凭证仅在 Adapter 层短时解密。
4. 需求方仅可使用平台签发凭证访问平台入口，platform_credential_ingress_coverage_pct 必须为 100%。
5. 禁止向需求方返回供应方上游凭证（API/控制台/导出/错误信息均不允许）。
6. 需求方绕过平台直连供应方视为 P0 安全事件，必须可观测、可告警、可阻断。

4.4 版本与发布治理

1. 固定 subapi 精确版本（vX.Y.Z），禁止漂移。
2. 每次升级必须通过 Schema/Behavior/Performance 三重 Gate。
3. 灰度比例：5% -> 20% -> 50% -> 100%。
4. 任一 P0 风险触发，自动回退上一稳定版本。

4.5 观测与审计

1. 强制 request_id 全链路透传。
2. 记录 router_engine、inbound_endpoint、upstream_endpoint、request_type。
3. 安全告警纳入统一事件中心：

• query key 拦截次数
• 非法上游域名命中
• 私网地址访问拦截
• 账务冲突率突增
• 供应方上游凭证泄露事件（supplier_credential_exposure_events）
• 需求方绕过平台直连供应方事件（direct_supplier_call_by_consumer_events）
• 平台凭证入站覆盖率下降（platform_credential_ingress_coverage_pct < 100%）

5. 运维简单 + 可靠性架构（目标态）

5.1 运维简单（减少人肉操作）

1. 单一控制面：所有路由开关、灰度比例、熔断阈值在我方控制面发布。
2. 单一发布流水线：subapi 升级与 Router Core 升级共享同一套 Gate 与回滚动作。
3. 标准化运行手册：按“告警 -> 判断 -> 操作 -> 验证”四段式 Runbook 固化。

5.2 高可靠（避免级联故障）

1. 故障域隔离（Cell）：按租户或区域切分 subapi 实例池，避免单点故障扩散。
2. 双通路兜底：自研主路径 + subapi connector 兜底，并支持一键回切。
3. 幂等与补偿：请求级幂等扣费 + 冲突告警 + 对账补偿任务。
4. 流式保护：首字输出后禁止 replay，防止双流拼接与重复扣费。

5.3 SLO 与错误预算（建议）

1. 可用性 SLO：99.9%（网关维度）。
2. 附加延迟 SLO：P95 <= 60ms。
3. 账务正确性 SLO：差错率 <= 0.1%，冲突率 <= 0.01%。
4. 每周审查 error budget；超预算自动冻结升波。

6. 两周内可落地动作（最小闭环）

1. 新增“兼容三重 Gate”流水线，并接入升级流程。
2. 生产配置硬化巡检（按 4.2 清单逐项验收）。
3. 在入口层落地“query key 全拦截（含 Gemini 兼容改写）”。
4. 建立安全告警面板（SSRF 拦截、query key 拦截、账务冲突）。
5. 增加凭证边界专项检查（上游凭证零外发 + 平台凭证入站覆盖率100%）。
6. 完成一次“升级 + 灰度 + 自动回滚”演练并沉淀复盘。

7. 验收标准（本设计是否落地）

1. 任一 subapi 升级都能产出 Gate 报告并可追溯。
2. 生产环境不存在宽松高风险配置（4.2 全部满足）。
3. 发生兼容或安全异常时，30 分钟内可回切到稳定版本。
4. 需求方仅使用平台凭证入站，platform_credential_ingress_coverage_pct = 100%。
5. supplier_credential_exposure_events = 0 且 direct_supplier_call_by_consumer_events = 0。
6. 运维团队按 Runbook 可独立处置常见告警，无需临时拍脑袋决策。

8. 代码证据（用于本设计判断）

1. 默认安全配置与告警日志： backend/internal/config/config.go
2. API Key 鉴权与 simple mode 逻辑： backend/internal/server/middleware/api_key_auth.go
3. Gemini 认证优先级与 query key 兼容： backend/internal/server/middleware/api_key_auth_google.go
4. URL 校验器（含 allowlist/private/insecure 与 DNS rebinding 注释）： backend/internal/util/urlvalidator/validator.go
5. trusted proxies 与 release 模式告警： backend/internal/server/http.go
6. 上游 ToS 风险提示： README.md（sub2api 仓库）

9. 执行任务单（新增）

为将本设计转换为可执行排期，新增任务单：

1. subapi_integration_risk_controls_execution_tasks_v1_2026-03-17.md
   • 两周里程碑（2026-03-18 至 2026-03-31）
   • 任务 ID / 责任角色 / 截止日期 / 验收标准 / 证据产物
   • Daily Gate / Weekly Gate / 回滚演练闭环
2. subapi_expert_review_wargame_plan_v1_2026-03-17.md
   • 专家组成、对抗式博弈规则、评分模型与一票否决条件
   • 四轮评审（架构/兼容计费/安全合规/可靠性演练）与最终决议机制