# 终端系统指标与历史（2026-11-10）

本轮补齐 Qt 终端的真实系统指标采集、设备鉴权上传、PostgreSQL 历史保存，以及控制台详情中的数值和趋势。串流 FPS、RTT 和 GPU 健康数据仍未采集；目标帧率、HTTP 耗时或 ping 不会被当作实际串流指标。

## 页面与采集

入口：`http://127.0.0.1:5182/terminals` → 终端详情 → **查看运行指标**。三个管理角色均可只读查看；面板打开后每 30 秒读取，关闭后停止；支持手动刷新和最近 1 小时 / 24 小时 / 7 天。失败时显示错误并允许重试，切换设备或时间范围时旧响应不会覆盖新响应。

| 指标 | 数据来源与含义 |
| --- | --- |
| CPU 使用率 | `/proc/stat` 聚合 CPU 相邻心跳差分，idle 与 iowait 计为空闲；不重复累加 guest。第一次采样、读失败、计数倒退或无差分返回空值 |
| 内存使用率 | `/proc/meminfo` 的 `100 × (MemTotal − MemAvailable) / MemTotal`。缺少 MemAvailable 不回退为把缓存全部计入已用 |
| SoC 温度 | sysfs 中类型为 `soc-thermal` 的 thermal zone，毫摄氏度转摄氏度。不将任意 thermal zone 命名为 CPU/GPU 温度 |
| 运行时长 | `/proc/uptime` 第一项。未采到有效值显示“未采集” |

Agent 版本为 `qt-platform/0.4.0`。采集只读取系统文件，不启动额外后台守护、不改变 Moonlight 参数和性能叠图。采样频率沿用已下发的心跳策略，现场为 30 秒。

## 服务与数据

- `POST /api/v1/terminal/heartbeat` 新增可选 `systemMetrics`，包含可空的 `cpuPercent`、`memoryPercent`、`socTemperatureC`、`uptimeSeconds`。
- 校验范围依次为 0～100%、0～100%、−40～150°C、0～3155760000 秒；不接受非数值或超限值。
- 使用设备令牌对应的终端身份，在已有设备行锁事务内写心跳和指标，客户端不能指定另一个终端 ID。旧 Agent 未带系统指标时兼容接收，并清空当前指标，显示升级提示。
- 新表 `terminal_metrics_current` 保存最新状态，`terminal_metric_samples` 保存历史；单终端历史至多每 10 秒一条，重复心跳仍更新当前状态。历史与当前表均外键关联设备；不修改 `terminals` 的原有字段结构。
- `GET /api/v1/terminals/{id}/metrics?from=...&to=...` 返回当前值、在线/新鲜度、最近采样时间和聚合历史。未知终端 404，无管理登录 401。单次查询最长 7 天，6 小时以内按 60 秒、24 小时以内按 300 秒、更长按 1800 秒聚合。
- CPU/内存/温度历史为桶内均值，运行时长为桶内最大值。显式返回空桶，页面在缺失处断线；粗粒度聚合可能合并同一桶内的短暂中断，不表示整桶内持续在线。
- 设备停用、心跳或指标超过 90 秒，当前数值返回空值；历史仍可查。设备重新激活会清除旧身份的当前指标，保留历史。
- 现有观测循环定期清理 30 天以前的历史。当前使用 PostgreSQL；VictoriaMetrics 和指标告警规则尚未接入。

API 契约由 `tools/generate-platform-openapi.mjs` 生成，并同步到控制台类型。

## 验证与部署

Go 全量测试、`go vet`、前端 lint / 类型检查 / 单元测试 / 生产构建、57 项页面回归和盒子 6 项 CTest 均通过。真实深浅主题、390px 与 7 天聚合检查通过，无脚本异常或失败响应。

现场验收中连续采样真实入库，CPU 约 2.5%、内存约 10.2%、SoC 温度约 45.5°C（数值会变化）。独立读取 `/proc` 和 thermal 核对内存、温度、时长；CPU 因取样间隔不同只核对合法范围，差分算法由固定计数器测试验证。原业务身份、授权、密码哈希指纹、设备配置文件和三台 VM 的配置 digest 均一致，三台 VM 保持运行。

测试覆盖 Qt 文件读取、差分/重置/缺失、传感器来源和单位；后端的身份隔离、数值校验、旧 Agent、在线过期、身份重置、采样限速、聚合空桶、查询范围和留存；页面的按需加载、零值、缺失、离线、重试、窄屏和响应竞态。

最终现场验收及截图见 [证据目录](evidence/cloud-terminal-metrics-20261110/)。更新时备份数据库和旧镜像，盒子单独备份旧二进制，仅在无活动串流时替换 kiosk 并由原看门狗恢复；不重启 LightDM、系统或虚拟机，不更改设备令牌、密码、桌面参数或授权。

数据库备份：`.local/live/backups/before-terminal-metrics-20261110-173343.dump`；API 与 console 旧镜像标签：`before-terminal-metrics-20261110-173343`。回退可恢复旧镜像和旧 kiosk 二进制，新指标表可保留，旧版本不依赖它们。