# 高级版日志与诊断中心

日期：2026-11-11。已部署到真实控制台 `http://127.0.0.1:5182`，入口为“高级版 → 日志与诊断”。

## 已实现

- 按终端设备或云桌面的唯一 ID 关联执行任务、桌面会话、监控告警、操作审计和已回传的终端日志片段。同名设备不会串记录。
- 支持时间范围、记录来源、数据库分页、来源数量及详情展开；最长查询 7 天，默认近 24 小时。修改筛选后清除旧结果，重新查询后才能导出。
- 设备、桌面及关联任务详情可直接进入指定对象诊断。设备选择显示 SN，桌面选择显示 VMID。
- 导出 ZIP 包含 `diagnostics.json` 和 `README.txt`，使用已查询的对象、时间及来源，包含全部匹配页。超过 2000 条时拒绝并提示缩小范围，不静默截断；导出记录审计。
- 在线设备可在确认后提交一次日志采集，显示真实任务回执；已有未完成或结果未知的设备命令时阻止再提交。失败重试复用幂等标识，提交成功与设备执行成功分开显示。
- 超级管理员、运维人员可使用；只读角色隐藏入口，直接页面访问被拦截，接口返回 403。界面模式不改变角色权限。
- 深浅主题和 390px 窄屏布局；日志以纯文本呈现。导出字段采用白名单，并遮盖常见凭据格式。

## 数据含义

对象卡片是查询时的当前快照，不代表所选历史时间点。任务提交条目展示查询时状态，另列最后一次更新事件，不伪造完整的任务状态变更历史。会话按预留、连接、结束分别列事件，因此查询范围之前开始但范围内结束的会话也能查到。

设备视角按终端 ID 及显卡准备任务的 `device:<ID>` 关联；桌面视角按桌面 ID 关联，并包含所属节点告警。只按名称保存、缺少稳定关联标识的旧审计不推测归属。不根据设备当前绑定推断历史日志属于哪台桌面，所以终端日志仅在设备视角出现。

日志来自设备已回传的片段，当前 Qt Agent 读取会话错误日志尾部及版本、启动标识、运行时长和 kiosk 状态。没有记录可能是尚未采集、未上报或超出留存；不代表没有故障。本轮没有实现持续实时日志推送、服务端全量日志归档或自动采集 VM 客体日志。常见凭据遮盖不保证消除所有自由文本中的自定义敏感信息。

## 测试与真实验收

- 后端 6 项诊断专项集成测试通过，覆盖同名隔离、旧会话结束时间、跨来源分页、权限/参数、ZIP 完整性/限额、白名单与凭据遮盖；使用一次性 PostgreSQL，未对业务库运行集成测试。
- Go 全量 `go test ./... -count=1`、`go vet ./...` 通过；全量测试之后仅增加能力标识及调整导出说明，最终 API 生产镜像构建通过。
- 前端 TypeScript、ESLint、6 项单元测试及生产 Docker 构建通过。9 项诊断页面测试、12 项两版界面测试、4 项 GPU 核对回归共 25 项通过；修正截图动画后另复验 1 项视觉用例。
- 真实 API 对 1 台设备和 3 台桌面核验近 24 小时查询、全部分页、5 类来源筛选与 ZIP 内容一致；临时运维账号可读/导出，临时只读账号 403，未登录 401。临时账号和会话已清理，保留审计。
- 真实浏览器核验：通用版 5 个入口、超级管理员高级版 14 个入口、设备/桌面深链、第二页、详情、筛选失效、实际下载、只读角色限制；1440/390 宽度及深浅主题通过，无脚本错误或失败 API 响应。
- 进一步通过实际页面确认并提交 **1 次 `collect-logs`**，`qt-platform/0.4.0` 真实盒子成功回执，页面展示日志并下载诊断包。导出中有 1 条对应日志，日志尾部 11981 个字符，内容保留在本机私有目录；公共证据仅保存元数据和收起日志后的截图。
- 采集完成后，原管理员密码/角色、桌面连接配置、用户/授权、设备身份/配置版本及告警规则仍与更新前一致。任务数 63→64，唯一新增任务为此次成功日志采集；快照任务数不变。未发送 VM 电源、GPU 切换、会话重置或终端重启。

证据：[真实接口核验](evidence/cloud-diagnostics-20261111/live-verification.json)、[真实页面核验](evidence/cloud-diagnostics-20261111/browser-verification.json)、[实际采集回执](evidence/cloud-diagnostics-20261111/collection-verification.json)、[采集后的状态核对](evidence/cloud-diagnostics-20261111/collection-state-verification.json)、[页面截图](evidence/cloud-diagnostics-20261111/live-diagnostics-light.png)。

## 发布与回退

从上一轮已部署源码 `.local/editions-review/release` 生成隔离发布目录，只叠加本轮 17 个文件；基线 API 重建二进制 SHA256 与更新前实际运行二进制一致。没有包含其他会话正在修改的终端/串流代码。

更新前备份：`.local/live/backups/before-diagnostics-20261111-174813.dump`，已校验归档目录。旧 API/控制台镜像均保留标签 `before-diagnostics-20261111-174813`。此次只更新 API、控制台，没有数据库结构变更，未重启 PostgreSQL，业务库 `fsync=on`。

需要回退时使用该标签的两套镜像和本轮保留的 compose 配置，仅重建 API/控制台；不要恢复整个业务库或使用 MFA 之前的 API。镜像身份与文件校验见[发布记录](evidence/cloud-diagnostics-20261111/deployment.json)和[文件清单](evidence/cloud-diagnostics-20261111/manifest.json)。