80 lines
4.8 KiB
Markdown
80 lines
4.8 KiB
Markdown
# 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 接入持久化任务表与队列后解决。
|