docs: record D4 integration inputs
This commit is contained in:
1 parent
fdf3a328ce
commit
78ed3c1103
11 files changed
+162
-29
No files matched your search
@@ -299,6 +299,7 @@ MaaS 模型服务与应用开发
|
|||||||
- [双端产品形态与开源技术底座](docs/03-dual-portal-and-open-source-foundation.md)
|
- [双端产品形态与开源技术底座](docs/03-dual-portal-and-open-source-foundation.md)
|
||||||
- [开源技术基线与开发节点](docs/04-open-source-baseline-and-development-nodes.md)
|
- [开源技术基线与开发节点](docs/04-open-source-baseline-and-development-nodes.md)
|
||||||
- [信息准备与阶段门禁清单](docs/05-information-readiness-checklist.md)
|
- [信息准备与阶段门禁清单](docs/05-information-readiness-checklist.md)
|
||||||
|
- [D4 密钥与模型目录实施计划](docs/06-d4-integration-plan.md)
|
||||||
|
|
||||||
## 前端原型
|
## 前端原型
|
||||||
|
|
||||||
|
|||||||
@@ -6,6 +6,6 @@ DATABASE_URL=postgresql://moyi:replace-with-a-long-random-password@127.0.0.1:543
|
|||||||
SESSION_TTL_HOURS=168
|
SESSION_TTL_HOURS=168
|
||||||
AUTH_PASSWORD_PEPPER=replace-with-a-long-random-secret
|
AUTH_PASSWORD_PEPPER=replace-with-a-long-random-secret
|
||||||
|
|
||||||
ADMIN_ACCOUNT=admin@moyi.local
|
ADMIN_ACCOUNT=adimin
|
||||||
ADMIN_PASSWORD=replace-with-a-strong-initial-password
|
ADMIN_PASSWORD=replace-with-a-strong-initial-password
|
||||||
ADMIN_DISPLAY_NAME=平台管理员
|
ADMIN_DISPLAY_NAME=平台管理员
|
||||||
@@ -0,0 +1,11 @@
|
|||||||
|
NODE_ENV=development
|
||||||
|
CONTROL_PLANE_HOST=127.0.0.1
|
||||||
|
CONTROL_PLANE_PORT=8787
|
||||||
|
CONTROL_PLANE_CORS_ORIGINS=http://localhost:5173
|
||||||
|
SESSION_TTL_HOURS=168
|
||||||
|
AUTH_PASSWORD_PEPPER=replace-with-a-long-random-secret
|
||||||
|
|
||||||
|
# 内存联调模式:不要设置 DATABASE_URL
|
||||||
|
ADMIN_ACCOUNT=adimin
|
||||||
|
ADMIN_PASSWORD=replace-with-a-strong-initial-password
|
||||||
|
ADMIN_DISPLAY_NAME=平台管理员
|
||||||
+28
-12
@@ -4,33 +4,49 @@ D3 的身份与权限服务,负责邀请码注册、登录会话、用户角
|
|||||||
|
|
||||||
## 本地开发
|
## 本地开发
|
||||||
|
|
||||||
\`\`\`powershell
|
### 内存联调
|
||||||
|
|
||||||
|
如果暂时只验证登录、邀请码和权限,可以使用内存仓库,不需要 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
|
cd control-plane
|
||||||
Copy-Item .env.example .env
|
Copy-Item .env.example .env
|
||||||
pnpm install
|
pnpm install
|
||||||
pnpm migrate
|
pnpm migrate
|
||||||
pnpm seed:admin
|
pnpm seed:admin
|
||||||
pnpm dev
|
pnpm dev
|
||||||
\`\`\`
|
```
|
||||||
|
|
||||||
默认监听 \`http://127.0.0.1:8787\`。没有设置 \`DATABASE_URL\` 时,服务可以使用内存仓库启动,用于接口联调;正式开发和测试应使用 PostgreSQL。
|
默认监听 `http://127.0.0.1:8787`。没有设置 `DATABASE_URL` 时,服务可以使用内存仓库启动,用于接口联调;正式开发和测试应使用 PostgreSQL。
|
||||||
|
|
||||||
## 接口
|
## 接口
|
||||||
|
|
||||||
- \`POST /api/auth/register\`:邀请码注册,账号支持邮箱或手机号。
|
- `POST /api/auth/register`:邀请码注册,账号支持邮箱或手机号。
|
||||||
- \`POST /api/auth/login\`:账号密码登录,返回 HttpOnly 会话 Cookie。
|
- `POST /api/auth/login`:账号密码登录,返回 HttpOnly 会话 Cookie。
|
||||||
- \`GET /api/auth/me\`:读取当前会话用户。
|
- `GET /api/auth/me`:读取当前会话用户。
|
||||||
- \`POST /api/auth/logout\`:撤销当前会话。
|
- `POST /api/auth/logout`:撤销当前会话。
|
||||||
- \`GET /api/admin/users\`:管理员用户列表。
|
- `GET /api/admin/users`:管理员用户列表。
|
||||||
- \`GET|POST /api/admin/invitations\`:管理员查看或生成邀请码。
|
- `GET|POST /api/admin/invitations`:管理员查看或生成邀请码。
|
||||||
- \`POST /api/admin/invitations/:id/revoke\`:停用邀请码。
|
- `POST /api/admin/invitations/:id/revoke`:停用邀请码。
|
||||||
- \`GET /api/admin/audit\`:管理员查看认证审计。
|
- `GET /api/admin/audit`:管理员查看认证审计。
|
||||||
|
|
||||||
第一版暂不实现短信/邮件真实验证码;注册页面保留验证码入口但不以它作为后端注册条件,邀请码、邮箱/手机号和账号密码是当前有效的注册条件。
|
第一版暂不实现短信/邮件真实验证码;注册页面保留验证码入口但不以它作为后端注册条件,邀请码、邮箱/手机号和账号密码是当前有效的注册条件。
|
||||||
|
|
||||||
## 安全约束
|
## 安全约束
|
||||||
|
|
||||||
- 数据库仅保存密码哈希、邀请码摘要和会话摘要,不保存明文密码、明文邀请码或会话 Token。
|
- 数据库仅保存密码哈希、邀请码摘要和会话摘要,不保存明文密码、明文邀请码或会话 Token。
|
||||||
- 生产环境必须设置随机的 \`AUTH_PASSWORD_PEPPER\`、强管理员密码和 HTTPS。
|
- 生产环境必须设置随机的 `AUTH_PASSWORD_PEPPER`、强管理员密码和 HTTPS。
|
||||||
- 管理员接口由 Control Plane 服务端角色校验保护,隐藏前端菜单不构成权限控制。
|
- 管理员接口由 Control Plane 服务端角色校验保护,隐藏前端菜单不构成权限控制。
|
||||||
- 迁移文件只创建认证相关表,额度、模型和 Key 表在后续 D4 节点加入。
|
- 迁移文件只创建认证相关表,额度、模型和 Key 表在后续 D4 节点加入。
|
||||||
@@ -1,7 +1,7 @@
|
|||||||
CREATE TABLE IF NOT EXISTS users (
|
CREATE TABLE IF NOT EXISTS users (
|
||||||
id uuid PRIMARY KEY,
|
id uuid PRIMARY KEY,
|
||||||
account varchar(320) NOT NULL UNIQUE,
|
account varchar(320) NOT NULL UNIQUE,
|
||||||
account_kind varchar(16) NOT NULL CHECK (account_kind IN ('email', 'phone')),
|
account_kind varchar(16) NOT NULL CHECK (account_kind IN ('email', 'phone', 'username')),
|
||||||
password_hash text NOT NULL,
|
password_hash text NOT NULL,
|
||||||
display_name varchar(80) NOT NULL,
|
display_name varchar(80) NOT NULL,
|
||||||
role varchar(16) NOT NULL DEFAULT 'user' CHECK (role IN ('user', 'admin')),
|
role varchar(16) NOT NULL DEFAULT 'user' CHECK (role IN ('user', 'admin')),
|
||||||
|
|||||||
@@ -8,7 +8,7 @@ import {
|
|||||||
|
|
||||||
export type UserRole = 'user' | 'admin'
|
export type UserRole = 'user' | 'admin'
|
||||||
export type UserStatus = 'active' | 'disabled'
|
export type UserStatus = 'active' | 'disabled'
|
||||||
export type AccountKind = 'email' | 'phone'
|
export type AccountKind = 'email' | 'phone' | 'username'
|
||||||
|
|
||||||
export interface UserRecord {
|
export interface UserRecord {
|
||||||
id: string
|
id: string
|
||||||
@@ -368,7 +368,9 @@ export function normalizeAccount(value: string) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
export function accountKind(account: string): AccountKind {
|
export function accountKind(account: string): AccountKind {
|
||||||
return account.includes('@') ? 'email' : 'phone'
|
if (account.includes('@')) return 'email'
|
||||||
|
if (/^\+?[0-9][0-9\s-]{6,19}$/.test(account)) return 'phone'
|
||||||
|
return 'username'
|
||||||
}
|
}
|
||||||
|
|
||||||
export function validateAccount(account: string) {
|
export function validateAccount(account: string) {
|
||||||
|
|||||||
@@ -79,3 +79,13 @@ test('stored invitation values are hashes rather than plaintext', async () => {
|
|||||||
assert.equal(stored?.codeHash, hashSecret(created.code))
|
assert.equal(stored?.codeHash, hashSecret(created.code))
|
||||||
assert.notEqual(stored?.codeHash, created.code)
|
assert.notEqual(stored?.codeHash, created.code)
|
||||||
})
|
})
|
||||||
|
|
||||||
|
test('development administrator can use a username account', async () => {
|
||||||
|
const { auth, repository } = createHarness()
|
||||||
|
await auth.ensureAdmin('adimin', 'test-admin-password', '平台管理员')
|
||||||
|
const login = await auth.login({ account: 'adimin', password: 'test-admin-password' }, {})
|
||||||
|
const stored = await repository.findUserByAccount('adimin')
|
||||||
|
|
||||||
|
assert.equal(login.user.role, 'admin')
|
||||||
|
assert.equal(stored?.accountKind, 'username')
|
||||||
|
})
|
||||||
@@ -140,4 +140,4 @@ POST /v1/tasks
|
|||||||
|
|
||||||
## 六、当前结论
|
## 六、当前结论
|
||||||
|
|
||||||
当前 D3 已完成认证与权限基线。D3 不要求短信/邮件服务或生产密钥;本地可用内存仓库联调,正式开发使用独立 PostgreSQL。下一节点进入 D4,补充 MOYI Key、统一模型目录与 Otari 映射。
|
当前 D3 已完成认证与权限基线。D4 输入已确认:先使用 Mock 建立 Key/模型目录闭环,真实接入方向包含国内文本/多模态模型和 VAST 相关 3D 模型,测试环境使用现有服务器,首轮规模按 4—5 人、3—4 个项目估算。下一节点进入 D4,补充 MOYI Key、统一模型目录与 Otari 映射。详见 [D4 密钥与模型目录实施计划](06-d4-integration-plan.md)。
|
||||||
@@ -145,17 +145,30 @@ UAT 通过的标准不是“所有模型都接入”,而是首批约定模型
|
|||||||
- 知识库、RAG、Agent、工作流和模型评测平台。
|
- 知识库、RAG、Agent、工作流和模型评测平台。
|
||||||
- 正式公网域名、品牌营销和大规模容量承诺。
|
- 正式公网域名、品牌营销和大规模容量承诺。
|
||||||
|
|
||||||
## 七、你现在只需要准备的内容
|
## 七、本轮已确认的 D4 输入
|
||||||
|
|
||||||
为了继续 D4,你可以按下面 8 项回复,暂时不知道的写“待定”即可:
|
| 项目 | 已确认内容 | 处理方式 |
|
||||||
|
|---|---|---|
|
||||||
|
| 开发管理员账号 | `adimin` | 已写入配置模板;密码只由本地 `.env` 设置,不进入 Git |
|
||||||
|
| 首个真实接入方向 | 先评估智谱、阿里、Kimi 等国内文本/多模态模型;VAST 合作方向重点评估 3D | 先做可替换 Provider Adapter,不绑定单一厂商 |
|
||||||
|
| VAST/3D 接入方式 | 先采用开发者 API Key + HTTP API;后续可增加 SDK 适配 | Key 只存本地密钥环境,用户侧只使用 MOYI Key |
|
||||||
|
| Mock 策略 | 接受先用 Mock 完成 Key/模型目录,再接真实供应商 | D4 先保证目录、权限和映射闭环 |
|
||||||
|
| 首批模型类型 | 文本/编码/多模态模型,或生成式 3D | 建议同步模型 + 异步 3D 各选一个验收 |
|
||||||
|
| 已有接口资源 | 已有 3D API 接入方式,后续可能使用 SDK | 真实接口资料在联调前补齐 |
|
||||||
|
| 测试环境 | 使用现有服务器 | 先确认 Docker、端口、磁盘、数据库和备份条件 |
|
||||||
|
| 首轮规模 | 4—5 人,3—4 个项目 | 作为测试容量假设,不作为生产承诺 |
|
||||||
|
| 业务规则 | 邀请码、管理员额度、暂不支付、公开注册后置;支持用量/金额分配 | D4/D5 先做额度分配和用量记录,支付后置 |
|
||||||
|
|
||||||
1. 第一个开发环境管理员登录账号。
|
### 凭证安全说明
|
||||||
2. 首个真实验收方式:HTTP、SDK 或某个 AI 应用接入。
|
|
||||||
3. 是否先用 Mock 完成 Key/模型目录,再接真实供应商。
|
|
||||||
4. 首个准备接入的模型类型,建议先选一个同步模型和一个异步/3D 模型。
|
|
||||||
5. 是否已有可用于测试的供应商或 AI SoulMate 接口。
|
|
||||||
6. 测试环境准备在本机、现有服务器,还是另建测试服务器。
|
|
||||||
7. 第一轮内部测试预计几个人、几个项目。
|
|
||||||
8. 是否接受当前默认规则:邀请码、管理员额度、暂不支付、公开注册后置。
|
|
||||||
|
|
||||||
除第 1—3 项外,其余都可以先填“待定”,我们继续用 Mock 和可替换配置推进。
|
本轮提供的管理员密码不会写入文档、代码或 Git。请在本地 `control-plane/.env` 中设置 `ADMIN_PASSWORD`;供应商 API Key、数据库密码和 SDK 凭证同样只通过本地环境变量或服务器密钥管理注入。
|
||||||
|
|
||||||
|
## 八、当前待补资料
|
||||||
|
|
||||||
|
为了进入真实供应商联调,目前只需要补充下面 3 类资料,暂时不知道的写“待定”即可:
|
||||||
|
|
||||||
|
1. 当前需要补充的是首个供应商/模型的 API 文档、测试 Key 和能力限制。
|
||||||
|
2. 如果优先接 3D,需要补充 VAST/AI SoulMate 的任务接口、回调/轮询、结果文件和计费单位。
|
||||||
|
3. 如果优先接文本/多模态,需要从智谱、阿里、Kimi 等候选中选出第一个可测试供应商。
|
||||||
|
|
||||||
|
其余本轮信息已经足够启动 D4;未确定的供应商和模型可以继续用 Mock 和可替换配置推进。
|
||||||
@@ -0,0 +1,80 @@
|
|||||||
|
# D4 密钥与模型目录实施计划
|
||||||
|
|
||||||
|
## 一、节点目标
|
||||||
|
|
||||||
|
D4 不先追求接入很多供应商,而是建立一条可替换的“MOYI Key → 统一模型目录 → Provider Adapter → Otari/异步任务适配器”链路。
|
||||||
|
|
||||||
|
首轮采用 Mock 完成控制面闭环,再选择一个文本/多模态模型和一个异步 3D 模型做真实联调。
|
||||||
|
|
||||||
|
开发管理员账号使用用户名 `adimin`;普通用户注册仍使用邀请码 + 邮箱或手机号。管理员密码只在本地 `control-plane/.env` 中配置。
|
||||||
|
|
||||||
|
## 二、首批供应商分层
|
||||||
|
|
||||||
|
### A. 文本/编码/多模态候选
|
||||||
|
|
||||||
|
智谱、阿里、Kimi 等国内模型供应商列为候选,不在代码中写死。真正进入联调前,需要从其中选择至少一个能够提供测试 Key、API 文档和限流说明的供应商。
|
||||||
|
|
||||||
|
### B. 3D 候选
|
||||||
|
|
||||||
|
VAST 合作方向作为 3D 优先候选;现有信息表明可以通过开发者 API Key/API 文档方式接入,后续再评估 SDK 接入。Tripo 官方 Key 页面说明 API Key 创建后仅展示一次,并建议使用环境变量保存,不要提交到版本控制:[Tripo API 密钥](https://developers.tripo3d.com/zh/keys)。
|
||||||
|
|
||||||
|
适配层必须把用户侧协议与上游实现隔离:
|
||||||
|
|
||||||
|
```text
|
||||||
|
用户应用
|
||||||
|
→ MOYI API Key
|
||||||
|
→ MOYI 统一模型 ID
|
||||||
|
→ VAST/3D Provider Adapter
|
||||||
|
→ 上游 HTTP API 或 SDK
|
||||||
|
```
|
||||||
|
|
||||||
|
SDK 不直接暴露给 MOYI 用户。后续如果上游从 HTTP API 切换为 SDK,只替换 Provider Adapter,不修改用户的 Base URL、MOYI Key 和统一模型名。
|
||||||
|
|
||||||
|
## 三、D4 先做 Mock 的内容
|
||||||
|
|
||||||
|
- MOYI Key 创建、只显示一次、停用和权限范围。
|
||||||
|
- 模型目录:文本、代码、多模态、3D 类型和模型能力 Schema。
|
||||||
|
- 用户/项目/Key 到模型的访问权限。
|
||||||
|
- 供应商模型 ID 到统一模型 ID 的映射。
|
||||||
|
- 同步模型和异步模型的调用模式标记。
|
||||||
|
- 模型上下线和管理端基础页面。
|
||||||
|
- Otari 模型列表适配接口的 Mock 响应。
|
||||||
|
|
||||||
|
## 四、真实联调前的最小资料
|
||||||
|
|
||||||
|
### 文本/多模态模型
|
||||||
|
|
||||||
|
- 供应商名称和正式 API 文档。
|
||||||
|
- 测试 Base URL、API Key 和模型 ID。
|
||||||
|
- 请求/响应样例,是否支持流式。
|
||||||
|
- 上下文、输入文件、输出长度、超时、速率和并发限制。
|
||||||
|
- 供应商错误码、余额/额度查询方式和数据使用条款。
|
||||||
|
|
||||||
|
### 3D 模型
|
||||||
|
|
||||||
|
- VAST 或 AI SoulMate 的 API/SDK 文档。
|
||||||
|
- 测试 API Key 和测试环境。
|
||||||
|
- 文生 3D、图生 3D 的任务参数。
|
||||||
|
- 任务创建、进度查询、Webhook/轮询和取消方式。
|
||||||
|
- 输出文件格式、文件下载授权、保存周期和大小限制。
|
||||||
|
- 计费单位、失败/超时/取消规则和重试建议。
|
||||||
|
|
||||||
|
## 五、首轮验收建议
|
||||||
|
|
||||||
|
按 4—5 人、3—4 个项目的内部测试规模,先验收:
|
||||||
|
|
||||||
|
1. 管理员创建 MOYI Key 并限制模型范围。
|
||||||
|
2. 普通用户使用 MOYI Key 查看可用模型。
|
||||||
|
3. Mock 文本模型完成一次同步或流式调用。
|
||||||
|
4. Mock 3D 模型完成任务创建、排队、进度和结果状态闭环。
|
||||||
|
5. 管理员分配一笔额度或金额预算,并能查看用量。
|
||||||
|
6. 停用 Key 后调用被拒绝,且产生审计记录。
|
||||||
|
7. 将 Mock Provider 替换为一个真实供应商时,用户侧配置不变。
|
||||||
|
|
||||||
|
## 六、暂不进入 D4
|
||||||
|
|
||||||
|
- 真实支付、充值、退款和发票。
|
||||||
|
- 多供应商智能路由和复杂降级。
|
||||||
|
- 企业认证、团队审批和 BYOK。
|
||||||
|
- 正式公网开放、生产 SLA 和大规模并发承诺。
|
||||||
|
- 自托管模型和 GPU 调度。
|
||||||
@@ -3,7 +3,7 @@ export type AuthRole = 'user' | 'admin'
|
|||||||
export interface AuthUser {
|
export interface AuthUser {
|
||||||
id: string
|
id: string
|
||||||
account: string
|
account: string
|
||||||
accountKind: 'email' | 'phone'
|
accountKind: 'email' | 'phone' | 'username'
|
||||||
displayName: string
|
displayName: string
|
||||||
role: AuthRole
|
role: AuthRole
|
||||||
status: 'active' | 'disabled'
|
status: 'active' | 'disabled'
|
||||||
|
|||||||
Reference in new issue
Block a user