# 云桌面说明

状态以[当前状态](current-status.md)为入口，以下归纳三种系统的显示、输入、外设和电源策略。日期是现场实施日期，本次整理没有改动镜像或服务。

<a id="windows"></a>
## Windows 显示与编码

Windows VM100 使用 GTX 965M 直通、Sunshine NVENC 和 VDD 虚拟显示器。只保留 VDD 为活动主屏，目标分辨率 2560×1440、显示刷新率 60Hz，Moonlight 请求 45FPS；11-03 实际渲染约 43～44FPS。提高请求到 60FPS、换队列/VSync/nearest 采样没有形成稳定 2K60 收益，精确尺寸采样实验未采用。

GPU 历史上曾出现 Code43，11-02 的 D3cold、ROM 副本、快速启动等实验没有可靠修复，均回退；之后运维修复，11-03 实际 NVENC、11-05 冷启动错误码 0 已验证。故障排查要同时看 `nvidia-smi`、设备错误码、Sunshine 的实际 `h264_nvenc` 和真实会话编码占用，不能只看显卡名称。

工具入口：[set-2k-display.ps1](../tools/set-2k-display.ps1)、[set-fixed-pci.py](../tools/set-fixed-pci.py)。历史 [2K45 证据](evidence/2k60-20261103/)、[单屏证据](evidence/single-display-20261103/)保留。当前 Windows 使用视频内的单个远程光标；11-03 的独立光标受控原型已收尾，没有进入产品默认路径。

<a id="linux"></a>
## Ubuntu 与麒麟画质、捕获和延迟

两种 Linux 已接入真实 2560×1440、H.264、30Mbps、盒子 RKMPP 硬解，并按主机处理 limited 色彩范围协商；Ubuntu 光标恢复 Adwaita/24px 和默认加速，保留关闭动画。不要把“2K 请求参数”视为服务端已经真实输出 2K，要同时核对 XRandR、捕获日志及截图。

| 系统 | 保留的调整 | 边界 |
| --- | --- | --- |
| Ubuntu VM102 | cpu=host、virtio-gl、原生光标；曾验证 KMS + 原生光标与 45FPS | 原服务在 11-06 直通失败回退后为 X11/software；原生光标租约使用的捕获路径需另查配置 |
| 麒麟 VM101 | std VGA 64MB、2 vCPU、真实 2K/30FPS；Sunshine 启动后暂停 UKUI/KWin 合成器 | 11-06 确认合成器 active=false；动态基准约 23FPS，对照开启约 19FPS，仍是 CPU 编码 |

Ubuntu 的可比较历史数据来自 11-05 同场景合成注入：

| 场景 | KMS 45FPS | X11 45FPS |
| --- | --- | --- |
| 长按框选回显 P50/P95 | 约 196/247ms | 约 250/312ms |
| 视频中可见新编号更新 | 16.0 次/秒 | 10.6 次/秒 |

同轮实际 GTK 按钮回显约 304/378ms、masked 输入约 165/182ms；没有将合成提交冒充真实业务登录成功。这些数值不包含物理 USB 与面板扫描，也不等于光标移动延迟。原始结果见 [Ubuntu 深度调优](evidence/ubuntu-deep-latency-20261105/)。

11-06 的两项失败实验都已撤回：

- **Intel 核显直通/VAAPI**：Ubuntu 识别 i915 与编码入口，但虚拟显示捕获到编码链路不稳定，出现 KMS monitor 阻塞和 launch 超时；已恢复 VM102 的 virtio-gl、无 hostpci0、普通 Sunshine X11/software。详见[试验最终状态](evidence/ubuntu-latency-plan-20261106/intel-vaapi-trial-final.json)。
- **虚拟显存 64MB**：短样本收流约 27.49FPS、主机处理平均 83.4ms，恢复默认后约 32.64FPS/60.8ms，未保留 64MB 参数。见 [VRAM 对照](evidence/ubuntu-vram-20261106/)。

VirGL 不等于可用的硬件编码。增加编码线程、虚拟显存或修改鼠标速度不能消除 CPU 捕获/编码瓶颈；后续路线见[未来计划](roadmap.md#performance)。

<a id="cursor"></a>
## 输入顺序与 Linux 原生独立光标

客户端输入补丁保持绝对移动与点击边界顺序，优先处理输入，最新帧队列避免堆积旧视频；这是输入正确性和排队优化，不能承诺零延迟。11-06 的 [0006 补丁](../terminal/moonlight/patches/0006-vdi-release-stuck-mouse-buttons.patch) 在 SDL 失焦与退出时释放左、中、右、X1、X2 五个按钮，修复丢失 BUTTONUP 后点击/拖拽卡住的问题。

Linux 原生光标实现见 [terminal/native-cursor](../terminal/native-cursor/README.md) 和 Moonlight 0005。通过受限 SSH 通道同步实际形状、热点、显隐及必要位置校正，本地指针移动不等待视频；连接前启用无光标捕获，整次会话结束后恢复普通服务，避免视频内与本地同时出现光标。

当前约束：单座席 X11、单屏 2560×1440、绝对鼠标，形状最大 128×128。客户端状态超时约 2 秒，主机租约 4 秒；未知形状、分辨率变化或连接故障时结束会话并恢复服务，不做未经确认的运行中切换。客户端和 Linux profile 的 SHA 必须匹配，升级/回退成对处理。

已验证两系统 7 类形状/热点/显隐、28 次编号点击、故障清理及 Ubuntu 约 6 分钟状态读取；短时暂停 1.1 秒可恢复，持续失效会退出。完整真实失焦、长期稳定、多屏/缩放/Wayland/相对鼠标尚未全面验收。11-09 进入/退出回归沿用原生光标。证据见 [native-cursor](evidence/native-cursor-20261105/)；当前二进制校验值见[终端说明](terminal-guide.md#build)。

<a id="power"></a>
## 客体桌面“关机/重启”按钮

11-04 已按当前客户账户部署持久策略，独立于盒子键盘过滤。目标是禁止客户从桌面图形入口关机、重启、睡眠和休眠，保留管理员与 PVE 维护能力。

| 系统/账户 | 策略与首次备份 |
| --- | --- |
| Windows VM100 / test | Explorer `NoClose=1`；`C:\ProgramData\VDI\power-policy\original.clixml` |
| 麒麟 VM101 / test1 | polkit `.pkla` + D-Bus 用户级电源方法拒绝；`/var/lib/vdi/power-policy/` |
| Ubuntu VM102 / test2 | polkit `.rules` + D-Bus 用户级电源方法拒绝；同上 |

Linux 仅用 polkit 不够：当时实际图形进程的基础 reboot 授权仍有残留，因此额外使用 `/etc/dbus-1/system.d/zz-vdi-desktop-power.conf` 拒绝该用户的 login1 电源方法与 Can* 查询。麒麟 polkit 文件为 `/etc/polkit-1/localauthority/90-mandatory.d/99-vdi-power.pkla`，Ubuntu 为 `/etc/polkit-1/rules.d/00-vdi-power.rules`。

Windows 交互 Shell 有效策略读回为 1；Linux 八类方法使用无效签名安全探测，均 Access denied，七类 Can* 查询拒绝。未发送真实关机请求，未逐项目视验收菜单刷新，也未完成重启后的全流程验收。策略不限制管理员绕过，不改变注销/锁屏和更新行为。新账户需重新应用。

管理员部署/查询/回退入口为 [deploy-guest-power-policy.py](../tools/deploy-guest-power-policy.py)，子工具为 [Windows](../tools/set-guest-power-policy.ps1) 与 [Linux](../tools/set-guest-power-policy.py)。`apply` 可替换成 `query` 或 `restore`，重复应用不覆盖首次备份。例：

```powershell
python tools/deploy-guest-power-policy.py query --vm 100
python tools/deploy-guest-power-policy.py query --vm 101 --user test1
python tools/deploy-guest-power-policy.py query --vm 102 --user test2
```

证据见 [guest-power-policy](evidence/guest-power-policy-20261104/)。盒子断电仅断开客户端，不等于云端 VM 随之关机；物理开关联动尚未实现。

<a id="usb"></a>
## U 盘透传与 Windows 安全删除菜单

当前 POC 路径为盒子物理 USB → Rust `vdi-usb-monitor` → 私有 usbredirect → 回环 SSH 隧道 → QEMU usb-redir → Windows 自带 USBSTOR。显示仍走 Moonlight，盒子不保存 PVE 凭据。

已由固定 Kingston 身份扩展为“任意纯 USB Mass Storage”：所有接口都必须为 class 08，键鼠、Hub、混合 HID 设备拒绝；发现本地挂载、holder、swap 占用时等待，不强制卸载。一个盒子/VM 同时导出一个存储设备。udev 事件即时唤醒，500ms 扫描兜底，必须等接口枚举完整后再判断设备。

已经验收 Kingston 真实盘符、1MiB 随机文件往返 SHA 一致与一次实物拔插；另一只 SanDisk 双分区 Healthy；用户确认不再自动开两个文件夹、提示菜单响应改善。私有 usbredir 0.15.0 避免旧 exporter 持续占约一个 CPU 核的问题，观察降至约 1%。没有完成多盘大文件吞吐、异常断网/掉电、VM/PVE 重启恢复及多用户隔离验收。

管理员部署入口为 [deploy-usb-device-poc.py](../tools/deploy-usb-device-poc.py) 的 `--any-storage`；盒子策略在 `/etc/vdi-usb-monitor/device.env`，服务 `vdi-usb-monitor.service`，PVE 隧道 `vdi-usb-tunnel-100.service`。QMP watcher 的源码能力、当时是否现场安装、后续 monitor 交接版本须分别确认；`vdi-monitor` 已记录保留端点的 `--keep-attached` 版本，但不能反推任意运行环境都有同一部署。

11-05 为 Windows 固定 PCI 设备关闭 Q35 的 ACPI PCI/SHPC/PCIe root-port 热插拔，正常关机再启动后四项能力从 6→0，GPU/网络/系统盘正常。USB 设备级热插拔保留，内部 PCI 增删改为关机维护。此配置不能只在 Windows 点重启生效，必须让 QEMU 完整退出再启动。托盘实际外观与真实 U 盘插入/安全弹出仍待组合验收，不能承诺隐藏全部虚拟化标识。

回退先在 Windows 安全弹出并物理拔盘，再停止导出服务；只还原本功能配置、公钥行和二进制，不整份覆盖后续更新。精确备份路径及步骤见[历史归档](archive/README.md)，测试见 [USB 原型](evidence/usb-device-20261103/) 和 [固定 PCI](evidence/fixed-pci-20261105/)。