wehub-resource-sync
523 lines
31 KiB
Markdown
523 lines
31 KiB
Markdown
# 设置页 → 远程连接 — WebUI 服务 (F-WEBUI)
|
||
|
||
> 本文档覆盖「设置 → 远程连接」页面 **WebUI Tab** 的全部功能，包括服务启停、远程访问控制、认证管理、QR 码登录、配置持久化、页面结构、状态同步、扩展系统 WebUI 贡献。
|
||
> 基于静态代码分析和动态 UI 验证综合整理。
|
||
>
|
||
> Channels Tab 相关内容见 [channels.md](../channels/channels.md)。
|
||
|
||
---
|
||
|
||
## (F-WEBUI-01) WebUI 服务启停 [已实现]
|
||
|
||
**用户故事**：作为桌面端用户，我希望通过一个开关快速启用或禁用 WebUI 服务，以便在需要时通过浏览器远程访问 AionUi。
|
||
|
||
**前置条件**：运行在 Electron 桌面端（`isElectronDesktop() === true`）
|
||
|
||
**正常流程**（用户视角）：
|
||
|
||
1. 用户进入「设置 → 远程连接」页面，默认选中 "WebUI" Tab
|
||
2. 页面显示 WebUI 服务卡片，卡片内第一行为"启用 WebUI"，右侧有 Switch 开关
|
||
3. 用户打开开关（OFF → ON）
|
||
4. 开关显示 loading 旋转，旁边出现橙色"启动中..."文字
|
||
5. 启动成功后：开关变为蓝色 checked 状态，旁边显示绿色"✓ 运行中"，toast 提示"WebUI 启动成功"
|
||
6. 下方出现"访问地址"行（见 F-WEBUI-03）
|
||
7. 如为首次启动且有初始密码，密码行显示明文（见 F-WEBUI-06）
|
||
8. 用户关闭开关（ON → OFF）
|
||
9. 访问地址行和 QR 码区域消失，toast 提示"WebUI 已停止"
|
||
|
||
**异常情况**：
|
||
|
||
- 启动 IPC 调用失败（网络错误/主进程异常）：Switch 回滚到关闭状态，toast 提示"操作失败"（`settings.webui.operationFailed`）
|
||
- 启动 IPC 超时（3 秒未返回）：UI 乐观地认为服务已启动，显示为运行中，**同时持久化 enabled=true**（已知局限：可能导致 UI 与实际状态不一致，且下次启动时循环恢复失败服务）
|
||
- 端口被占用：服务器自动尝试下一个端口（`port + 1`），递增上限固定为 `DEFAULT_PORT + 10`（默认端口：生产 25808，开发 25809，上限 25818/25819）；当用户通过 CLI/环境变量指定端口超出此范围时，不触发递增，直接报错
|
||
- 停止操作为 fire-and-forget 模式：UI 和 ConfigStorage 先行更新为停止状态 → toast 提示"WebUI 已停止"（`settings.webui.stopSuccess`）→ 然后才异步调用 `webui.stop.invoke()`。**Toast 出现时服务器可能仍在运行**
|
||
- 服务器已在运行时再次收到启动请求：先停止旧实例（关闭所有 WebSocket 连接、释放端口），再启动新实例
|
||
|
||
**验收标准**：
|
||
|
||
- [ ] Switch 开关可切换 WebUI 服务启停
|
||
- [ ] 启动过程显示 loading 状态 + "启动中…" 文字（以 i18n `settings.webui.starting` 实际值为准）
|
||
- [ ] 启动成功后显示绿色"✓ 运行中"标记
|
||
- [ ] 启动/停止成功各有对应 toast 提示（`settings.webui.startSuccess` / `settings.webui.stopSuccess`）
|
||
- [ ] 启动失败时 Switch 回滚到关闭状态 + toast 提示（`settings.webui.operationFailed`）
|
||
- [ ] 端口被占用时自动递增，上限固定为 `DEFAULT_PORT + 10`
|
||
|
||
---
|
||
|
||
## (F-WEBUI-02) 启动恢复与配置持久化 [已实现]
|
||
|
||
**用户故事**：作为用户，我希望启用 WebUI 后下次打开应用时能自动恢复服务，无需每次手动开启。
|
||
|
||
**正常流程**（用户视角）：
|
||
|
||
1. 用户启用 WebUI 服务（F-WEBUI-01）
|
||
2. 系统在启动成功后将 `webui.desktop.enabled = true` 写入 ConfigStorage
|
||
3. 用户关闭并重新打开应用
|
||
4. 应用在后台自动启动 WebUI 服务（非阻塞，不影响应用启动速度）
|
||
5. 进入设置页面时显示为已启动状态
|
||
|
||
**配置来源**：
|
||
|
||
端口解析（覆盖式优先级）：CLI 参数（`--port` / `--webui-port`）> 环境变量（`AIONUI_PORT` / `PORT`）> 配置文件（`userData/webui.config.json`）> 默认值（25808/25809）
|
||
|
||
远程访问（多源 OR 聚合 — 只要任一来源为 true 即启用）：`isRemoteMode` || 环境变量（`AIONUI_ALLOW_REMOTE` / `AIONUI_REMOTE` / `AIONUI_HOST=0.0.0.0`）|| 配置文件（`allowRemote: true`）|| ConfigStorage 偏好
|
||
|
||
**两种启动路径的配置差异**：
|
||
|
||
| 启动路径 | 端口解析 | 远程访问解析 |
|
||
| -------------- | ------------------------------------------------------- | ------------------------------------------ |
|
||
| CLI/服务器模式 | 经过 `resolveWebUIPort`（CLI > env > config > default） | 经过 `resolveRemoteAccess`（多源 OR 聚合） |
|
||
| 桌面自动恢复 | 仅从 ConfigStorage 读取（不经过 resolve） | 仅从 ConfigStorage 读取（不经过 resolve） |
|
||
|
||
**异常情况**：
|
||
|
||
- 自动恢复失败（端口全部占用/其他错误）：仅记录日志，不影响应用正常启动
|
||
- 配置文件 JSON 解析失败：使用空配置 `{}`，不报错
|
||
- ConfigStorage 读取失败：默认为未启用
|
||
|
||
**验收标准**：
|
||
|
||
- [ ] 启用 WebUI 后，重启应用时自动恢复 WebUI 服务 [验证策略：集成测试]
|
||
- [ ] 禁用 WebUI 后，重启应用不会自动启动服务 [验证策略：集成测试]
|
||
- [ ] 启动失败不影响应用正常使用 [验证策略：集成测试]
|
||
- [ ] 持久化在启动成功后才写入（失败不写入，避免循环恢复失败）[验证策略：evaluate_script 读 ConfigStorage]
|
||
|
||
---
|
||
|
||
## (F-WEBUI-03) 访问地址展示 [已实现]
|
||
|
||
**用户故事**：作为用户，我希望 WebUI 启动后能看到访问地址，方便在浏览器中打开或分享给他人。
|
||
|
||
**前置条件**：WebUI 服务正在运行（`status.running === true`）
|
||
|
||
**正常流程**（用户视角）：
|
||
|
||
1. WebUI 启动后，服务卡片内出现"访问地址"行
|
||
2. 根据"允许远程访问"开关状态显示不同地址：
|
||
- 远程访问关闭：显示 `http://localhost:{port}`
|
||
- 远程访问开启：显示 `http://{局域网IP}:{port}`（如 `http://192.168.3.15:25809`）
|
||
3. 地址以蓝色链接样式显示，点击在系统默认浏览器中打开
|
||
4. 地址旁有复制按钮，点击复制到剪贴板，toast 提示"复制成功"
|
||
|
||
**异常情况**：
|
||
|
||
- 点击链接打开浏览器失败：仅记录日志，无用户可见提示
|
||
- 局域网 IP 获取失败（无网卡/无 IPv4 地址）：退回显示 `localhost`
|
||
|
||
**验收标准**：
|
||
|
||
- [ ] 仅在 WebUI 运行时显示访问地址行
|
||
- [ ] 远程访问开启时显示局域网 IP 地址
|
||
- [ ] 远程访问关闭时显示 localhost
|
||
- [ ] 点击地址在系统浏览器中打开
|
||
- [ ] 复制按钮可复制地址 + toast 提示
|
||
|
||
---
|
||
|
||
## (F-WEBUI-04) 远程访问控制 [已实现]
|
||
|
||
**用户故事**：作为用户，我希望控制是否允许局域网内其他设备访问 WebUI，以便用手机或其他电脑访问 AionUi。
|
||
|
||
**正常流程**（用户视角）：
|
||
|
||
1. 服务卡片内"允许远程访问"行，右侧有 Switch 开关
|
||
2. 开关下方显示说明文字（"使用远程软件/服务器可安全远程访问"）和蓝色"查看方式"链接
|
||
3. 用户打开开关（OFF → ON）
|
||
4. **如果 WebUI 正在运行**：系统执行停止→重启流程（因为需要切换监听地址从 `127.0.0.1` 到 `0.0.0.0`），显示 loading，toast 提示"WebUI 已重启"
|
||
5. 访问地址从 `localhost` 变为局域网 IP，QR 码区域出现（见 F-WEBUI-08）
|
||
6. **如果 WebUI 未运行**：仅保存偏好，不触发重启
|
||
|
||
**异常情况**：
|
||
|
||
- 重启失败（停止后无法重新启动）：系统二次确认服务状态（调用 getStatus），如确认未运行则回滚开关 + toast（`settings.webui.operationFailed`）
|
||
- 重启超时：最大等待 6s（停止 1.5s + 启动 3s + 状态确认 1.5s），超时后同上处理
|
||
- 持久化失败：回滚开关状态 + toast（`settings.webui.operationFailed`）
|
||
- "查看方式"链接：点击打开 GitHub Wiki 远程访问指南页面（`shell.openExternal`）
|
||
|
||
**验收标准**：
|
||
|
||
- [ ] 切换开关可启用/禁用远程访问
|
||
- [ ] WebUI 运行中切换时，执行自动重启流程
|
||
- [ ] 重启成功有 toast 提示（`settings.webui.restartSuccess`）
|
||
- [ ] 重启失败回滚开关状态 + toast 提示（`settings.webui.operationFailed`）
|
||
- [ ] 设置在 WebUI 未运行时也可修改并持久化，下次启动生效
|
||
- [ ] "查看方式"链接可打开指南页面
|
||
|
||
---
|
||
|
||
## (F-WEBUI-05) 用户名管理 [已实现]
|
||
|
||
**用户故事**：作为用户，我希望能查看和修改 WebUI 的登录用户名，以便个性化我的登录凭据。
|
||
|
||
**正常流程**（用户视角）：
|
||
|
||
1. 登录信息卡片（始终可见，无论 WebUI 是否启用）显示"用户名:"行
|
||
2. 当前用户名明文显示（默认 "admin"）
|
||
3. 旁有复制按钮（复制用户名）和编辑按钮（铅笔图标）
|
||
4. 点击编辑按钮弹出"设置新用户名"弹窗
|
||
5. 输入框预填当前用户名
|
||
6. 用户输入新用户名，点击"确定"
|
||
7. 提交成功：toast"用户名修改成功"，弹窗关闭，显示更新为新用户名
|
||
|
||
**表单校验规则**：
|
||
|
||
| 规则 | 前端校验 | 后端校验 | 错误提示 |
|
||
| --------------------------- | -------- | -------- | -------------------------------------- |
|
||
| 必填 | 是 | - | 前端 i18n 提示 |
|
||
| 最少 3 字符 | 是 | 是 | 前端 i18n / 后端英文原文（未 i18n 化） |
|
||
| 最多 32 字符 | 是 | 是 | 前端 i18n / 后端英文原文（未 i18n 化） |
|
||
| 仅允许 `[a-zA-Z0-9_-]` | 是 | 是 | 前端 i18n / 后端英文原文（未 i18n 化） |
|
||
| 不能以 `_` 或 `-` 开头/结尾 | 是 | 是 | 前端 i18n / 后端英文原文（未 i18n 化） |
|
||
| 用户名已存在（不同用户） | - | 是 | "Username already exists"（英文原文） |
|
||
|
||
**异常情况**：
|
||
|
||
- 前端校验失败：表单内行内提示，不提交
|
||
- 后端校验失败：toast 显示后端返回的**英文原文**错误信息（注：与密码修改不同，用户名后端错误码未做前端 i18n 翻译）
|
||
- IPC 调用异常：toast（`settings.webui.usernameChangeFailed`）
|
||
- 用户名与当前相同：后端直接返回成功，不执行更新
|
||
- 修改成功后：所有已存在的登录 token 失效（通过 JWT secret 轮转实现，为被动失效 — 已建立的 WebSocket 连接不会立即断开，需等到下次请求或心跳时才被拒绝）
|
||
|
||
**验收标准**：
|
||
|
||
- [ ] 用户名默认显示"admin"
|
||
- [ ] 复制按钮可复制用户名
|
||
- [ ] 编辑按钮打开"设置新用户名"弹窗，预填当前值
|
||
- [ ] 前端校验规则全部生效
|
||
- [ ] 提交成功后 toast 提示 + 弹窗关闭 + UI 更新
|
||
- [ ] 提交失败有明确错误提示
|
||
- [ ] 修改后已有 WebUI 登录会话被踢出
|
||
|
||
---
|
||
|
||
## (F-WEBUI-06) 密码显示与初始密码 [已实现]
|
||
|
||
**用户故事**：作为用户，我希望在首次启动 WebUI 时能看到系统生成的初始密码，之后密码显示为遮罩状态，以保护安全。
|
||
|
||
**正常流程**（用户视角）：
|
||
|
||
1. 登录信息卡片中"初始密码:"行（始终可见）
|
||
2. **首次启动（有初始密码）**：显示明文密码（12 至 16 字符，含两端；含小写 + 大写字母 + 数字 + 特殊字符 `!@#$%^&*`）
|
||
3. **非首次启动（无初始密码/已修改密码）**：显示"**\*\***"（密码遮罩）
|
||
4. 旁有编辑按钮（铅笔图标），hover 时 tooltip 提示"忘记密码？点击设置新密码（不需要当前密码）"
|
||
5. **注意：密码行仅有编辑按钮，无复制功能**（与用户名行不同，用户名行有复制 + 编辑两个按钮）
|
||
|
||
**异常情况**：
|
||
|
||
- 服务运行中但无初始密码且无缓存密码：显示"**\*\***"，用户需通过编辑按钮设置新密码
|
||
- 密码可见状态（`canShowPlainPassword`）是组件内存状态，页面刷新后重置为遮罩
|
||
|
||
**验收标准**：
|
||
|
||
- [ ] 首次启动时密码明文可见
|
||
- [ ] 用户修改密码后切换为遮罩显示
|
||
- [ ] 编辑按钮 tooltip 提示修改密码不需要当前密码
|
||
- [ ] 页面刷新后密码回到遮罩状态
|
||
- [ ] 密码行仅有编辑按钮，无复制按钮
|
||
|
||
---
|
||
|
||
## (F-WEBUI-07) 密码修改 [已实现]
|
||
|
||
**用户故事**：作为用户，我希望能设置自定义密码替换系统生成的初始密码，或在忘记密码时直接设置新密码。
|
||
|
||
**正常流程**（用户视角）：
|
||
|
||
1. 点击密码行的编辑按钮
|
||
2. 弹出"设置新密码"弹窗
|
||
3. 输入新密码（Password 输入框，带可见性切换图标，placeholder"请输入新密码（至少8位）"）
|
||
4. 输入确认密码（placeholder"请再次输入新密码"）
|
||
5. 点击"确定"
|
||
6. 提交成功：toast"密码修改成功"，弹窗关闭，密码行切换为"**\*\***"
|
||
|
||
**表单校验规则**：
|
||
|
||
| 规则 | 校验端 | 错误提示 |
|
||
| ------------- | --------- | -------------------------------- |
|
||
| 新密码必填 | 前端 | "请输入新密码" |
|
||
| 最少 8 字符 | 前端+后端 | i18n 提示 / `PASSWORD_TOO_SHORT` |
|
||
| 最多 128 字符 | 后端 | `PASSWORD_TOO_LONG` |
|
||
| 弱密码黑名单 | 后端 | `PASSWORD_TOO_COMMON` |
|
||
| 确认密码必填 | 前端 | "请再次输入新密码" |
|
||
| 两次密码一致 | 前端 | "两次密码不一致" |
|
||
|
||
**弱密码黑名单**：`password`, `12345678`, `123456789`, `qwertyui`, `abcdefgh`
|
||
|
||
**异常情况**：
|
||
|
||
- 前端校验失败：表单内行内提示，不提交
|
||
- 后端返回多个错误码（`'; '` 分隔）：前端翻译后合并显示（如 `PASSWORD_TOO_SHORT` → i18n 短密码提示）
|
||
- 后端返回未知错误码：显示原始错误信息，或兜底"密码修改失败"
|
||
- IPC 调用异常：toast"密码修改失败"
|
||
|
||
**技术说明**：
|
||
|
||
- **不需要当前密码验证**：changePassword API 直接设置新密码（安全性依赖 Electron 本地环境）
|
||
- **密码修改后全部 token 失效**：通过 JWT secret 轮转（`invalidateAllTokens` 生成新 secret）实现。这是**被动失效**机制 — 旧 token 不会被主动推送下线，而是在下次请求时验证失败被拒绝。已建立的 WebSocket 连接不会立即断开，需等到心跳或重连时才会被拒绝
|
||
- **后端清除初始密码**：`clearInitialAdminPassword()` 清除内存中的初始密码，后续 getStatus 不再返回 initialPassword
|
||
|
||
**验收标准**：
|
||
|
||
- [ ] 点击编辑按钮打开"设置新密码"弹窗
|
||
- [ ] 不需要输入当前密码
|
||
- [ ] 新密码和确认密码均有 Password 可见性切换
|
||
- [ ] 前端校验（必填、最短 8 位、两次一致）生效
|
||
- [ ] 后端校验（最长 128 位、弱密码黑名单）生效
|
||
- [ ] 提交成功后 toast 提示（`settings.webui.passwordChanged`）+ 弹窗关闭 + 密码切换为遮罩
|
||
- [ ] 修改后已有 WebUI 登录 token 被动失效
|
||
|
||
---
|
||
|
||
## (F-WEBUI-08) QR 码登录 [已实现]
|
||
|
||
**用户故事**：作为用户，我希望在允许远程访问时能通过手机扫描二维码快速登录 WebUI，无需手动输入地址和密码。
|
||
|
||
**前置条件**：WebUI 服务运行中（`status.running === true`）且允许远程访问（`status.allowRemote === true`）
|
||
|
||
**正常流程**（用户视角）：
|
||
|
||
1. 登录信息卡片下方出现分隔线 + "二维码登录"区块
|
||
2. 说明文字："使用手机扫描二维码，即可在手机浏览器中自动登录"
|
||
3. 系统自动生成二维码（140x140 SVG，纠错级别 M）
|
||
4. 二维码下方显示有效期（本地化时间格式，24h 或 12h 取决于系统 locale；使用 `toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' })`）
|
||
5. 旁有复制按钮（复制二维码对应的 URL）和刷新按钮
|
||
6. 用户用手机扫描二维码，自动在手机浏览器打开并登录 WebUI
|
||
7. 二维码在过期前自动刷新（token 5 分钟过期，定时器 4 分钟触发刷新）
|
||
|
||
**QR 码 URL 格式**：`http://{lanIP}:{port}/qr-login?token={64位hex}`
|
||
|
||
**Token 安全机制**：
|
||
|
||
| 安全特性 | 说明 |
|
||
| ---------- | ------------------------------------------- |
|
||
| 随机生成 | `crypto.randomBytes(32)` → 64 位 hex |
|
||
| 有效期 | 5 分钟（`QR_TOKEN_EXPIRY = 5 * 60 * 1000`） |
|
||
| 一次性使用 | 验证后标记 `used: true` 并立即从内存中删除 |
|
||
| IP 限制 | 非远程模式下仅允许本地/局域网 IP 使用 |
|
||
| 内存存储 | 存储在进程内 `Map`，进程重启后全部失效 |
|
||
|
||
**自动生成/清除逻辑**：
|
||
|
||
- 服务运行 + 允许远程 + 无 QR URL → 自动生成
|
||
- 服务停止或关闭远程访问 → 自动清除二维码 + 取消定时器
|
||
|
||
**异常情况**：
|
||
|
||
- 生成失败（WebUI 未运行/IPC 异常）：QR 区域显示占位文案（`settings.webui.qrGenerateFailed`）+ toast（同一 i18n key）。注意：初始状态（尚未生成）和生成失败共用同一占位文案，组件无法区分两种状态
|
||
- Token 已过期：扫码后提示"QR token has expired"
|
||
- Token 已使用（重复扫码）：提示"QR token has already been used"
|
||
- 非本地 IP 使用 local-only token：拒绝，提示"QR login is only allowed from local network"
|
||
- 加载中：QR 区域显示 `common.loading` 对应文案（以 i18n 实际值为准），刷新按钮显示旋转动画
|
||
|
||
**验收标准**：
|
||
|
||
- [ ] 仅在 WebUI 运行 + 允许远程访问时显示 QR 区域
|
||
- [ ] 二维码自动生成，无需用户操作
|
||
- [ ] 显示有效期（本地化时间格式）
|
||
- [ ] QR 码在过期前自动刷新 [验证策略：代码审查 + 单元测试]
|
||
- [ ] 可手动点击刷新按钮
|
||
- [ ] 可复制二维码链接
|
||
- [ ] 扫码后可在手机浏览器中自动登录
|
||
- [ ] Token 为一次性使用，重复扫码失败
|
||
- [ ] 服务停止或关闭远程时 QR 区域消失
|
||
|
||
---
|
||
|
||
## (F-WEBUI-09) 页面结构 — WebUI / Channels 双 Tab [已实现]
|
||
|
||
**用户故事**：作为用户，我希望在"远程连接"设置页面中方便地切换 WebUI 服务配置和 Channel 渠道配置。
|
||
|
||
**正常流程**（用户视角）：
|
||
|
||
1. **桌面端**：页面顶部显示两个 Tab
|
||
- "WebUI"（图标：地球）— 默认选中
|
||
- "Channels"（图标：通讯 + 7 个渠道 logo 缩略图：Telegram/Lark/DingTalk/WeChat/WeCom/Slack/Discord）
|
||
2. 点击 Tab 切换内容区域
|
||
3. Channels Tab 内容通过懒加载方式加载，加载中显示"加载中..."
|
||
4. **非桌面端（WebUI 浏览器访问）**：无 Tab 切换，直接显示 Channels 配置内容（无 WebUI 服务管理功能）
|
||
|
||
**页面布局**：
|
||
|
||
- 导航路径：左侧栏"远程连接"（位于"应用"分组下，在"显示"和"桌面宠物"之间）
|
||
- URL hash：`#/settings/webui`
|
||
- WebUI Tab 内部结构：
|
||
1. 标题"WebUI"（h2）+ 功能描述 + 3 步引导提示条
|
||
2. WebUI 服务卡片（含蓝色提示横幅 + 启用开关 + 访问地址 + 远程访问开关）
|
||
3. 登录信息卡片（含用户名 + 密码 + QR 码登录）
|
||
|
||
**验收标准**：
|
||
|
||
- [ ] 桌面端显示 WebUI / Channels 双 Tab
|
||
- [ ] 默认选中 WebUI Tab
|
||
- [ ] Tab 切换后内容区域渲染完成，Channels 懒加载期间显示 loading 占位
|
||
- [ ] 仅在 Electron 桌面端渲染 WebUI 服务配置区域（含 Tab 切换）
|
||
- [ ] 非桌面端仅显示 Channels，无 Tab 切换
|
||
|
||
---
|
||
|
||
## (F-WEBUI-10) 状态实时同步 [已实现]
|
||
|
||
**用户故事**：作为用户，我希望设置页面能实时反映 WebUI 服务的最新状态，即使状态由其他来源（如应用菜单、启动恢复）触发变更。
|
||
|
||
**正常流程**（用户视角）：
|
||
|
||
1. 组件挂载时自动加载 WebUI 当前状态（偏好设置 + 服务运行状态）
|
||
2. 主进程触发的状态变更（启动/停止/端口变化）通过事件实时推送到设置页面
|
||
3. UI 自动更新所有相关元素（Switch 状态、运行标记、访问地址、QR 码区域）
|
||
|
||
**IPC 双通道机制**：
|
||
|
||
- **Electron 环境**：优先使用 `electronAPI.webuiGetStatus()`（直接 IPC，无超时问题）
|
||
- **非 Electron 后备**：使用 `webui.getStatus.invoke()`（bridge 模式，1.5s 超时）
|
||
- **实时事件**：`webui.statusChanged.on()` 监听主进程推送的状态变更
|
||
|
||
**异常情况**：
|
||
|
||
- 偏好设置读取失败：默认为未启用/不允许远程
|
||
- getStatus 调用失败或超时：使用兜底状态（`running: false, port: DEFAULT_PORT, adminUsername: 'admin'`）
|
||
- 主进程 emit 的状态事件丢失：不影响 UI 已有状态，仅下次操作时刷新
|
||
|
||
**验收标准**：
|
||
|
||
- [ ] 页面进入时自动加载最新状态
|
||
- [ ] 状态变更实时反映到 UI（无需手动刷新）
|
||
- [ ] 状态加载失败时使用合理的兜底默认值
|
||
|
||
---
|
||
|
||
## (F-WEBUI-11) 扩展系统 WebUI 贡献 [已实现] [验证策略：单元测试]
|
||
|
||
**用户故事**：作为扩展开发者，我希望能通过扩展 manifest 声明 API 路由和静态资源，自动注册到 WebUI 服务器。
|
||
|
||
**正常流程**（开发者视角）：
|
||
|
||
1. 在扩展的 `manifest.contributes.webui` 中声明 `apiRoutes` 和/或 `staticAssets`
|
||
2. 应用加载扩展时，`resolveWebuiContributions` 校验并注册贡献
|
||
3. API 路由和静态资源在 WebUI 服务器上可用
|
||
|
||
**安全校验规则**：
|
||
|
||
| 规则 | 说明 |
|
||
| ------------------ | ------------------------------------------------------------------------------ |
|
||
| 命名空间化 | 路径必须以 `/{extensionName}/` 开头 |
|
||
| 保留路径保护 | 不允许使用 `/`, `/api`, `/login`, `/logout`, `/qr-login`, `/static`, `/assets` |
|
||
| 路径冲突检测 | 跨扩展重复路径，后者被跳过 |
|
||
| 路径遍历防护 | `isPathWithinDirectory` 确保所有文件在扩展目录内 |
|
||
| 入口存在性检查 | 同时查找 dist 和 source 路径 |
|
||
| 静态资源目录存在性 | `existsSync` 检查目录 |
|
||
|
||
**已知局限**：
|
||
|
||
- `wsHandlers` 和 `middleware` 已声明但运行时不支持（仅 `console.warn` 提示）
|
||
|
||
**验收标准**：
|
||
|
||
- [ ] 合法的扩展 API 路由和静态资源可被注册
|
||
- [ ] 命名空间化和保留路径校验生效
|
||
- [ ] 路径遍历尝试被阻止
|
||
- [ ] 路径冲突时后者被跳过（不覆盖先注册的）
|
||
|
||
---
|
||
|
||
## 附录 A：WebUI 状态矩阵
|
||
|
||
| WebUI 开关 | 允许远程 | 访问地址 | QR 码区域 | 登录信息 |
|
||
| ---------- | -------- | ------------------------- | --------- | -------- |
|
||
| OFF | (any) | 不显示 | 不显示 | 显示 |
|
||
| ON | OFF | `http://localhost:{port}` | 不显示 | 显示 |
|
||
| ON | ON | `http://{lanIP}:{port}` | 显示 | 显示 |
|
||
|
||
---
|
||
|
||
## 附录 B：IPC 通信链路
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────────┐
|
||
│ 渲染进程 (Renderer) - WebuiModalContent.tsx │
|
||
│ │
|
||
│ 状态加载: │
|
||
│ ├─ ConfigStorage.get('webui.desktop.enabled') │
|
||
│ ├─ ConfigStorage.get('webui.desktop.allowRemote') │
|
||
│ ├─ electronAPI.webuiGetStatus() [优先] │
|
||
│ └─ webui.getStatus.invoke() [后备, 1.5s timeout] │
|
||
│ │
|
||
│ 服务启停: │
|
||
│ ├─ webui.start.invoke({ port, allowRemote }) [3s timeout] │
|
||
│ ├─ webui.stop.invoke() [fire-and-forget] │
|
||
│ └─ webui.statusChanged.on(callback) [实时监听] │
|
||
│ │
|
||
│ 认证管理 (双通道: electronAPI 优先, bridge 后备): │
|
||
│ ├─ webuiChangePassword / webui.changePassword.invoke │
|
||
│ ├─ webuiChangeUsername / webui.changeUsername.invoke │
|
||
│ └─ webuiGenerateQRToken / webui.generateQRToken.invoke │
|
||
│ │
|
||
│ 外部操作: │
|
||
│ ├─ shell.openExternal.invoke(url) [打开浏览器/指南] │
|
||
│ └─ navigator.clipboard.writeText(text) [复制] │
|
||
└──────────────────────────────────────────────────────────────────────┘
|
||
│ IPC Bridge + Direct IPC
|
||
┌─────────────────────▼────────────────────────────────────────────────┐
|
||
│ 主进程 (Main) - webuiBridge.ts │
|
||
│ │
|
||
│ Bridge providers: │
|
||
│ ├─ webui.getStatus → WebuiService.getStatus() │
|
||
│ ├─ webui.start → startWebServerWithInstance() │
|
||
│ ├─ webui.stop → server.close() + cleanupWebAdapter() │
|
||
│ ├─ webui.changePassword → WebuiService.changePassword() │
|
||
│ ├─ webui.changeUsername → WebuiService.changeUsername() │
|
||
│ ├─ webui.generateQRToken → generateQRLoginUrlDirect() │
|
||
│ └─ webui.verifyQRToken → verifyQRTokenDirect() │
|
||
│ │
|
||
│ Emitters (主→渲染): │
|
||
│ ├─ webui.statusChanged.emit({ running, port, localUrl }) │
|
||
│ └─ webui.resetPasswordResult.emit({ success, newPassword }) │
|
||
└─────────────────────┬────────────────────────────────────────────────┘
|
||
│
|
||
┌─────────────────────▼────────────────────────────────────────────────┐
|
||
│ 服务层 │
|
||
│ WebuiService: getStatus / changePassword / changeUsername / │
|
||
│ resetPassword / getLanIP │
|
||
│ webuiQR: generateQRLoginUrlDirect / verifyQRTokenDirect │
|
||
│ AuthService: validatePasswordStrength / validateUsername / │
|
||
│ generateRandomPassword / hashPassword / invalidateAllTokens │
|
||
└──────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 附录 C：Toast 通知汇总
|
||
|
||
| 触发操作 | Toast 类型 | i18n Key |
|
||
| -------------------- | ---------- | ------------------------------------- |
|
||
| WebUI 启动成功 | success | `settings.webui.startSuccess` |
|
||
| WebUI 停止成功 | success | `settings.webui.stopSuccess` |
|
||
| 远程访问切换重启成功 | success | `settings.webui.restartSuccess` |
|
||
| 启动/停止/重启失败 | error | `settings.webui.operationFailed` |
|
||
| 复制成功 | success | `common.copySuccess` |
|
||
| 用户名修改成功 | success | `settings.webui.usernameChanged` |
|
||
| 用户名修改失败 | error | `settings.webui.usernameChangeFailed` |
|
||
| 密码修改成功 | success | `settings.webui.passwordChanged` |
|
||
| 密码修改失败 | error | `settings.webui.passwordChangeFailed` |
|
||
| QR 码生成失败 | error | `settings.webui.qrGenerateFailed` |
|
||
|
||
---
|
||
|
||
## 附录 D：已知局限汇总
|
||
|
||
| # | 功能点 | 局限描述 | 来源 |
|
||
| --- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------- |
|
||
| 1 | F-WEBUI-01 | 启动 IPC 超时 3s 后乐观设置 `running: true`，同时持久化 `enabled=true`，可能导致 UI 与实际状态不一致且下次启动循环恢复失败服务 | R2 初稿 + C-04 |
|
||
| 2 | F-WEBUI-01 | 停止操作 fire-and-forget，Toast 出现时服务器可能仍在运行，停止失败用户无感知 | R2 初稿 + C-05 |
|
||
| 3 | F-WEBUI-04 | 远程访问切换需重启服务器，期间短暂不可用（最长 6s：停止 1.5s + 启动 3s + 状态确认 1.5s） | R2 初稿 + C-06 |
|
||
| 4 | F-WEBUI-06 | 密码首次可见状态是组件内存状态，页面刷新后丢失 | R2 初稿 |
|
||
| 5 | F-WEBUI-06 | 密码行仅有编辑按钮，无复制功能（与用户名行功能不对称） | C-07 |
|
||
| 6 | F-WEBUI-07 | 修改密码不需要输入当前密码，安全性依赖 Electron 本地环境信任 | R2 初稿 |
|
||
| 7 | F-WEBUI-05 | 用户名后端校验错误信息为硬编码英文，未做前端 i18n 翻译（密码修改有 errorCodeMap 翻译） | C-10 |
|
||
| 8 | F-WEBUI-05/07 | Token 失效通过 JWT secret 轮转实现（被动失效），已建立的 WebSocket 连接不会立即断开 | C-13 |
|
||
| 9 | F-WEBUI-08 | QR token 存储在进程内存 Map，主进程重启后全部失效 | R2 初稿 |
|
||
| 10 | F-WEBUI-08 | `isLocalIP` 不覆盖 IPv6 ULA 地址（`fd00::/8`） | R2 初稿 |
|
||
| 11 | F-WEBUI-08 | QR 码初始状态（尚未生成）和生成失败共用同一占位文案，组件无法区分两种状态 | C-11 |
|
||
| 12 | F-WEBUI-02 | UI 未暴露端口修改入口，仅可通过配置文件/CLI/环境变量修改 | R2 初稿 |
|
||
| 13 | F-WEBUI-02 | 桌面自动恢复（`restoreDesktopWebUIFromPreferences`）不经过 `resolveWebUIPort`/`resolveRemoteAccess`，CLI 和环境变量在此路径下不生效 | C-08 |
|
||
| 14 | F-WEBUI-01 | 端口递增上限固定为 `DEFAULT_PORT + 10`，用户指定端口超出此范围时递增不生效 | C-01 |
|