138 lines
14 KiB
Markdown
138 lines
14 KiB
Markdown
# 现场真实接入
|
||
|
||
更新：2026-11-10。与原演示环境分开，当前 API 使用 `production` 模式和独立 PostgreSQL，不生成演示节点、桌面或用户。服务运行在开发机 Docker Desktop；这是接入现场设备的联调环境，尚未迁到独立云服务器。
|
||
|
||
11-10 模板、桌面池与克隆接口及页面扩展见[功能核对与验收边界](cloud-feature-progress-20261110.md)。现场暂无 PVE 模板和创建权限，克隆实际发放仍待接入条件满足后验收。
|
||
|
||
Windows 模板来源已由用户确认为现有 Windows 镜像：复用 VM100 的系统作为母盘，不要求重装。VM100 当前仍在运行，PVE `template=0`，60 GiB 系统盘且带物理 GPU 直通；尚未制作独立模板副本。这里只读核查，没有转换现有桌面或修改显卡配置。
|
||
|
||
## 日常启动与入口
|
||
|
||
打开 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 秒领取远程命令。平台配置存在时不回退到本地授权或本地票据，列表与连接参数由平台维护。
|
||
|
||
11-10 修复冷启动认证失败的页面回退：启动始终显示选择页，平台未就绪时按 2～30 秒退避自动重试，成功后加载授权桌面；不会退回旧账号密码页。此前首次失败的底层原因缺少足够日志，新增 HTTP 状态/网络错误码记录供复查，详见[终端说明](terminal-guide.md#session)。
|
||
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 和多租户仍属于后续产品化范围。设备停用/重新激活及用户维护见[11-10 功能说明](cloud-lifecycle-20261110.md)。管理员账号维护与手工密码修改已于 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/日志内容。截图见 [真实总览](evidence/cloud-live-20261109/overview.png)、[真实桌面](evidence/cloud-live-20261109/desktops.png)。
|
||
- 现场 kiosk-shell SHA256：`2cca9d2d183c2f34f0f6172db207649decb2799414f9443043d175bbb19d33a1`。Moonlight 二进制未更换。
|
||
|
||
以上为 11-09 接入验收。11-10 启动认证重试修复已更新 kiosk-shell 为 SHA256 `9dba9c66092aa9ccf67477b305aaefe09f52eabb8c6b30dbbcbb1ce43dc7a6a6`，CTest 4/4 与部署后真实选择页核验通过；原接入身份、票据、三桌面参数、Moonlight 均保留，未重启云桌面或宿主，未再次断电验收。备份与证据见[终端说明](terminal-guide.md#session)。
|
||
|
||
浏览器现场用例独立执行，避免运行演示库用例操作真实 VM：
|
||
|
||
```powershell
|
||
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 接到新增列数据库。完整说明见[功能核对清单](cloud-feature-progress-20261110.md)。
|
||
|
||
## 终端与用户维护更新（2026-11-10）
|
||
|
||
5182 已部署终端资料编辑、设备停用/重新激活、用户资料/启停及批量桌面授权。真实临时设备与用户验收后定向清理，原 root 密码、设备凭据、桌面配置、用户和授权保持一致，原盒子心跳继续推进。设备重新激活需管理员更新设备身份配置，不会通过旧令牌自动恢复。新增字段、回退边界和证据见[本轮说明](cloud-lifecycle-20261110.md)。
|
||
|
||
## 终端策略更新（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 指标批次见后文。范围、接口与备份见[终端策略说明](cloud-terminal-policies-20261110.md)。
|
||
|
||
## 11-10 批量导入、会话历史与告警
|
||
|
||
新增 CSV 用户/终端/授权导入、90 天会话历史、PostgreSQL 节点采样及控制台告警，入口、接口、留存、迁移与验收范围见[功能说明](cloud-operations-20261110.md)。VictoriaMetrics 和外部通知仍待接入。
|
||
|
||
## 11-10 接入配置、规格与登录限流
|
||
|
||
PVE 连接可在「系统设置 → 配置 Proxmox 接入」检查和保存，当前原地址/Token/CA 已入加密存储并通过重启核对，密钥不回显。JWT Secret 与数据库密文必须配套保管。桌面详情新增「规格管理」，三台真实 VM 读取和运行中拒绝修改已验证；现场缺 VM.Config.CPU/Memory/Disk 权限，未进行真实规格写入。管理员登录新增 5 分钟账号 10 次/来源 IP 30 次限制；设备心跳不受登录预算影响。详见[入口、测试与恢复边界](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)。
|
||
|
||
|
||
## 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、留存与采集限制见[系统指标说明](cloud-terminal-metrics-20261110.md)，现场结果见[验收数据](evidence/cloud-terminal-metrics-20261110/live-verification.json)。
|