Files

5.0 KiB
Raw Permalink 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。

V47 冻结异步 provider/model 绑定并约束已证明的上游任务身份;V48 增加仅追加核账收据。管理端“价格版本与成本对账”提供人工核账,可根据证据恢复只读轮询、确认失败释放原冻结、确认成功并按原价和实际用量结算。操作使用管理员会话、版本检查、UUID 幂等收据和与钱包同事务的审计;worker 和人工操作共用 TaskSettlementService,不另写扣费逻辑。历史无法证明的已受理绑定不能猜测补齐。详见 ../docs/23-audited-task-reconciliation.md;尚无双人审批,不等同于完整财务流程。

同步和原生调用在结算前单独提交精简用量快照(Flyway V44)。快照已持久化而账本事务失败时,接口返回 SETTLEMENT_PENDING,冻结额度保留,由后台恢复任务重试结算。该快照不保存提示词、生成内容或密钥;不能将其当作响应重放存储。若数据库在快照写入前已不可用,则尚不能保证结果的持久恢复,必须结合上游记录核对。

provider.credentials.UpstreamCredentialResolver 共享密钥池解析与轮转;provider.transport.SseEventReader 专门负责 SSE 解帧、UTF-8 校验和有界读取,不承担风控、路由或计费。完整模块边界、验证命令和后续风险清单见 ../docs/21-api-request-modularization.md。

V49 增加数据库共享登录窗口;所有新密码统一 8–256 位,改密撤销全部浏览器会话,登录/改密/重置通过用户行锁协调。初次创建管理员必须显式配置非默认密码;已存在管理员不会被启动配置重置。API Key 不随改密自动撤销。

provider.transport.BoundedHttpTransport 已供异步 JSON/multipart/音频/媒体读取复用:接收中限量、总期限覆盖响应体、取消订阅、不自动跟随重定向。它不等于 SSRF 已解决,DNS 预检与实际解析的绑定仍需补齐;同步/SSE 生命周期和 Codex 长请求亦未统一完成。详见 ../docs/25-auth-and-bounded-transport.md 与 ../docs/24-security-and-cpr-task-tracker.md。

Flyway 脚本位于 src/main/resources/db/migration/,与现有 TypeScript 服务使用同一套基础表命名,后续迁移数据时可以按表逐步切换。

本目录的镜像由 infra/moyi/docker-compose.yml 构建。生产发布前应验证目标渠道能力、价格快照、Redis 准入和 PostgreSQL 集成测试;本地通过不代表线上部署验收。TypeScript Control Plane 保留为历史参考实现,不与 Java 后端同时承担同一钱包的写入。