# 运维说明

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

<a id="monitor"></a>
## 日常监控看哪里

| 事项 | 位置 | 保存范围 |
| --- | --- | --- |
| 实时监控页面 | 联调环境 `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/](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`；该命令只停止记录，不删除已有数据。本次整理未执行。具体初次部署与回退细节在[归档](archive/README.md)的 `overnight-box-observation-20261104.md` 中。

<a id="diagnosis"></a>
## 常见问题的排查顺序

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

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

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

```bash
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](../terminal/kiosk-shell/tests/verify_entry_surface.py) 与 [verify_return_surface.py](../terminal/kiosk-shell/tests/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-monitor/docs/运维说明与已知限制.md)。

## 备份与回退原则

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