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/04-open-source-baseline-and-development-nodes.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
|
||||
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_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
|
||||
Copy-Item .env.example .env
|
||||
pnpm install
|
||||
pnpm migrate
|
||||
pnpm seed:admin
|
||||
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/login\`:账号密码登录,返回 HttpOnly 会话 Cookie。
|
||||
- \`GET /api/auth/me\`:读取当前会话用户。
|
||||
- \`POST /api/auth/logout\`:撤销当前会话。
|
||||
- \`GET /api/admin/users\`:管理员用户列表。
|
||||
- \`GET|POST /api/admin/invitations\`:管理员查看或生成邀请码。
|
||||
- \`POST /api/admin/invitations/:id/revoke\`:停用邀请码。
|
||||
- \`GET /api/admin/audit\`:管理员查看认证审计。
|
||||
- `POST /api/auth/register`:邀请码注册,账号支持邮箱或手机号。
|
||||
- `POST /api/auth/login`:账号密码登录,返回 HttpOnly 会话 Cookie。
|
||||
- `GET /api/auth/me`:读取当前会话用户。
|
||||
- `POST /api/auth/logout`:撤销当前会话。
|
||||
- `GET /api/admin/users`:管理员用户列表。
|
||||
- `GET|POST /api/admin/invitations`:管理员查看或生成邀请码。
|
||||
- `POST /api/admin/invitations/:id/revoke`:停用邀请码。
|
||||
- `GET /api/admin/audit`:管理员查看认证审计。
|
||||
|
||||
第一版暂不实现短信/邮件真实验证码;注册页面保留验证码入口但不以它作为后端注册条件,邀请码、邮箱/手机号和账号密码是当前有效的注册条件。
|
||||
|
||||
## 安全约束
|
||||
|
||||
- 数据库仅保存密码哈希、邀请码摘要和会话摘要,不保存明文密码、明文邀请码或会话 Token。
|
||||
- 生产环境必须设置随机的 \`AUTH_PASSWORD_PEPPER\`、强管理员密码和 HTTPS。
|
||||
- 生产环境必须设置随机的 `AUTH_PASSWORD_PEPPER`、强管理员密码和 HTTPS。
|
||||
- 管理员接口由 Control Plane 服务端角色校验保护,隐藏前端菜单不构成权限控制。
|
||||
- 迁移文件只创建认证相关表,额度、模型和 Key 表在后续 D4 节点加入。
|
||||
@@ -1,7 +1,7 @@
|
||||
CREATE TABLE IF NOT EXISTS users (
|
||||
id uuid PRIMARY KEY,
|
||||
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,
|
||||
display_name varchar(80) NOT NULL,
|
||||
role varchar(16) NOT NULL DEFAULT 'user' CHECK (role IN ('user', 'admin')),
|
||||
|
||||
@@ -8,7 +8,7 @@ import {
|
||||
|
||||
export type UserRole = 'user' | 'admin'
|
||||
export type UserStatus = 'active' | 'disabled'
|
||||
export type AccountKind = 'email' | 'phone'
|
||||
export type AccountKind = 'email' | 'phone' | 'username'
|
||||
|
||||
export interface UserRecord {
|
||||
id: string
|
||||
@@ -368,7 +368,9 @@ export function normalizeAccount(value: string) {
|
||||
}
|
||||
|
||||
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) {
|
||||
|
||||
@@ -79,3 +79,13 @@ test('stored invitation values are hashes rather than plaintext', async () => {
|
||||
assert.equal(stored?.codeHash, hashSecret(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、工作流和模型评测平台。
|
||||
- 正式公网域名、品牌营销和大规模容量承诺。
|
||||
|
||||
## 七、你现在只需要准备的内容
|
||||
## 七、本轮已确认的 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 {
|
||||
id: string
|
||||
account: string
|
||||
accountKind: 'email' | 'phone'
|
||||
accountKind: 'email' | 'phone' | 'username'
|
||||
displayName: string
|
||||
role: AuthRole
|
||||
status: 'active' | 'disabled'
|
||||
|
||||
Reference in new issue
Block a user