90 lines
7.3 KiB
Markdown
90 lines
7.3 KiB
Markdown
# 现场真实接入
|
||
|
||
更新：2026-11-09。与原演示环境分开，当前 API 使用 `production` 模式和独立 PostgreSQL，不生成演示节点、桌面或用户。服务运行在开发机 Docker Desktop；这是接入现场设备的联调环境，尚未迁到独立云服务器。
|
||
|
||
## 日常启动与入口
|
||
|
||
打开 Docker Desktop，在项目根目录运行：
|
||
|
||
```powershell
|
||
.\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 秒领取远程命令。平台配置存在时不回退到本地授权或本地票据，列表与连接参数由平台维护。
|
||
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 主机公钥，再执行：
|
||
|
||
```powershell
|
||
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、登记设备和创建用户授权。盒子配置格式如下，路径按现场用户调整：
|
||
|
||
```json
|
||
{
|
||
"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 和多租户仍属于后续产品化范围。
|
||
|
||
## 本轮现场验收
|
||
|
||
- 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/日志内容。截图见 [真实总览](evidence/cloud-live-20261109/overview.png)、[真实桌面](evidence/cloud-live-20261109/desktops.png)。
|
||
- 现场 kiosk-shell SHA256：`2cca9d2d183c2f34f0f6172db207649decb2799414f9443043d175bbb19d33a1`。Moonlight 二进制未更换。
|
||
|
||
浏览器现场用例独立执行，避免运行演示库用例操作真实 VM：
|
||
|
||
```powershell
|
||
cd console
|
||
npx playwright test --config=playwright.live.config.ts
|
||
```
|
||
|
||
该用例读取本机私有初始账号文件，验证正式登录、真实桌面/设备以及日志收集下载，不发 VM 电源操作。完整演示 E2E 仍要求 demo 模式；数据库集成测试仍只指向专用 vdi_test。
|