4.7 KiB
终端系统指标与历史（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 尚未接入；终端系统指标告警已于 11-11 补齐，见规则与采样判断。
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、在线过期、身份重置、采样限速、聚合空桶、查询范围和留存；页面的按需加载、零值、缺失、离线、重试、窄屏和响应竞态。
最终现场验收及截图见 证据目录。更新时备份数据库和旧镜像，盒子单独备份旧二进制，仅在无活动串流时替换 kiosk 并由原看门狗恢复；不重启 LightDM、系统或虚拟机，不更改设备令牌、密码、桌面参数或授权。
数据库备份：.local/live/backups/before-terminal-metrics-20261110-173343.dump；API 与 console 旧镜像标签：before-terminal-metrics-20261110-173343。回退可恢复旧镜像和旧 kiosk 二进制，新指标表可保留，旧版本不依赖它们。