运维说明

本文件维护云桌面项目的排障与回退入口。监控页面、采集器和看门狗后台的维护说明以独立 vdi-monitor 项目为准。

日常监控看哪里

事项	位置	保存范围
实时监控页面	联调环境 `http://192.168.1.51:8090`	硬件、盒子状态、日志解释等；实际功能看 monitor 版本
盒子采集器	`vdi-monitor/deploy/box-sync.sh`	约每 30 秒 SSH 采集一次
监控日志解读	`vdi-monitor/source/box_metrics.py` 的 `LOG_RULES` / `diagnose()`	页面规则在监控项目维护
PVE 最新原始数据/状态	`/var/lib/vdi-monitor/box/raw.txt`、`status.txt`	最新快照，不是完整历史原始日志库
PVE 指标历史	`/var/lib/vdi-monitor/box/history.log`	约 7 天/最多约 20000 行，保存时间、健康、温度、内存、磁盘、kiosk、uptime 等指标
开发证据	本仓库 evidence/	固定测试/故障的原始材料，不能由指标历史替代

因此旧的过夜观察说明可合并，但不能因为“监控接入”就删除唯一故障日志、回退配置或停掉盒子的记录服务。指标保留期限也不是故障证据归档期限。

盒子日志和健康记录

路径/服务	用途
`/tmp/vdi-monitor.log`	kiosk 看门狗输出；重启可能丢失
`/tmp/vdi-kiosk.heartbeat`	kiosk 心跳，不是错误根因
`~/vdi-terminal/logs/*.log`	Moonlight 会话及过夜健康记录等
`~/vdi-terminal/logs/overnight-summary.txt`	中文汇总
`~/vdi-terminal/logs/overnight-health-YYYYMMDD.log`	每分钟 JSON 行，按日轮转
`~/vdi-terminal/state/overnight-state.json`	观察器持久 boot ID/计数基线
`/var/lib/vdi-observer/pstore.json`	限量只读采集的 pstore 快照
`vdi-overnight-observer.service`	盒子持久记录，与监控页面采集互补

11-04 观察器从启用时建立基线，不能把“计数 0”解释为盒子历史从未重启。用 boot ID 与单调 uptime 判断整机重启，服务重启不算整机重启；墙上时钟变化和 last 不能单独定论。

该盒子 /var/log 是 zram；journal 链接到 eMMC 的 /var/log.hdd/journal。观察器部署了 persistent journald 配置，磁盘预算 64MB、运行预算 16MB、保留 7 天、同步间隔 30 秒；观察日志保留 7 个日期，每日最多 4 个 8MB 分段。历史 41 字节的 reboot: Restarting system 是旧 pstore 基线，不是新故障证明。突然断电/硬复位可能缺少末尾日志，缺日志不能直接证明电源故障。

要停用观察器可由管理员执行 sudo systemctl disable --now vdi-overnight-observer.service；该命令只停止记录，不删除已有数据。本次整理未执行。具体初次部署与回退细节在归档的 overnight-box-observation-20261104.md 中。

常见问题的排查顺序

开机显示旧的用户名/密码页：11-10 已定位到原启动认证回调在任一失败后切到 CONFIG，且没有认证重试。新版保持选择页并退避重试；查询 .xsession-errors 中 vdi_device_auth 和 vdi_device_auth_request，分别核对重试、HTTP 状态及网络错误码。旧日志没有记录首次失败细节时，不直接认定 Wi-Fi、证书或平台停机中的某一个原因。当前平台仍在开发机 Docker，开发机/容器不可达时需要恢复服务，页面保持选择页不代表离线仍能授权连接。

开机/退出出现盒子桌面或系统 greeter：核对真实运行会话 DESKTOP_SESSION=vdi-kiosk、LightDM 配置、是否残留 mate-session/mate-panel/marco/caja，检查是否从 SSH 脱离 LightDM 拉起了 kiosk。不要仅检查磁盘默认会话或一张开机截图。
进入时左上角小窗：核对 Moonlight 0007 构建、VDI_KIOSK_STREAM=1、SDL 首次映射几何、连接遮罩，使用进入探针；只测退出不能覆盖进入阶段。
黑边/画面变矮：同时核对盒子 XRandR、Moonlight 窗口、客体捕获尺寸与显示守护；原 1920×1440 回退会让 16:9 视频上下留边。
Win+Shift+S 无反应：先检查传给 Moonlight 的系统键捕获参数，再检查 Windows 截图组件与客体收到的键；“不弹底层窗口”和“客体截图成功”是两个验收点。
指针流畅但点击/拖窗慢：区分本地光标移动与视频回显，查看实际编码器、捕获路径、主机处理延迟、网络 RTT、解码/渲染；Linux 软件编码瓶颈不能靠调鼠标速度解决。
按钮像一直按住/拖拽失效：核对 0006 失焦/退出按钮释放与当前二进制，不把输入状态残留都当作网络延迟。
Linux 启动失败/光标租约失败：检查二进制与 profile 的 SHA、远端 guard 和普通 Sunshine 恢复状态。11-09 曾因旧 SHA 拒绝，也出现普通捕获 503；这些失败没有计入通过样本。
Windows 编码突然慢：查询 GPU Code43、nvidia-smi、Sunshine 实际编码器，不能只因设备名称存在就认定 NVENC 正常。

盒子显示查询（SSH 内使用已授权的图形会话）：

systemctl --user status vdi-display-guard.service
sudo -n journalctl _SYSTEMD_USER_UNIT=vdi-display-guard.service -n 50 --no-pager
DISPLAY=:0 XAUTHORITY=/home/armbian/.Xauthority xrandr --query

会话交接探针为 verify_entry_surface.py 与 verify_return_surface.py。它们会实际连接/退出桌面，先阅读脚本参数与前置条件，在允许打断盒子当前会话时运行。

异常退出与监控自动恢复

11-04 Windows 非正常退出与 USB 隧道重启时间接近，已保留 PVE/Windows 时间线，但缺少 QEMU 退出码、栈和转储，原因尚未确认。后续在隔离 VM 或维护窗口记录 QEMU stderr、QMP 事件和退出状态，再复现隧道断开、拔盘等情景；不能把相关性写成已确认根因。

vdi-monitor 交接版本带 VM 自动恢复和 USB watcher 调整。维护前应开启该 VM 维护模式或关闭自动恢复；其“最近 90 秒 pvedaemon 日志”识别不能可靠区分所有正常停止。自动恢复成功、VM 重新 running 不等于退出原因解决。详见监控项目已知限制。

备份与回退原则

盒子功能备份集中在 ~/vdi-terminal/backups/，11-09 交接修复入口见终端说明。Linux 光标客户端和 profile SHA 必须成对恢复。
Windows 电源策略备份与 Linux /var/lib/vdi/power-policy/ 见电源策略，使用对应工具 restore。
PCI 热插拔属性回退由 set-fixed-pci.py restore 管理，要求 VM 先正常关机；不能覆盖整份 PVE 配置，也不能仅客体重启。
U 盘回退前安全弹出并拔盘，不在文件传输时重启隧道；保留其他功能和其他公钥。
不通过本次文档整理重启任何设备，不更改监控服务、系统日志保留策略或现网配置。新测试应记录真实部署版本、完整失败和最后恢复状态。

终端系统指标告警

控制台「监控告警」支持终端 CPU、内存与 SoC 温度持续阈值。数据缺失时事件保留并标注最近告警值，不应把确认或设备离线当作恢复。正常新采样会自动恢复，修改/停用规则会以“规则变更”结束原事件；外部通知尚未接入。单位、持续时间、权限和回退注意事项见功能说明。

7.6 KiB Raw Blame History Unescape Escape