songyiming/vdi-cloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
5ac692724d
vdi-cloud/docs/cloud-platform-development.md

15 KiB
Raw Blame History

云端服务与控制台开发说明

更新：2026-11-09。当前交付是第一阶段本地可运行版本。Vue 控制台通过真实 HTTP 调用 Go API，账号、授权、设备、任务和审计保存在 PostgreSQL；演示 VM 的电源操作由明确标记的演示计算适配执行。本文件主要描述演示开发环境；随后已接通独立真实环境，控制台端口 5182、设备 HTTPS 8443。

11-10 新增模板登记、PVE 克隆任务、桌面池、初始化连接配置，以及真实管理员账号维护和本人改密。最新实现范围、操作路径、现场前提和剩余功能见功能核对清单。

启动

Windows 本机开发

需要 Node.js 22.12+、Go 1.25+、Docker Desktop。仓库根目录执行：

.\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 停止；不删除卷即可保留数据。

全容器开发

与本机模式二选一，避免占用同一端口：

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。

仅前端模拟

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 字符的初始密码。管理员环境变量仅在账号首次创建时生效，不会在每次启动时覆盖已有密码。数据库记录初始化模式，拒绝直接混用演示与正式数据库。

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 串流事件、固定命令执行和诊断日志上传已在真实环境接通。

检查命令

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。

cd platform
go test ./...
go vet ./...

数据库集成测试需要 VDI_TEST_DATABASE_URL 指向专用可清空测试数据库。测试会清空该数据库内平台表，不要指向开发业务库或生产库。

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 窄屏。
  • 页面截图：总览、桌面管理、窄屏。页面主题集中在 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 冒充“还原镜像”。
  • 当前任务和审计列表展示最近 1000 条，完整记录仍存 PostgreSQL；长期检索和归档后续扩展。
  • 凭据不写入审计；设备上报的自由文本不直接放入公开任务结果。

管理员维护（2026-11-10）

真实环境入口为「系统设置 → 管理员账号」，仅超级管理员可新增、编辑角色/显示名称、启停及重置他人密码。所有角色通过右上角钥匙修改本人密码；角色/状态/密码变化撤销该账号所有会话。新增密码至少 12 字符且 UTF-8 不超过 72 字节，原账号不强制改密；无永久删除入口。迁移、测试和验收证据见功能清单。

终端与桌面用户维护（2026-11-10）

终端列表支持编辑名称/分组，详情增加停用/重新激活；用户列表支持资料编辑、启停和批量追加/撤销指定桌面。设备停用撤销旧身份，重新激活显示一次性密钥并需管理员更新设备配置。活动会话和未完成命令会阻止身份重置；用户权限变更阻止后续连接，既有串流单独重置。完整接口、迁移和验收见本轮说明。

11-10 终端策略

新增策略模板、下发记录、设备结果和设备应用回执。配置版本沿用终端版本递增；四张独立策略表保存能力、模板与历史，不向既有业务表新增列。仅超级管理员可创建/下发，设备回执沿用鉴权事务与行锁。Qt 客户端在安全持久化后热更新实际定时器，失败保留原运行配置；不改变串流参数。已部署本机真实服务与 RK3528 盒子并验证配置变化/恢复，详见实现与验收。

11-10 批量导入、会话历史与告警

新增 CSV 用户/终端/授权导入、90 天会话历史、PostgreSQL 节点采样及控制台告警，入口、接口、留存、迁移与验收范围见功能说明。VictoriaMetrics 和外部通知仍待接入。

接入配置与规格任务（2026-11-10）

新增网页 PVE 配置及热加载、真实规格读取/预检/变更任务与只读核对、共享数据库的登录限流。完整接口、可信代理、加密密钥保存要求、独立测试和现场权限限制见本批说明。

快照与手动还原（2026-11-10）

新增 snapshot_jobs 表及电源/规格/快照任务的共同活动索引，启动幂等迁移。控制台入口为「桌面管理 → 详情 → 快照与还原」；仅支持关机后的普通虚拟磁盘与无内存还原，含数据盘的快照也会回退其数据。原任务未知不重发，成功还原后须重新确认连接初始化。接口、测试、备份和现场权限/VM100 限制见本批说明。本批未进行真实 VM 快照写入，公共池自动领取/还原尚未实施。

桌面批量电源操作（2026-11-10）

5182 的「桌面管理」新增跨页选择、批量开机/正常关机/重启和批次历史，每批最多 50 台。逐台真实预检、5 分钟签名凭证、确认后幂等提交；执行前复查，未确认结果不重发并阻止后续修改和新连接。Go 全量与静态检查、前端检查和 45 项隔离接口页面回归通过；真实环境只做预检与取消提交，三台桌面继续运行。新增表、任务状态、备份与现场边界见功能说明。专用测试 VM、Windows 副本和存储准备按用户要求暂缓。

GPU 资源查看（2026-11-10）

5182 侧栏新增「GPU 资源」，三角色均可读取节点显卡清单、PCI 地址、IOMMU 分组与当前/待应用的虚拟机配置引用，支持搜索、筛选与详情。现场确认 Intel 核显、GTX 965M 及 Windows VM100 引用；自定义配置导致不完整时明确提示，不将未发现引用视为可分配。只新增 GET 接口，无数据库迁移或 GPU 写入；Go 全量与静态检查、前端检查和 51 项页面回归通过。接口、权限、备份和现场证据见功能说明。

终端系统指标与历史（2026-11-10）

5182 的「终端管理 → 详情 → 查看运行指标」已接通真实 CPU、内存、SoC 温度和运行时长，支持 1 小时/24 小时/7 天趋势、30 天留存、缺失断线和过期隐藏。盒子升级为 qt-platform/0.4.0，真实连续采样已入库，旧 Agent 兼容通过；没有将目标 FPS 或请求耗时当作串流实测指标。Go 全量及静态检查、前端检查/构建、57 项页面回归和盒子 6 项 CTest 通过，真实深浅主题及 390px 页面检查无异常。原设备配置、账号密码哈希指纹、桌面参数和授权一致，三台 VM 的配置 digest 与运行状态保持。详见采集范围与验收。串流 FPS/RTT、GPU 健康指标及系统指标告警仍待接入。