2026-10-21 18:24:30 +08:00
|
|
|
|
# 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 分片/多行/字节上限/完成标记/超时。
|
|
|
|
|
|
|
|
|
|
|
|
## 下一阶段优先级
|
|
|
|
|
|
|
2026-10-21 18:57:35 +08:00
|
|
|
|
1. 已完成 `V45`:异步创建 `Idempotency-Key`、请求哈希和数据库唯一性/锁语义,客户端同键重试不重复排队或预留。
|
|
|
|
|
|
2. 已完成 `V46` 的未知受理持久状态与冻结保护;审计化人工核账入口仍待实现。详情及本阶段 190 项后端验证结果见 `22-async-task-safety.md`。
|
|
|
|
|
|
3. 已增加异步已观察终态的结算恢复与待核账提示;继续完善执行路由快照、重试退避、人工对账和不可原子提交窗口。
|
2026-10-21 18:24:30 +08:00
|
|
|
|
4. HTTP Transport 生命周期继续拆分;真实 Redis 并发、租约回收与队列公平性回归。
|
|
|
|
|
|
5. 再进入用户/角色/会话、管理操作与密钥生命周期的后续安全优化;本轮模块改造不替代完整审计。
|