196 lines
16 KiB
Markdown
196 lines
16 KiB
Markdown
# 云端服务与控制台开发说明
|
||
|
||
更新：2026-11-09。当前交付是第一阶段本地可运行版本。Vue 控制台通过真实 HTTP 调用 Go API，账号、授权、设备、任务和审计保存在 PostgreSQL；演示 VM 的电源操作由明确标记的演示计算适配执行。本文件主要描述演示开发环境；随后已接通[独立真实环境](cloud-live-integration.md)，控制台端口 5182、设备 HTTPS 8443。
|
||
|
||
11-10 新增模板登记、PVE 克隆任务、桌面池、初始化连接配置，以及真实管理员账号维护和本人改密。最新实现范围、操作路径、现场前提和剩余功能见[功能核对清单](cloud-feature-progress-20261110.md)。
|
||
|
||
## 启动
|
||
|
||
### Windows 本机开发
|
||
|
||
需要 Node.js 22.12+、Go 1.25+、Docker Desktop。仓库根目录执行：
|
||
|
||
```powershell
|
||
.\tools\start-cloud-dev.ps1
|
||
```
|
||
|
||
已安装前端依赖时可加 `-SkipInstall`。脚本启动专用 PostgreSQL 容器，编译并启动本机 API，再启动 Vite。默认控制台地址 `http://127.0.0.1:5180`，API 地址 `http://127.0.0.1:8088`，数据库仅映射本机 `55438`。可用 `-ApiPort` 和 `-ConsolePort` 改开发端口。不会停止其他占用端口的程序。
|
||
|
||
演示账号 `admin`、`operator`、`viewer`，统一演示密码 `Demo@2026`。对应超级管理员、运维、只读角色，仅 `VDI_MODE=demo` 会创建这些账号。首次数据库初始化后，重新启动保留业务数据。
|
||
|
||
进程 PID 和日志在忽略提交的 `.local/` 中。关闭本机开发进程时根据 `.local/cloud-dev.json` 确认 PID 和命令路径，只停止本次启动的 API 与 Vite。数据库可通过 `docker compose -f deploy/compose.dev.yml stop postgres` 停止；不删除卷即可保留数据。
|
||
|
||
### 全容器开发
|
||
|
||
与本机模式二选一，避免占用同一端口：
|
||
|
||
```powershell
|
||
docker compose -f deploy/compose.dev.yml up --build -d
|
||
```
|
||
|
||
控制台仍是 `http://127.0.0.1:5180`。Nginx 代理同源 `/api` 到 Go 服务，PostgreSQL 使用命名卷。该 compose 是开发演示配置，不是客户生产部署包。
|
||
|
||
端口被其他开发进程占用时，可先设置 `$env:VDI_CONSOLE_PORT='5181'`、`$env:VDI_API_PORT='8089'` 再执行 compose。当前本机验收使用该端口组合，预览地址为 `http://127.0.0.1:5181`。
|
||
|
||
### 仅前端模拟
|
||
|
||
```powershell
|
||
cd console
|
||
npm ci
|
||
$env:VITE_API_MODE='mock'
|
||
npm run dev
|
||
```
|
||
|
||
MSW 在浏览器层模拟 HTTP，只有开发构建允许启用，不需要 Go 或数据库。模拟操作不控制真实资源，刷新页面会重置模拟业务数据。正常的 `api` 模式不注册模拟 Worker。
|
||
|
||
## 当前可用范围
|
||
|
||
| 模块 | 当前实现 |
|
||
| --- | --- |
|
||
| 登录 | bcrypt 密码校验、JWT、服务端会话记录、退出撤销、刷新页面恢复、三角色服务端授权 |
|
||
| 总览 | 终端在线、VM 电源、实际画面就绪连接、异常任务；连接预约单独记录 |
|
||
| 计算资源 | 节点列表；配置 PVE 后每 30 秒同步节点/已纳管 VM，显示同步时间与过期标记 |
|
||
| 桌面 | 演示桌面；发现 PVE VM、纳管、查看详情、开机/正常关机/重启；PVE UPID 跟踪 |
|
||
| 终端 | 管理员登记、一次性激活、设备独立令牌、心跳、桌面授权列表、命令领取与回执 |
|
||
| 授权 | 创建最终使用者、每设备关联一位使用者、每使用者多个桌面、停用和撤销后阻止新连接 |
|
||
| 任务 | 持久化排队/执行/成功/失败/结果未确认、请求去重、同对象任务互斥、最终回执审计 |
|
||
| 连接契约 | 短期单次票据、终端隔离、消费时重新校验授权、同桌面活动占用检查 |
|
||
|
||
当前连接票据仅授权并返回 Moonlight 端点与参数；终端仍需既有 Sunshine 配对。消费票据登记连接预约，不证明串流已建立；现场 Qt 已上报实际画面就绪与进程结束事件，详情见真实接入说明。不要把 `credentialMode=existing-pairing` 当作免配对认证。
|
||
|
||
本轮将 API 入口与基础业务模块放在一个可运行的 Go 网关进程中，数据库和 Proxmox client 独立封装。原方案的七个服务职责继续作为后续拆分边界；当前尚未交付七个独立部署的服务。MQTT 总线、Rust Agent、VictoriaMetrics 指标接入、GPU 绑定、OTA、AD/LDAP 尚未完成；模板登记、克隆编排与桌面池已在后续批次实现，现场发放仍待模板和权限验收；Qt 适配现已实际部署。控制台仅显示已接通的第一阶段功能。
|
||
|
||
## 真实 Proxmox 接入
|
||
|
||
使用新的独立数据库，按 `platform/.env.example` 注入配置。正式模式要求至少 32 字符的 JWT 密钥、管理员账号和至少 12 字符的初始密码。管理员环境变量仅在账号首次创建时生效，不会在每次启动时覆盖已有密码。数据库记录初始化模式，拒绝直接混用演示与正式数据库。
|
||
|
||
```text
|
||
VDI_MODE=production
|
||
DATABASE_URL=postgres://.../vdi?sslmode=require
|
||
VDI_JWT_SECRET=...
|
||
VDI_ADMIN_USERNAME=...
|
||
VDI_ADMIN_PASSWORD=...
|
||
PVE_URL=https://pve.example.internal:8006
|
||
PVE_TOKEN_ID=vdi@pve!console
|
||
PVE_TOKEN_SECRET=...
|
||
PVE_CA_FILE=/run/secrets/pve-ca.pem
|
||
```
|
||
|
||
PVE API Token 密钥由后端保管，网页只输入不回显，终端不接收；证书校验始终开启。PVE_URL 只填 HTTPS origin，不附 `/api2/json`。由运维给 API Token 配置实际需要的节点/VM/存储查询和 VM 电源操作权限。本轮不自动修改 PVE 账号、ACL、VM 或主机配置。
|
||
|
||
启动后到“计算资源”手动同步；再到“桌面管理”选择“纳管已有 VM”。纳管仅登记已存在的 VM，不改 VM 配置。连接地址可在纳管表单填写。首次真实接入应使用专门测试 VM 核验 API 版本、证书、任务结果和关机行为，再对业务 VM 开放操作。
|
||
|
||
正式环境的 HTTPS 入口、运维凭据轮换、独立数据库迁移流程与备份恢复仍属于部署产品化工作；账号维护与登录限流已在后续批次接入；当前 compose 不作生产就绪声明。
|
||
|
||
## 设备接口联调
|
||
|
||
接口契约在 `docs/openapi/platform.v1.json`，API 根路径 `/api/v1`。控制台通过生成的类型和统一请求适配调用接口，页面不拼接 API 地址。
|
||
|
||
1. 管理员在终端页登记 SN，取得仅显示一次的 `activationSecret`。
|
||
2. 终端 `POST /terminal/register` 提交 SN、activationSecret、agentVersion，取得设备令牌；激活密钥随即作废。
|
||
3. 设备以独立 `Authorization: Bearer <device-token>` 发送心跳、拉配置和获取授权桌面。
|
||
4. 管理员创建用户并关联终端、勾选多个桌面；设备再次请求 `/terminal/desktops` 即获得更新列表。
|
||
5. 设备轮询 `GET /terminal/commands` 领取命令，执行后 `POST /terminal/commands/{id}/ack` 报告 success/failed。没有回执的命令约两分钟后显示结果未确认；不会自动重放。
|
||
6. 申请 `/terminal/connect-ticket`，再用 `/terminal/connect-ticket/consume` 单次消费；消费时再次检查授权与桌面占用。之后仍使用已有 Moonlight/Sunshine 配对。
|
||
|
||
`tools/platform-terminal-simulator.py --sn <SN>` 可在本机演示平台注册、发心跳和读取授权桌面。激活密钥通过交互输入或 `VDI_DEVICE_ACTIVATION_SECRET` 传入；模拟器对所有设备操作回失败，避免假装执行了重启或日志收集。它不是可部署的 Rust Agent。
|
||
|
||
当前 HTTPS 轮询是 MQTT 接入前的可验证通道；没有声称已提供消息总线。终端令牌的撤销/重新激活、配置热更新将继续扩展契约；Qt 串流事件、固定命令执行和诊断日志上传已在真实环境接通。
|
||
|
||
## 检查命令
|
||
|
||
```powershell
|
||
cd console
|
||
npm run lint
|
||
npm run typecheck
|
||
npm run test
|
||
npm run build
|
||
npm run test:e2e
|
||
npm run api:generate
|
||
```
|
||
|
||
E2E 使用已经启动的本机平台，只允许对 `/healthz` 返回 demo 模式的服务运行；Windows 默认使用已安装的 Edge。其他环境使用 `npx playwright install chromium` 准备测试浏览器。`VDI_E2E_URL` 可覆盖测试地址。测试会创建演示用户和待激活终端、切换演示 VM 电源，不会操作真实 PVE。
|
||
|
||
```powershell
|
||
cd platform
|
||
go test ./...
|
||
go vet ./...
|
||
```
|
||
|
||
数据库集成测试需要 `VDI_TEST_DATABASE_URL` 指向**专用可清空测试数据库**。测试会清空该数据库内平台表，不要指向开发业务库或生产库。
|
||
|
||
```powershell
|
||
docker exec vdi-cloud-dev-postgres-1 psql -U vdi -d postgres -c 'CREATE DATABASE vdi_test'
|
||
$env:VDI_TEST_DATABASE_URL='postgres://vdi:vdi-local-demo@127.0.0.1:55438/vdi_test?sslmode=disable'
|
||
go test ./...
|
||
```
|
||
|
||
后端测试覆盖服务端 RBAC、JWT 退出失效、幂等任务、授权变更事务回滚、设备隔离、一次性票据、回执和超时；PVE client 使用本地测试服务器验证 TLS 和 UPID，不向现场 PVE 发送请求。
|
||
|
||
## 本轮验收记录（2026-11-09）
|
||
|
||
- Go 单元测试、专用 PostgreSQL 集成测试和 `go vet` 通过；包含模式隔离、重启后撤权保留、PVE 明确失败与提交结果未确认的区分。
|
||
- 前端 ESLint、TypeScript、3 项登录状态单元测试和生产构建通过。
|
||
- 容器版 `http://127.0.0.1:5181` 的 7 项 Playwright 用例全部通过：登录失败/恢复/退出、桌面命令最终结果、用户多桌面授权持久化、终端激活信息、两种权限角色、空列表/异常/401。
|
||
- 单独启动 MSW 模式，验证模拟登录和授权页导航；检查 1440px 桌面及 390px 窄屏。
|
||
- 页面截图：[总览](evidence/cloud-console-20261109/overview.png)、[桌面管理](evidence/cloud-console-20261109/desktops.png)、[窄屏](evidence/cloud-console-20261109/narrow.png)。页面主题集中在 `console/src/styles/tokens.css`，可交给 UI 同事继续调整。
|
||
- Node 依赖完整审计为 0 项已知漏洞。Vitest 已更新；TypeScript ESLint 的 minimatch 子依赖定向覆盖至 11.0.1+，静态检查通过。
|
||
- Docker API/控制台镜像构建并启动，数据库保留卷内已有业务数据。未向现场 PVE 或盒子发送操作。
|
||
|
||
## 数据与执行边界
|
||
|
||
- 在线按最近 90 秒心跳计算；FPS/RTT 缺失为 null，不填 0。PVE 电源状态与 VM 内连接服务状态分开。
|
||
- 任务成功必须有计算适配结果或设备回执。提交后发生通信异常时保留“结果未确认”，由管理员核对实际状态，不自动重试。
|
||
- 桌面“重启”只用 PVE reboot；未将硬重启 reset 冒充“还原镜像”。
|
||
- 任务和审计已支持完整历史的数据库分页、组合检索及 CSV 导出；单次导出最多 10000 条。全局轮询只读取近期任务和全部未结束任务；外部归档、防篡改待扩展。详见[任务历史](cloud-task-history-20261111.md)和[审计历史](cloud-audit-history-20261111.md)。
|
||
- 凭据不写入审计；设备上报的自由文本不直接放入公开任务结果。
|
||
|
||
## 管理员维护（2026-11-10）
|
||
|
||
真实环境入口为「系统设置 → 管理员账号」，仅超级管理员可新增、编辑角色/显示名称、启停及重置他人密码。所有角色通过右上角钥匙修改本人密码；角色/状态/密码变化撤销该账号所有会话。新增密码至少 12 字符且 UTF-8 不超过 72 字节，原账号不强制改密；无永久删除入口。迁移、测试和验收证据见[功能清单](cloud-feature-progress-20261110.md)。
|
||
|
||
## 终端与桌面用户维护（2026-11-10）
|
||
|
||
终端列表支持编辑名称/分组，详情增加停用/重新激活；用户列表支持资料编辑、启停和批量追加/撤销指定桌面。设备停用撤销旧身份，重新激活显示一次性密钥并需管理员更新设备配置。活动会话和未完成命令会阻止身份重置；用户权限变更阻止后续连接，既有串流单独重置。完整接口、迁移和验收见[本轮说明](cloud-lifecycle-20261110.md)。
|
||
|
||
## 11-10 终端策略
|
||
|
||
新增策略模板、下发记录、设备结果和设备应用回执。配置版本沿用终端版本递增；四张独立策略表保存能力、模板与历史，不向既有业务表新增列。仅超级管理员可创建/下发，设备回执沿用鉴权事务与行锁。Qt 客户端在安全持久化后热更新实际定时器，失败保留原运行配置；不改变串流参数。已部署本机真实服务与 RK3528 盒子并验证配置变化/恢复，详见[实现与验收](cloud-terminal-policies-20261110.md)。
|
||
|
||
## 11-10 批量导入、会话历史与告警
|
||
|
||
新增 CSV 用户/终端/授权导入、90 天会话历史、PostgreSQL 节点采样及控制台告警，入口、接口、留存、迁移与验收范围见[功能说明](cloud-operations-20261110.md)。VictoriaMetrics 和外部通知仍待接入。
|
||
|
||
## 接入配置与规格任务（2026-11-10）
|
||
|
||
新增网页 PVE 配置及热加载、真实规格读取/预检/变更任务与只读核对、共享数据库的登录限流。完整接口、可信代理、加密密钥保存要求、独立测试和现场权限限制见[本批说明](cloud-configuration-20261110.md)。
|
||
|
||
|
||
## 快照与手动还原（2026-11-10）
|
||
|
||
新增 snapshot_jobs 表及电源/规格/快照任务的共同活动索引，启动幂等迁移。控制台入口为「桌面管理 → 详情 → 快照与还原」；仅支持关机后的普通虚拟磁盘与无内存还原，含数据盘的快照也会回退其数据。原任务未知不重发，成功还原后须重新确认连接初始化。接口、测试、备份和现场权限/VM100 限制见[本批说明](cloud-snapshots-20261110.md)。本批未进行真实 VM 快照写入，公共池自动领取/还原尚未实施。
|
||
|
||
|
||
## 桌面批量电源操作（2026-11-10）
|
||
|
||
5182 的「桌面管理」新增跨页选择、批量开机/正常关机/重启和批次历史，每批最多 50 台。逐台真实预检、5 分钟签名凭证、确认后幂等提交；执行前复查，未确认结果不重发并阻止后续修改和新连接。Go 全量与静态检查、前端检查和 45 项隔离接口页面回归通过；真实环境只做预检与取消提交，三台桌面继续运行。新增表、任务状态、备份与现场边界见[功能说明](cloud-batch-operations-20261110.md)。专用测试 VM、Windows 副本和存储准备按用户要求暂缓。
|
||
|
||
|
||
## GPU 资源查看（2026-11-10）
|
||
|
||
5182 侧栏新增「GPU 资源」，三角色均可读取节点显卡清单、PCI 地址、IOMMU 分组与当前/待应用的虚拟机配置引用，支持搜索、筛选与详情。现场确认 Intel 核显、GTX 965M 及 Windows VM100 引用；自定义配置导致不完整时明确提示，不将未发现引用视为可分配。只新增 GET 接口，无数据库迁移或 GPU 写入；Go 全量与静态检查、前端检查和 51 项页面回归通过。接口、权限、备份和现场证据见[功能说明](cloud-gpu-inventory-20261110.md)。
|
||
|
||
|
||
## 终端系统指标与历史（2026-11-10）
|
||
|
||
5182 的「终端管理 → 详情 → 查看运行指标」已接通真实 CPU、内存、SoC 温度和运行时长，支持 1 小时/24 小时/7 天趋势、30 天留存、缺失断线和过期隐藏。盒子升级为 `qt-platform/0.4.0`，真实连续采样已入库，旧 Agent 兼容通过；没有将目标 FPS 或请求耗时当作串流实测指标。Go 全量及静态检查、前端检查/构建、57 项页面回归和盒子 6 项 CTest 通过，真实深浅主题及 390px 页面检查无异常。原设备配置、账号密码哈希指纹、桌面参数和授权一致，三台 VM 的配置 digest 与运行状态保持。详见[采集范围与验收](cloud-terminal-metrics-20261110.md)。串流 FPS/RTT、GPU 健康指标及系统指标告警仍待接入。
|
||
|
||
|
||
## 终端系统指标告警（2026-11-11）
|
||
|
||
5182「监控告警」新增终端 CPU、内存、SoC 温度规则，按真实新采样计算持续时长；计时不早于规则启用/修改，重复评估不推进，缺失/过期不冒充恢复。支持原有三角色权限、确认、规则启停和 90 天事件历史；摄氏度与百分比分开显示。Go 全量与静态检查、前端检查/构建及 61 项隔离页面回归通过，旧规则/事件/待触发状态的重复升级验证通过。无需更新终端，未操作 VM、磁盘或 GPU。详见[规则与验收边界](cloud-terminal-alerts-20261111.md)。
|
||
|
||
2026-11-11：[管理员在线登录管理](cloud-admin-sessions-20261111.md)已上线，提供单独撤销与登录来源查看。新增兼容附表，密码与原会话表不重置。
|
||
|
||
2026-11-11：[可选管理员 TOTP 双重验证](cloud-mfa-20261111.md)已上线。既有账号默认不启用；启用账号必须验证动态码或恢复码。存在启用账号时禁止直接回退到不校验 MFA 的旧 API。
|