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

80 lines
4.8 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 Control Plane
D3 的身份与权限服务,负责邀请码注册、登录会话、用户角色、管理员接口和认证审计。它与 Otari 分离,前端不直接持有 Otari Master Key 或供应商密钥。
## 本地开发
### 内存联调
如果暂时只验证登录、邀请码和权限,可以使用内存仓库,不需要 PostgreSQL:
```powershell
cd control-plane
Copy-Item .env.memory.example .env
# 在 .env 中设置 ADMIN_PASSWORD,且不要设置 DATABASE_URL
pnpm install
pnpm dev
```
内存仓库重启后会清空用户、邀请码和会话,只适合开发联调。
### PostgreSQL 持久化
```powershell
cd control-plane
Copy-Item .env.example .env
pnpm install
pnpm migrate
pnpm seed:admin
pnpm dev
```
默认监听 `http://127.0.0.1:8787`。没有设置 `DATABASE_URL` 时,服务可以使用内存仓库启动,用于接口联调;正式开发和测试应使用 PostgreSQL。
## 接口
- `POST /api/auth/register`:邀请码注册,账号支持邮箱或手机号。
- `POST /api/auth/login`:账号密码登录,返回 HttpOnly 会话 Cookie。
- `GET /api/auth/me`:读取当前会话用户。
- `POST /api/auth/logout`:撤销当前会话。
- `GET /api/models`:读取当前供应商和统一模型目录。
- `GET|POST /api/projects`:查看或创建当前用户拥有的工作区/项目。
- `GET|POST /api/keys`:查看或创建平台调用 Key;明文 Key 只在创建响应中返回一次。
- `POST /api/keys/:id/models`:在 Key 创建后配置可调用的具体模型。
- `POST /api/keys/:id/revoke`:撤销当前用户自己的平台 Key。
- `GET /v1/models`:使用 `Authorization: Bearer <MOYI_KEY>` 查询可调用模型。
- `POST /v1/chat/completions`:OpenAI 兼容的同步文本/多模态调用;按目录路由至 DeepSeek、Kimi 或 GLM。
- `POST /v1/3d/tasks`、`GET /v1/tasks/:id`:Mock 异步 3D 任务创建与查询。
- `POST /v1/video/tasks`、`GET /v1/tasks/:id`:Seedance 异步视频任务创建与查询。
- `GET /api/admin/users`:管理员用户列表。
- `GET|POST /api/admin/invitations`:管理员查看或生成邀请码。
- `POST /api/admin/invitations/:id/revoke`:停用邀请码。
- `GET /api/admin/audit`:管理员查看认证审计。
- `GET|POST /api/admin/providers`:管理员查看或登记供应商适配位。
- `GET|POST /api/admin/models`:管理员查看或登记统一模型目录。
第一版暂不实现短信/邮件真实验证码;注册页面保留验证码入口但不以它作为后端注册条件,邀请码、邮箱/手机号和账号密码是当前有效的注册条件。
## 首批供应商
| 供应商 | 接口类型 | 服务端配置 | 当前状态 |
|---|---|---|---|
| DeepSeek | OpenAI 兼容 Chat Completions | `DEEPSEEK_API_KEY`、`DEEPSEEK_BASE_URL` | 同步转发已接入,流式转发待下一节点 |
| 月之暗面 Kimi | OpenAI 兼容 Chat Completions | `KIMI_API_KEY`、`KIMI_BASE_URL` | 同步转发已接入,流式转发待下一节点 |
| 智谱 GLM | OpenAI 兼容 Chat Completions | `ZHIPU_API_KEY`、`ZHIPU_BASE_URL` | 同步转发已接入,流式转发待下一节点 |
| 字节 Seedance | 火山方舟异步视频任务 | `VOLCENGINE_API_KEY`、`VOLCENGINE_BASE_URL` | 创建任务与轮询已接入 |
模型名称可通过 `.env` 中的 `*_MODEL` 变量覆盖,不需要修改网关代码。没有配置对应 API Key 时,模型仍可在目录中展示,但调用会返回 `PROVIDER_NOT_CONFIGURED`,不会伪造供应商结果。真实密钥只能放在未提交的本地 `.env` 或服务器密钥管理服务中。
## 安全约束
- 数据库仅保存密码哈希、邀请码摘要和会话摘要,不保存明文密码、明文邀请码或会话 Token。
- 生产环境必须设置随机的 `AUTH_PASSWORD_PEPPER`、强管理员密码和 HTTPS。
- 管理员接口由 Control Plane 服务端角色校验保护,隐藏前端菜单不构成权限控制。
- D4 的 Mock Key、项目和模型目录暂存于内存仓库;PostgreSQL 迁移已准备 `model_providers`、`model_catalog`、`model_projects` 和 `platform_api_keys` 表,接真实持久化时复用同一接口。
- 额度界面统一按人民币 `¥` 展示;内测额度由管理员手动发放,真实计量、扣费和账单在后续节点实现。
- 上游供应商密钥不进入模型目录或用户响应,后续由 Provider Adapter 通过环境变量/密钥管理服务读取。
- Tripo 3D 适配器读取 `TRIPO_API_KEY` 和可选的 `TRIPO_BASE_URL`;真实值只放本地 `.env` 或服务器密钥管理,不得写入 Git。
- DeepSeek、Kimi、GLM 和 Seedance 适配器只读取服务端环境变量,API Key 不进入模型目录、日志或用户响应。
- 当前 Tripo 任务归属映射仍随 Control Plane 进程保存在内存中,服务重启后会清空;D6 接入持久化任务表与队列后解决。