diff --git a/README.md b/README.md index 2fdcb2a..5b18d2e 100644 --- a/README.md +++ b/README.md @@ -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) ## 前端原型 diff --git a/control-plane/.env.example b/control-plane/.env.example index 7991847..f50e675 100644 --- a/control-plane/.env.example +++ b/control-plane/.env.example @@ -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=平台管理员 diff --git a/control-plane/.env.memory.example b/control-plane/.env.memory.example new file mode 100644 index 0000000..acd97ad --- /dev/null +++ b/control-plane/.env.memory.example @@ -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=平台管理员 diff --git a/control-plane/README.md b/control-plane/README.md index c5667d9..d1fe858 100644 --- a/control-plane/README.md +++ b/control-plane/README.md @@ -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 节点加入。 diff --git a/control-plane/migrations/001_auth.sql b/control-plane/migrations/001_auth.sql index a70ff79..95e7e74 100644 --- a/control-plane/migrations/001_auth.sql +++ b/control-plane/migrations/001_auth.sql @@ -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')), diff --git a/control-plane/src/auth.ts b/control-plane/src/auth.ts index 3f6262c..0f89d7c 100644 --- a/control-plane/src/auth.ts +++ b/control-plane/src/auth.ts @@ -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) { diff --git a/control-plane/tests/auth.test.ts b/control-plane/tests/auth.test.ts index 94b8d11..ec7140f 100644 --- a/control-plane/tests/auth.test.ts +++ b/control-plane/tests/auth.test.ts @@ -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') +}) diff --git a/docs/04-open-source-baseline-and-development-nodes.md b/docs/04-open-source-baseline-and-development-nodes.md index cf12fcf..69428eb 100644 --- a/docs/04-open-source-baseline-and-development-nodes.md +++ b/docs/04-open-source-baseline-and-development-nodes.md @@ -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)。 diff --git a/docs/05-information-readiness-checklist.md b/docs/05-information-readiness-checklist.md index 3a98a76..a4c4ef8 100644 --- a/docs/05-information-readiness-checklist.md +++ b/docs/05-information-readiness-checklist.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 和可替换配置推进。 diff --git a/docs/06-d4-integration-plan.md b/docs/06-d4-integration-plan.md new file mode 100644 index 0000000..6a18127 --- /dev/null +++ b/docs/06-d4-integration-plan.md @@ -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 调度。 diff --git a/prototype/src/services/auth.ts b/prototype/src/services/auth.ts index 744b079..6a47379 100644 --- a/prototype/src/services/auth.ts +++ b/prototype/src/services/auth.ts @@ -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'