Files
moyi-model-intelligence-hub/docs/21-api-request-modularization.md
T

71 lines
7.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API 请求模块化与风控扩展边界
更新日期:2026-10-21。本文对应 Java 后端的第一阶段模块化改造,不代表全部安全审计问题已解决或已上线。
## 模块分工
采用同一 Spring Boot 应用内的模块化单体,暂不拆微服务或 Maven 子工程,以保留钱包事务的一致性。
| 模块 | 负责 | 不负责 |
| --- | --- | --- |
| Gateway / Native / Playground / Task HTTP 入口 | 身份认证、Key 所属权检查、来源标记、早期 RPM 限流、协议规范化 | 风控规则的业务实现、单独复制账务流程 |
| `gateway.request` | 不可变请求上下文、风控规则与决策、同步请求执行编排、准入租约、结算持久化异常分类 | 上游凭据、HTTP/SSE 解析、异步轮询状态机 |
| `gateway.ChatMeter` / `NativeProtocolMeter` | 请求合法性、用量规范化、协议完成条件 | 选择账号、重试、修改余额 |
| `provider.credentials` | 渠道/路由/模型密钥池解析、去重、原子轮转 | 账号冷却、是否安全重试、任务凭据指纹绑定 |
| `provider.transport.SseEventReader` | SSE 解帧、严格 UTF-8、单行/事件字符上限和总响应字节上限 | 扣费、HTTP 响应写出、路由切换 |
| Provider / Failover / UpstreamHealth | 上游协议适配、HTTP 生命周期、Key 健康、授权约束下的安全换路 | 绕过风险策略、复制钱包事务 |
| Wallet / Usage | 价格快照、预留、结算、释放、持久化审计与恢复 | 估算用量后扣费、透明重放上游生成 |
| AsyncTaskService | 通过共享风险门禁后排队,worker 提交、轮询和终态事务 | 复用同步请求的短生命周期并发租约 |
同步调用顺序:认证 → 基础 RPM → 路由与协议校验 → 风控 → 并发准入 → 钱包预留 → 上游调用 → 精简用量快照 → 原子结算 → 释放准入。
异步创建顺序:认证 → 基础 RPM → 路由与输入校验 → 风控 → 数据库队列准入及价格快照/预留 → worker。异步的长任务租约继续由原有任务调度管理,不能使用同步 Controller 的生命周期。
## 风控规则接口
- 通过 Spring 注册 `ApiRequestRiskRule`,每个规则需要唯一、稳定的小写 ID。规则只接收 `ApiRequestContext`,不能读取原始 API Key、Authorization 或请求正文。
- `GATEWAY_RISK_MODE=shadow` 为默认值:规则命中或规则异常只形成影子信号,不阻断请求;`enforce` 下才会拒绝、限速或因策略异常返回 503。
- 未注册规则时不会凭空产生反欺诈能力。部署配置中写 `enforce` 也不等于已实现有效风控。
- 多规则时拒绝优先于限速,限速采用命中规则中的最长等待时间。非法模式在启动时失败,不能默默关闭安全检查。
- 原有基础频率与用户/Key/模型并发策略继续生效。不能因为增加高级风控而让非法请求绕过基础 RPM。
## 来源与隐私
- 公网入口固定标记为 `API`;只有已经验证会话和 Key 所属权的 Playground 入口使用 `PLAYGROUND`。`X-Moyi-Source` 仅保留为 Playground 的跨站请求约束之一,不作为可信来源证明。
- IP 由 Servlet 的 `getRemoteAddr()` 获取。不直接读取客户端 `X-Forwarded-For`;需要真实 IP 时,应由明确可信的反向代理/Tomcat 配置提供。
- 风控日志不写 IP、User-Agent、密钥或原始正文;上下文/元数据的默认字符串表示也不含 IP。已有用量审计可保存经脱敏的请求响应,保留策略与访问权限需要独立评估。
- 来源/IP 显式传入钱包及任务用量记录,避免仅依赖线程局部 HTTP 上下文。数据库中的 IP 属于敏感审计数据,不应出现在普通风控日志中。
## 结算与恢复
- `V44__recoverable_chat_settlement.sql` 新增归一化用量与耗时快照。快照独立于最终扣款事务提交,不保存提示词、工具参数、生成内容或凭据。
- 正常路径仍用原始响应完成审计;账本写入失败后使用精简用量恢复,不能保证重放原始生成内容。
- 已有有效快照时,账本异常返回 `SETTLEMENT_PENDING`,不能直接调用 `fail()` 释放成功调用的冻结额度。过期恢复任务逐笔事务重试,并利用行锁与原有终态检查确保只扣一次。
- 无完整结果或有效用量时仍不能估算扣费;缺少快照的过期孤儿请求沿用释放策略。
- **剩余窗口:**数据库在快照提交前不可用、或进程在收到上游结果后而快照提交前崩溃,仍可能没有可自动恢复的用量。需配合上游 request ID、对账记录和后续持久执行状态设计,不能宣称端到端 exactly-once 已实现。
- `SETTLEMENT_PENDING` 后不能用新的幂等键自动重新生成。同步既有幂等语义保持为相同用户、相同幂等键不重复调用;结果查询/重放接口尚未实现。
## 保持不变的上游约束
密钥顺序保留为路由池 → provider+model 池 → 渠道池;渠道池内保留原实现各自的 fallback/alias 顺序。轮转状态保存在客户端实例中,不随动态 DB 渠道读取重置。异步轮询继续绑定提交时 Key 的指纹,禁止随意换账号查询已有任务。
超时和发送结果不明时不透明重放;SSE 已取得后不换路。确定的请求参数错误兼容重试、明确未受理的账号拒绝及备用路由授权约束仍由原 Provider/Failover 决定。HTTP 生命周期、整体截止时间、健康冷却目前仍在 Provider 门面内,后续可继续提取为独立 Transport。
## 验证
本轮在 Docker 内使用 Java 21、Maven 3.9.9 和独立 PostgreSQL 15.18 执行 `clean verify`:157 项测试,0 失败、0 错误、0 跳过;生成 Spring Boot JAR 成功。临时数据库已清理,未执行线上发布或业务库迁移。该结果不等于真实上游、生产数据库或真实 Redis 并发的完整验收。
运行 Java 21 / Maven:`mvn -B -ntp -f control-plane-java/pom.xml verify`。
PostgreSQL 集成测试由 `MOYI_AUTH_TEST_JDBC_URL` 启用,当前测试限制为本机回环地址,并使用专用测试账号 `moyi_role_test`。必须使用独立临时数据库;测试会创建/删除随机 schema,不能指向业务或生产数据库。Docker 内运行时,`127.0.0.1` 指向容器自身;应使用与测试数据库容器共享的 network namespace,而非将宿主机回环地址直接传入普通 Maven 容器。
回归范围包括:风控 shadow/enforce/异常、所有主要调用入口拒绝时无准入和预留、早期 RPM、来源伪造、IP 显式审计、结算失败与恢复一次扣费、密钥优先级/轮转/任务指纹、SSE 分片/多行/字节上限/完成标记/超时。
## 下一阶段优先级
1. 异步创建 `Idempotency-Key`、请求哈希和数据库唯一性/锁语义,保证客户端重试不重复排队或预留。
2. 异步上游提交结果未知的持久状态与核账入口:区分明确未受理、已受理可轮询、结果未知,禁止统一退款后自动重试。
3. 执行中元数据和计量快照的崩溃窗口、重试退避、人工对账与待结算可视化。
4. HTTP Transport 生命周期继续拆分;真实 Redis 并发、租约回收与队列公平性回归。
5. 再进入用户/角色/会话、管理操作与密钥生命周期的后续安全优化;本轮模块改造不替代完整审计。