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

3.7 KiB
Raw Blame History

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 作为风控分类。

账务不变量:风险拒绝必须先于并发准入和钱包预留;预留使用价格快照;已确认失败的释放和成功结算沿用原子事务;不完整流或无效用量不得估算扣费。

异步创建支持用户级 Idempotency-Key(V45),同键同请求返回原任务,同键不同请求返回 409。异步上游受理未知、回执丢失、worker 中断或轮询期限到期时进入 reconciling(V46),保留冻结与预算占用,不自动重发/退款。已观察的生成结果先持久化再结算,账本失败只重试本地结算。发布时须先停旧 worker,不能混跑旧的未知结果退款逻辑。详见 docs/22-async-task-safety.md;受审计的人工核账入口仍属下一阶段。

同步和原生调用在结算前单独提交精简用量快照(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 后端同时承担同一钱包的写入。