Files
moyi-model-intelligence-hub/docs/09-java-control-plane-node.md

94 lines
7.3 KiB
Markdown
Raw Permalink 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.
# 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` | 登录用户 | 当前会话用户 |
| `PATCH /api/auth/account` | 登录用户 | 修改显示名称或密码 |
| `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、供应商、错误、管理员备注和软删除字段。
- `V11__invitation_secrets_and_account_settings.sql`:保存新邀请码的加密副本,支持管理端记录页再次复制。
Java 版本沿用现有 TypeScript 服务的表命名,便于后续迁移 RDS;供应商密钥只返回掩码,数据库保存 AES-GCM 密文,主密钥由 `CREDENTIAL_ENCRYPTION_KEY` 注入。生产环境应进一步使用 KMS/RAM 托管该主密钥。
## 本地启动
```powershell
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`。V9 起首次启动创建唯一 `super_admin`,现有同名且正常的 `admin` 自动升级,其他管理员保持 `admin`。服务器初始密码由 `deploy.py init` 随机生成并保存在 `.env.cloud` 的 `ADMIN_PASSWORD` 中,不是本地开发密码;启动不会覆盖已有密码。生产环境必须替换开发密码、密码 Pepper、数据库密码和 Redis 密码。
超级管理员可以通过用户详情调整其他用户的 `user` / `admin` 角色;普通管理员不能调用角色管理接口,也不能更改超级管理员。注册始终创建 `user`,不接受客户端指定角色。数据库通过唯一索引限制超级管理员数量。修改 `ADMIN_ACCOUNT` 不是转让超级管理员的方法,已有超级管理员与配置不一致时启动会拒绝创建第二个账号。
## 验收边界
本节点完成的是“控制面基础闭环 + 同步供应商转发 + Redis 网关保护 + 持久化任务队列”,不是生产网关完成版:
- 数据已写入 PostgreSQL;Redis 已用于 API Key 频率限制、API Key 并发租约、上游分组并发租约和 Redis Lua 原子操作。默认同步调用每 Key 每分钟 60 次(`GATEWAY_REQUESTS_PER_MINUTE`)、每 Key 同时 4 个请求(`GATEWAY_DEFAULT_KEY_CONCURRENCY`);分组并发由管理端模型分组的 `maxConcurrency` 配置,填 0 表示不设置 MOYI 分组上限,未配置时使用 `GATEWAY_DEFAULT_MODEL_CONCURRENCY`。Redis 不可用时网关返回 503,不会绕过保护直接请求上游;
- `/v1/chat/completions` 支持 OpenAI 兼容同步/流式文本聊天;真实供应商未配置 Key 时返回 503,只有 `provider-mock` 可以返回 Mock。V13 起按人民币分组售价预留并结算,详见 [流式与计费](16-streaming-chat-billing.md);
- `/v1/3d/tasks` 和 `/v1/video/tasks` 已提供数据库持久化 Mock worker;真实供应商执行器尚未替换,返回 501 而非伪造任务成功;
- Seedance、Tripo/VAST 的异步任务和 OSS 结果存储尚未迁移到 Java;
- 异步任务已持久化并提供按模型的排队上限(默认 100,可由 `TASK_MAX_QUEUED_PER_MODEL` 调整),但真实供应商执行器、优先级调度、价格/额度扣减和计费账单仍沿用下一节点计划;
- 模型调用记录会自动保存同步请求/响应和异步任务入队结果,输入输出中的 `authorization`、`api_key`、`token`、`secret`、`password` 等字段会脱敏,单个文本字段最多 8000 字符、单个 JSON 载荷最多 32000 字符;管理员可筛选、查看、备注、软删除和导出 CSV;
- 服务器测试部署参照 `11-server-test-deployment.md`;预编译包附带 JAR 和静态文件,服务器只需运行时基础镜像,不需要 Maven/Node。
## 下一节点
1. 为真实同步转发补充超时、重试、熔断、响应脱敏和用量事件记录;
2. 接入 Redis 限流、并发计数、幂等键和分布式异步任务状态;
3. 用 Tripo/Seedance 替换 Mock 执行器,并接入 OSS 私有对象;
4. 用 RDS、Redis、OSS 的测试资源完成云上验收,再切换前端的 Java API 地址。