95 lines
9.2 KiB
Markdown
95 lines
9.2 KiB
Markdown
# 终端说明
|
||
|
||
基线日期：2026-11-09。当前是 Armbian/Xorg POC，正式目标仍为 Weston/Wayland。
|
||
|
||
同日已部署 Qt HTTPS 平台适配：现场存在 `~/.config/vdi-terminal/platform.json` 时，设备认证、桌面列表和一次性连接票据由真实平台提供，原 `desktops.json` 不再作为授权来源。启动、现场验收和回退见[真实云管接入](cloud-live-integration.md)。Qt 编译依赖新增 Network 模块，编码/显示配置沿用接入前版本。
|
||
|
||
<a id="session"></a>
|
||
## 开机与进出云桌面
|
||
|
||
产品入口由 LightDM 管理 `vdi-kiosk` 独占会话，再运行 `vdi-kiosk-start → vdi-kiosk-monitor → kiosk-shell`。开机直接进入“选择云桌面”，不再通过普通 MATE 桌面或旧登录页中转。Moonlight 只在选择桌面后启动，不能与 kiosk 分别设置开机自启。
|
||
|
||
11-10 补充：真实平台接入后的启动认证原先只尝试一次，任一失败都会跳回旧的用户名/密码页，并且不再认证。已改为先绘制选择页，再异步进行设备认证；失败留在该页显示自动重试提示，按 2/4/8/16/30 秒退避（请求完成后再计时），恢复后自动加载授权桌面。认证完成前不读取本地桌面作为授权、不发连接票据，不并发重复认证。设备撤销、配置错误同样不会回到旧登录页，但仍需管理员处理实际授权/配置问题。
|
||
|
||
用户首次启动失败的具体网络/TLS/HTTP 原因没有足够旧日志，不能仅凭第二次开机正常确定是哪一项。新增诊断只记录认证请求 HTTP 状态和网络错误码、重试间隔，不记录身份凭据或请求正文。回归结果见 [boot-auth-20261110](evidence/boot-auth-20261110/)。
|
||
|
||
部署/验证：11-10 盒子 ARM64 构建 CTest 4/4 通过；新增真实 HTTPS 隔离测试覆盖首次离线后恢复、403 后恢复、慢认证不重叠、同步配置错误、本地模式五个场景。只原子替换 kiosk-shell，由原看门狗重启子进程；当前进程认证 ready、平台授权列表 200/三桌面、独占会话与选择页截图核对通过，boot ID 未变，未再次断电验证。kiosk-shell SHA256 为 `9dba9c66092aa9ccf67477b305aaefe09f52eabb8c6b30dbbcbb1ce43dc7a6a6`；备份在 `~/vdi-terminal/backups/boot-device-auth-20261110/`。Moonlight 与光标校验配置未变。
|
||
|
||
主要配置/实现入口：
|
||
|
||
- [LightDM 配置](../terminal/kiosk-shell/etc/92-vdi-kiosk.conf)、[会话定义](../terminal/kiosk-shell/vdi-kiosk-session.desktop)、[启动脚本](../terminal/kiosk-shell/scripts/vdi-kiosk-start)。
|
||
- `~/.config/vdi-terminal/desktops.json` 保存各桌面地址、应用名、分辨率和 FPS；基础配置在 `client.conf`。`moonlight.conf` 属于旧独立调试入口，不代表产品连接参数。
|
||
- 当前常见状态流为 `BOOT → DESKTOP_LIST → CONNECTING → SESSION → DESKTOP_LIST`；首配、认证、重连和错误分支仍保留在状态机中。
|
||
|
||
11-09 的交接修复包括：
|
||
|
||
1. 串流期间保持全屏列表窗口映射在 Moonlight 下方，预先完成绘制；Moonlight 自己处理退出快捷键并销毁串流窗口时，下面已经是产品页面。
|
||
2. 串流期间释放 kiosk 键盘抓取，几何回调不抢焦点、不抬高列表；页面切换后再显示窗口。
|
||
3. 连接遮罩使用不透明 X11 override-redirect 窗口，无合成器时直接隐藏，不依赖透明淡出。
|
||
4. [Moonlight 0007](../terminal/moonlight/patches/0007-vdi-kiosk-launch-surface.patch) 由子进程环境 `VDI_KIOSK_STREAM=1` 启用：CLI Qt 启动/错误界面不映射，隐藏根窗口同步加载 QML，SDL 创建时即按输出位置与尺寸无边框全屏；失败通过非零退出码交给 kiosk 提示。独立 Moonlight GUI 不受此环境外的逻辑影响。
|
||
5. 部署采用二进制原子替换，由 LightDM 管理会话。停止会话主进程后从 SSH 脱离启动会使 LightDM 回到系统 greeter，不能用作正常恢复方式。
|
||
|
||
当日回归：进入阶段 Windows/Ubuntu/麒麟分别采样 819/908/968 次，启动 Qt 小窗和非全屏违规均为 0；后续返回采样 525/527/510 次，暴露违规为 0。另有此前两轮返回共 3121 个有效采样。证据见 [entry-surface](evidence/entry-surface-20261109/) 与 [return-surface](evidence/return-surface-20261109/)。这些是 X11 状态与截图验证，未做外置物理逐帧采集。
|
||
|
||
<a id="shortcuts"></a>
|
||
## 快捷键边界
|
||
|
||
用户要求从选择页到三种云桌面均不能通过快捷键唤起盒子系统内容。`MoonlightSession` 已使用 `--capture-system-keys always`，将 Win/Super、Alt+Tab 等系统组合键交给客体；无 MATE 会话也减少了宿主桌面快捷键入口。
|
||
|
||
- `Ctrl+Alt+Shift+Q`：结束当前串流并返回产品桌面列表，属于保留的退出入口。
|
||
- `Ctrl+Alt+Shift+M`：kiosk 管理菜单入口，和客户云桌面内的快捷键职责不同。
|
||
- `Win+Shift+S`：目标是在 Windows 内截屏；能否弹出还取决于客体截图工具/组件及键盘传递，不能把“没有盒子弹窗”当成“截图已成功”。
|
||
- [0004 电源键策略](../terminal/moonlight/patches/0004-vdi-power-key-policy.patch) 属于客户端输入策略；客体菜单关机限制由独立系统策略实施，详见[电源策略](desktop-guide.md#power)。历史现场构建与构建器补丁集合曾不同，核验二进制来源后再判断覆盖范围。
|
||
|
||
验收应同时覆盖选择页、连接中、串流中、退出后，逐一检查 Windows/Ubuntu/麒麟的系统键和截图快捷键。不能以一个系统通过推断另外两个通过。
|
||
|
||
<a id="display"></a>
|
||
## 显示器关开与 2K 恢复
|
||
|
||
当前盒子使用 `2560x1440_60_fixed297`，已验证时序：
|
||
|
||
```text
|
||
297.00 2560 2608 2640 2720 1440 1443 1448 1820 +HSync -VSync
|
||
```
|
||
|
||
[vdi-display-guard](../terminal/kiosk-shell/scripts/vdi-display-guard) 每 2 秒检查输出，异常持续至少 2 秒后恢复；健康状态只查询，断开时等待，失败按 2～60 秒退避。该盒子 vendor PHY 与显示器原厂 241.70MHz 时序存在兼容问题，不能直接换回原厂时序。
|
||
|
||
11-03 模拟两次 1920×1440 回退均自动恢复，用户实际关开显示器也确认恢复全屏；会话 PID 保持不变。当前验证局限于这台盒子、单 HDMI 显示器与 Xorg，不覆盖任意显示器或 Wayland。模式确实回退时驱动与守护切换可能需要约 15 秒。
|
||
|
||
仅部署显示守护入口为 [tools/deploy_display_guard.sh](../tools/deploy_display_guard.sh)，状态查询见[运维说明](operations.md#diagnosis)，证据见 [display-resume](evidence/display-resume-20261103/)。
|
||
|
||
<a id="build"></a>
|
||
## 构建与版本回退
|
||
|
||
在具备 Qt5 开发依赖的 ARM64 环境编译 kiosk：
|
||
|
||
```bash
|
||
cd terminal/kiosk-shell
|
||
cmake -G Ninja -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=ON
|
||
cmake --build build
|
||
QT_QPA_PLATFORM=offscreen ctest --test-dir build --output-on-failure
|
||
```
|
||
|
||
完整终端部署入口是 [tools/deploy_kiosk.sh](../tools/deploy_kiosk.sh)（开发机 Git Bash）；它会重启 LightDM、打断盒子当前串流。私有硬解客户端由 [tools/build-rkmpp-client.sh](../tools/build-rkmpp-client.sh) 在盒子构建。补丁范围、未采用实验和版本来源见 [Moonlight 模块说明](../terminal/moonlight/README.md)。以上命令是维护入口，本次文档整理未执行部署。
|
||
|
||
11-09 已验证 Moonlight SHA256：
|
||
|
||
```text
|
||
2e7441df1f6af5c4ddc79b89af15eed3b6b63cf265bea294ffc090483d8c6c51
|
||
```
|
||
|
||
旧二进制和 Linux 光标配置备份在盒子 `~/vdi-terminal/backups/return-surface-20261109/`。回退必须同时匹配 Moonlight 二进制与两台 Linux 原生光标 profile 中的客户端 SHA，不能只换二进制。显示守护旧文件备份为 `~/vdi-terminal/backups/display-guard-20261103-095920/`，恢复旧布局也会恢复原先的显示回退风险。
|
||
|
||
当日 CTest 3/3、原生光标边界测试 4/4 通过；完整实验过程及较早版本校验值见[归档](archive/README.md)。
|
||
|
||
## 运维策略（2026-11-10）
|
||
|
||
客户端 `qt-platform/0.4.0`（从 0.3.0 起）支持平台配置的心跳、命令检查和桌面列表刷新间隔。每 15 秒检查新版本，安全写入 `~/.config/vdi-terminal/policy.json`（0600）后更新运行定时器并回执；身份仍保存在原 `platform.json`，不要混用。新下发失败时保留原运行配置，原因在控制台「终端策略 → 设备结果」查看。
|
||
|
||
当前 kiosk-shell SHA256 `690a74ee5b077ff96e385f2ba45ca756f1879223f7433e63ec1833eb0f3a628b`，更新前备份 `~/vdi-terminal/backups/policy-20261110/kiosk-shell`；CTest 已增至 5 项并全部通过。真实盒子完成改变管理间隔及恢复默认的设备回执验证，保留之前启动认证重试与全屏交接修复。该次未测试断电、长时间离线或活动串流中下发。见[策略说明](cloud-terminal-policies-20261110.md)。
|
||
|
||
|
||
## 平台系统指标
|
||
|
||
`qt-platform/0.4.0` 在心跳中上报真实 CPU 使用率、内存使用率、SoC 温度和运行时长，沿用心跳策略（现场 30 秒）。控制台入口为「终端管理 → 详情 → 查看运行指标」，可查最近 1 小时/24 小时/7 天，历史保留 30 天。CPU 第一次采样为空；缺失传感器和离线过期数据不填零。不会更改串流参数，实际 FPS/RTT 仍未采集。定义与验收见[终端系统指标](cloud-terminal-metrics-20261110.md)。
|