Files
moyi-model-intelligence-hub/control-plane-java/README.md
T

27 lines
3.2 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.
# MOYI Java Control Plane
这是 MOYI Control Plane 的 Java 版本,目标运行时为 Java 21,框架为 Spring Boot。当前包括健康检查、Flyway 数据库迁移、邀请码认证、用户会话、供应商/模型目录、项目、API Key、模型权限、同步与原生协议网关、异步任务、计费和用量审计。
目标依赖边界:
- PostgreSQL:用户、会话、供应商、模型目录、Key、任务队列、幂等、上游账号健康、计费和审计等持久化数据。
- Redis:请求频率、并发准入租约;当前会话、调用幂等和异步任务队列以 PostgreSQL 持久化为准。
- OSS:3D、图片、视频等任务结果和用户上传文件;只保存对象元数据,应用不保存大文件本体。
- Provider Adapter:服务端调用 DeepSeek、Kimi、GLM、Seedance、Tripo/VAST 和后续中转渠道。
## API 请求模块边界
`gateway.request` 是统一的模型 API 请求应用边界。HTTP/Playground 控制器负责认证、协议解析和规范化;请求模块接收不含凭据、提示词和原始请求体的 `ApiRequestContext`,先执行风险策略,再通过准入租约包住钱包预留、Provider 调用和最终结算。Chat、原生协议和异步任务提交共用该风险策略。
协议字段映射留在各自 Meter/Adapter;`ApiRequestRiskRule` 只能读取最小化上下文并返回决策,不能调用 Provider 或改账。新增协议时应复用准入、风控和账务边界,而不是在 Controller 中另写一套钱包/重试流程。默认 `GATEWAY_RISK_MODE=shadow` 仅记录规则 ID,不改变调用;只有显式部署规则并设置 `enforce` 才会拒绝或限速。请求来源由服务端路由确定,不能信任 `X-Moyi-Source` 作为风控分类。
账务不变量:风险拒绝必须先于并发准入和钱包预留;预留使用价格快照;失败释放和成功结算沿用现有事务处理;不完整流或无效用量不得结算。上游提交结果未知时的异步核账状态机与异步创建幂等将在后续阶段单独处理。
同步和原生调用在结算前单独提交精简用量快照(Flyway `V44`)。快照已持久化而账本事务失败时,接口返回 `SETTLEMENT_PENDING`,冻结额度保留,由后台恢复任务重试结算。该快照不保存提示词、生成内容或密钥;不能将其当作响应重放存储。若数据库在快照写入前已不可用,则尚不能保证结果的持久恢复,必须结合上游记录核对。
`provider.credentials.UpstreamCredentialResolver` 共享密钥池解析与轮转;`provider.transport.SseEventReader` 专门负责 SSE 解帧、UTF-8 校验和有界读取,不承担风控、路由或计费。完整模块边界、验证命令和后续风险清单见 `../docs/21-api-request-modularization.md`。
Flyway 脚本位于 `src/main/resources/db/migration/`,与现有 TypeScript 服务使用同一套基础表命名,后续迁移数据时可以按表逐步切换。
本目录的镜像由 `infra/moyi/docker-compose.yml` 构建。生产发布前应验证目标渠道能力、价格快照、Redis 准入和 PostgreSQL 集成测试;本地通过不代表线上部署验收。TypeScript Control Plane 保留为历史参考实现,不与 Java 后端同时承担同一钱包的写入。