Files
moyi-model-intelligence-hub/docs/09-java-control-plane-node.md
T
2026-09-08 20:43:04 +08:00

6.0 KiB
Raw Blame History

Java Control Plane 节点一:基础控制面

节点目标

把前端原型依赖的核心控制面接口迁移到 Java 21 / Spring Boot,并让本地 Docker Compose 可以使用同一套数据库迁移脚本启动:

  • 邀请码注册、账号密码登录、会话 Cookie、退出登录;
  • 当前用户、管理员用户列表、邀请码管理、审计记录;
  • 供应商和模型目录读取;
  • 项目创建与查询;
  • API Key 创建、明文一次性返回、撤销和模型权限配置;
  • 最小 OpenAI 兼容 GET /v1/models 与 POST /v1/chat/completions 接口;DeepSeek、Kimi、GLM 配置服务端 Key 后走真实上游,未配置时保留 Mock;
  • 持久化的 3D/视频 Mock 异步任务、轮询和结果结构,保证 Java Compose 下任务中心可联调。

已落地接口

接口 权限 用途
POST /api/auth/login 公开 账号密码登录
POST /api/auth/register 公开 邀请码注册
GET /api/auth/me 登录用户 当前会话用户
POST /api/auth/logout 登录用户 撤销当前会话
GET /api/models 登录用户 用户端模型广场目录
GET/POST /api/projects 登录用户 工作区/项目基础管理
GET/POST /api/keys 登录用户 API Key 管理
POST /api/keys/{id}/models Key 所属用户 修改模型权限
POST /api/keys/{id}/revoke Key 所属用户 撤销 API Key
GET/POST /api/admin/providers 管理员 供应商目录管理
GET/POST /api/admin/models 管理员 模型目录管理
GET/POST /api/admin/invitations 管理员 邀请码管理
GET /api/admin/users 管理员 用户列表
GET /api/admin/audit 管理员 审计记录
GET /api/admin/usage 管理员 分页查询模型调用/任务记录,可按用户、分发 Key、模型、状态和时间筛选
GET /api/admin/usage/{id} 管理员 查看单条调用输入、输出、错误和元数据
PATCH /api/admin/usage/{id} 管理员 修改管理员备注
DELETE /api/admin/usage/{id} 管理员 软删除单条调用记录
DELETE /api/admin/usage?ids=... 管理员 批量软删除调用记录
GET /api/admin/usage/export 管理员 按当前筛选条件导出 UTF-8 CSV
GET /v1/models 平台 API Key 返回该 Key 有权限的模型
POST /v1/chat/completions 平台 API Key 同步聊天调用(已配置供应商 Key 时转发真实上游)
POST /v1/3d/tasks 平台 API Key 创建 3D 异步任务(当前 Mock 执行器)
POST /v1/video/tasks 平台 API Key 创建视频异步任务(当前 Mock 执行器)
GET /v1/tasks/{id} 平台 API Key 查询任务状态和结果
GET /v1/tasks 平台 API Key 查询当前 Key 所属用户的最近任务
GET /api/tasks 登录会话 用户端恢复当前用户的最近任务

数据库迁移

  • V1__auth.sql:用户、邀请码、会话、审计;
  • V2__catalog_and_keys.sql:供应商、模型目录、API Key;
  • V3__projects.sql:项目和 Key 项目归属;
  • V4__catalog_channels.sql:供应商凭证元数据、模型来源分组、价格和并发字段;
  • V5__usage_events.sql:用量事件基础表;
  • V6__seed_catalog.sql:本地首批模型目录初始数据,可由管理员继续增删改造。
  • V7__async_tasks.sql:3D/视频异步任务、状态和结果元数据。
  • V8__usage_payload_audit.sql:调用/任务输入输出、分发 Key、供应商、错误、管理员备注和软删除字段。

Java 版本沿用现有 TypeScript 服务的表命名,便于后续迁移 RDS;供应商密钥只返回掩码,数据库保存 AES-GCM 密文,主密钥由 CREDENTIAL_ENCRYPTION_KEY 注入。生产环境应进一步使用 KMS/RAM 托管该主密钥。

本地启动

cd infra/moyi
Copy-Item .env.example .env
docker compose build
docker compose up -d
Invoke-WebRequest http://localhost:8080/health

默认开发管理员来自 .env:ADMIN_ACCOUNT=adimin,首次启动时由 Java 服务创建。生产环境必须替换管理员密码、密码 Pepper、数据库密码和 Redis 密码。

验收边界

本节点完成的是“控制面基础闭环 + 同步供应商转发 + Redis 网关保护 + 持久化任务队列”,不是生产网关完成版:

  • 数据已写入 PostgreSQL;Redis 已用于按 API Key 限流、按模型并发租约和 Redis Lua 原子操作。默认同步调用每 Key 每分钟 60 次、模型并发 4,均可通过环境变量调整;Redis 不可用时网关返回 503,不会绕过保护直接请求上游;
  • /v1/chat/completions 已支持 DeepSeek、Kimi、GLM 的 OpenAI 兼容转发;管理员在目录中新增带凭证的兼容供应商后,也可按模型绑定动态渠道;未配置 Key 时返回 Mock,流式响应暂未开放;
  • /v1/3d/tasks 和 /v1/video/tasks 已提供数据库持久化 Mock worker,真实供应商执行器尚未替换;
  • Seedance、Tripo/VAST 的异步任务和 OSS 结果存储尚未迁移到 Java;
  • 异步任务已持久化并提供按模型的排队上限(默认 100,可由 TASK_MAX_QUEUED_PER_MODEL 调整),但真实供应商执行器、优先级调度、价格/额度扣减和计费账单仍沿用下一节点计划;
  • 模型调用记录会自动保存同步请求/响应和异步任务入队结果,输入输出中的 authorization、api_key、token、secret、password 等字段会脱敏,单个文本字段最多 8000 字符、单个 JSON 载荷最多 32000 字符;管理员可筛选、查看、备注、软删除和导出 CSV;
  • Docker 镜像需要在具备 Maven 和 Docker daemon 的环境中构建验证。

下一节点

  1. 为真实同步转发补充超时、重试、熔断、响应脱敏和用量事件记录;
  2. 接入 Redis 限流、并发计数、幂等键和分布式异步任务状态;
  3. 用 Tripo/Seedance 替换 Mock 执行器,并接入 OSS 私有对象;
  4. 用 RDS、Redis、OSS 的测试资源完成云上验收,再切换前端的 Java API 地址。