songyiming/vdi-cloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
vdi-cloud/docs/cloud-live-integration.md

14 KiB
Raw Permalink Blame History

现场真实接入

更新：2026-11-10。与原演示环境分开，当前 API 使用 production 模式和独立 PostgreSQL，不生成演示节点、桌面或用户。服务运行在开发机 Docker Desktop；这是接入现场设备的联调环境，尚未迁到独立云服务器。

11-10 模板、桌面池与克隆接口及页面扩展见功能核对与验收边界。现场暂无 PVE 模板和创建权限，克隆实际发放仍待接入条件满足后验收。

Windows 模板来源已由用户确认为现有 Windows 镜像：复用 VM100 的系统作为母盘，不要求重装。VM100 当前仍在运行，PVE template=0，60 GiB 系统盘且带物理 GPU 直通；尚未制作独立模板副本。这里只读核查，没有转换现有桌面或修改显卡配置。

日常启动与入口

打开 Docker Desktop，在项目根目录运行：

.\tools\start-cloud-live.ps1

代码修改后加 -Build。控制台为 http://127.0.0.1:5182，初始管理员账号密码保存在本机忽略提交的 .local/live/admin-login.txt。原 5181 仍是独立演示环境，不作为现场入口。正式数据库命名卷 vdi-cloud-live_vdi-live-postgres；停止容器不会删除数据，勿执行 down -v。

盒子通过 https://192.168.1.159:8443 访问平台，校验专用 CA；HTTP 控制台端口只映射本机。开发机必须保持运行、内网地址可达，IP 变化时需更新证书、Compose 地址和盒子配置。浏览器从其他机器访问 HTTPS 时，需要信任本机生成的 CA；本轮没有将 CA 安装进系统证书库。

当前现场映射

对象 接入方式
PVE 192.168.1.51 / 节点 starhe 专用 vdi-cloud@pve!console Token；CA 验证开启，证书 DNS 名 starhe 通过容器 extra_hosts 映射实际 IP
Windows VM100 / .70 纳管已有 VM，2560×1440 / 45FPS 请求
麒麟 VM101 / .71 纳管已有 VM，2560×1440 / 30FPS 请求
Ubuntu VM102 / .72 纳管已有 VM，2560×1440 / 45FPS 请求
盒子 .188 / SN ee621cae7199a2e9 Qt 平台适配器 qt-platform/0.2.0，设备 Token、HTTPS 心跳和命令轮询

FPS 是串流请求参数，不是实际性能验收值。桌面与设备 ID 由数据库生成；本机 .local/live/site-state.json 保存本轮映射，不把固定演示 ID 用于真实环境。

PVE Token 继承专用用户权限：根路径 PVEAuditor 负责只读发现，只有 /vms/100、/vms/101、/vms/102 授予自定义 VDICloudPower（VM.Audit VM.PowerMgmt）。子路径 ACL 会覆盖继承权限，因此该角色同时包含 VM.Audit。平台没有 PVE root 密码、宿主重启、VM 创建、删除、改硬件权限。

终端实际流程

  1. 管理员登记 SN，生成一次性激活密钥。盒子读取 ~/.config/vdi-terminal/platform.json，通过注册接口取得设备 Token，以 0600 原子保存并删除激活密钥。

  2. 每 30 秒发送真实心跳；每 15 秒在选择页刷新授权桌面；每 3 秒领取远程命令。平台配置存在时不回退到本地授权或本地票据，列表与连接参数由平台维护。

    11-10 修复冷启动认证失败的页面回退：启动始终显示选择页，平台未就绪时按 2～30 秒退避自动重试，成功后加载授权桌面；不会退回旧账号密码页。此前首次失败的底层原因缺少足够日志，新增 HTTP 状态/网络错误码记录供复查，详见终端说明。

  3. 点击连接后申请、消费单次票据。消费只登记“连接中”，Moonlight 实际画面就绪后才上报 connected，计入活动连接。

  4. 自然退出、连接失败、管理员重置都会按 sessionId 释放预约。结束事件和回执写入待发队列，网络恢复后重试；已执行的命令不自动重放。旧会话事件或迟到的重置回执不能清理新会话。

  5. “重置会话”等待 Moonlight 进程真正退出后回执。“收集日志”上传受限诊断信息与脱敏日志尾部；管理员/运维可在成功任务详情下载，只读角色不可读取。

  6. “重启盒子”通过固定 sudo -n /usr/bin/systemctl reboot 调用，记录原 boot ID，下一次启动确认 boot ID 改变后才回执；未做现场重启验收。没有远程任意命令或 shell 参数接口。

本轮由 Qt 直接接入已有设备 API；未将它称为 Rust Agent 或 MQTT。Moonlight/Sunshine 继续使用原有配对；平台票据不是 Sunshine 的新认证方式。没有修改串流编码、光标、显示守护、USB 隧道配置。

初次配置其他现场

安装 Python 的 paramiko、cryptography 后，先确认 SSH known_hosts 中存在核验过的 PVE 主机公钥，再执行：

python tools/provision-pve-access.py --host <PVE-IP> --vmids <VM-ID...> --output .local/live/pve-access.json
python tools/prepare-live-config.py --ip <平台内网-IP> --pve-hostname <PVE证书内DNS名称> --pve-ip <PVE-IP>
.\tools\start-cloud-live.ps1 -Build

PVE SSH 密码通过交互提示或 VDI_PVE_SSH_PASSWORD 读取；工具不在控制台打印 Token。已存在配置或账号时会停止，防止覆盖已有身份。不要将本轮现场的 .local/live 文件复制给其他客户。

从控制台发现并纳管 VM、登记设备和创建用户授权。盒子配置格式如下，路径按现场用户调整：

{
  "url": "https://平台内网地址:8443",
  "caFile": "/home/armbian/.config/vdi-terminal/platform-ca.pem",
  "activationSecret": "控制台生成的一次性密钥"
}

配置和证书通过受信 SSH 安装；配置权限 0600。注册成功后由终端维护 deviceToken、待发事件和回执，不再手工覆盖。备份时同时保留数据库、PVE Token、平台 CA 私钥和终端身份文件，均按凭据管理。

盒子回退

本轮初始备份路径在盒子 ~/vdi-terminal/backups/platform-live-current-backup 指向的目录。备份包括接入前 kiosk-shell、client.conf、desktops.json。维护时先结束串流，再原子恢复该 kiosk-shell 并将 platform.json 移至受限备份目录，由原有监控进程重启 kiosk。恢复后是原本的本地 POC 模式，不再从平台授权。无需回退 Moonlight 二进制或重启 VM。

只撤销 PVE 接入时，可禁用 vdi-cloud@pve 用户或移除 console Token；不要删除 root 或其他账号。独立部署、用户目录集成、登录限流、备份恢复演练、终端策略、OTA 和多租户仍属于后续产品化范围。设备停用/重新激活及用户维护见11-10 功能说明。管理员账号维护与手工密码修改已于 11-10 接通。

本轮现场验收

  • PVE 严格 CA/DNS 验证通过，发现并纳管三台真实 VM；节点/VM 状态每 30 秒自动同步。
  • 盒子实际注册，心跳上报 qt-platform/0.2.0；控制台显示 1 台在线，串流请求使用现场原有配对。
  • Windows、Ubuntu、麒麟分别从真实授权列表申请并消费票据，实际画面就绪事件被平台记录；控制台分别下发 reset-session，Moonlight 实际退出后收到成功回执，最终活动连接均归零。
  • 首次 Windows 重置因同步检查异步退出而错误返回 failed，已保留任务；修复为异步等待后重测通过，未删除失败记录。
  • Go 测试与专用 PostgreSQL 集成测试、go vet 通过，新增覆盖会话事件隔离、预约不冒充活动串流、日志读取权限与迟到回执不清理新会话。盒子 CTest 3/3、前端静态检查、类型检查、单元测试和 Docker 构建通过。
  • 现场 Playwright 页面流程通过：正式登录、3 台真实桌面、真实设备在线、下发日志采集、收到成功回执并下载实际 boot ID/uptime/日志内容。截图见 真实总览、真实桌面。
  • 现场 kiosk-shell SHA256：2cca9d2d183c2f34f0f6172db207649decb2799414f9443043d175bbb19d33a1。Moonlight 二进制未更换。

以上为 11-09 接入验收。11-10 启动认证重试修复已更新 kiosk-shell 为 SHA256 9dba9c66092aa9ccf67477b305aaefe09f52eabb8c6b30dbbcbb1ce43dc7a6a6，CTest 4/4 与部署后真实选择页核验通过；原接入身份、票据、三桌面参数、Moonlight 均保留，未重启云桌面或宿主，未再次断电验收。备份与证据见终端说明。

浏览器现场用例独立执行，避免运行演示库用例操作真实 VM：

cd console
npx playwright test --config=playwright.live.config.ts

该用例读取本机私有初始账号文件，验证正式登录、真实桌面/设备以及日志收集下载，不发 VM 电源操作。完整演示 E2E 仍要求 demo 模式；数据库集成测试仍只指向专用 vdi_test。

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

5182 已部署「系统设置 → 管理员账号」和右上角本人改密入口，真实数据库验证新增/角色/启停/重置/改密及全部旧登录失效。临时账号已清理，原 root 密码、桌面连接参数、用户授权保持一致，3 台 VM 运行且终端在线。新增 administrators.enabled 默认 true；启动不重置既有密码或停用状态。更新前保留数据库备份及 before-admin-20261110 镜像，回退不能直接将旧 API 接到新增列数据库。完整说明见功能核对清单。

终端与用户维护更新（2026-11-10）

5182 已部署终端资料编辑、设备停用/重新激活、用户资料/启停及批量桌面授权。真实临时设备与用户验收后定向清理，原 root 密码、设备凭据、桌面配置、用户和授权保持一致，原盒子心跳继续推进。设备重新激活需管理员更新设备身份配置，不会通过旧令牌自动恢复。新增字段、回退边界和证据见本轮说明。

终端策略更新（2026-11-10）

5182 新增「终端策略」。真实设备客户端为 qt-platform/0.3.0，kiosk-shell SHA256 690a74ee5b077ff96e385f2ba45ca756f1879223f7433e63ec1833eb0f3a628b。盒子原二进制备份 ~/vdi-terminal/backups/policy-20261110/kiosk-shell；只替换空闲 kiosk 子进程，由既有看门狗接管，未重启 LightDM、Moonlight、PVE 或 VM。真实配置变更与恢复均已回执，最终为 30/3/15 秒管理间隔。本段记录策略批次的 0.3.0 版本，前文 SHA 为历史接入记录；最新 0.4.0 指标批次见后文。范围、接口与备份见终端策略说明。

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

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

11-10 接入配置、规格与登录限流

PVE 连接可在「系统设置 → 配置 Proxmox 接入」检查和保存，当前原地址/Token/CA 已入加密存储并通过重启核对，密钥不回显。JWT Secret 与数据库密文必须配套保管。桌面详情新增「规格管理」，三台真实 VM 读取和运行中拒绝修改已验证；现场缺 VM.Config.CPU/Memory/Disk 权限，未进行真实规格写入。管理员登录新增 5 分钟账号 10 次/来源 IP 30 次限制；设备心跳不受登录预算影响。详见入口、测试与恢复边界。

快照与手动还原（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 项页面回归通过。接口、权限、备份和现场证据见功能说明。

11-10 终端系统指标

当前真实盒子为 qt-platform/0.4.0，kiosk SHA256 6ff0697e9c5efb7428053d54af6d52f360e726eea5962e944f592c802f7463e1。旧二进制保留在 ~/vdi-terminal/bin/kiosk-shell.before-terminal-metrics-20261110。CPU、内存、SoC 温度和运行时长已连续上报入库，控制台详情可查历史。只在空闲时替换 kiosk，未重启 LightDM 或宿主；身份、策略文件、桌面参数、账号授权及三台 VM 配置核对一致。数据库备份、API、留存与采集限制见系统指标说明，现场结果见验收数据。