# 批量导入、会话历史与监控告警（2026-11-10）

本轮按原需求补齐三项真实功能，使用 Go API、PostgreSQL 与现有 Vue 控制台。入口保持 http://127.0.0.1:5182，沿用原管理员账号。没有修改盒子串流或画质参数。

## 使用入口

| 功能 | 入口 | 权限 |
| --- | --- | --- |
| 用户 CSV | 用户与授权 → 导入用户 | 超级管理员 |
| 终端 CSV | 终端管理 → 批量导入 | 超级管理员 |
| 授权 CSV | 用户与授权 → 导入授权 | 超级管理员 |
| 会话历史 | 远程会话 → 历史记录 | 所有管理员角色只读 |
| 资源曲线、告警 | 侧栏 → 监控告警 | 所有角色查看，超管/运维确认，超管编辑规则 |

## CSV 格式与提交规则

UTF-8 CSV，支持 BOM 和标准双引号字段；每批最多 200 行、512 KiB。页面可下载空白模板、上传文件或直接粘贴。先预检，逐行显示错误并可下载错误 CSV；所有行通过后才能整批提交。

```csv
username,displayName
worker01,研发人员
```

```csv
sn,name,group
BOX-NEW-001,研发终端,研发组
```

```csv
username,terminalSn,desktopIds
worker01,BOX-NEW-001,desktop-id-1;desktop-id-2
```

表头名称固定，列顺序可调整。用户和终端只新增，已存在或文件内重复的账号/SN会阻止整批导入。用户无需在 CSV 填密码，仍是用户与设备绑定模式。

授权导入仅追加桌面，不撤销原授权；空 terminalSn 保持原终端。不能抢占他人终端、给已有其他终端的用户换绑或绑定停用终端。预检后原授权发生变化时，提交返回冲突，整批不写入，需重新预检。已停用用户不会因导入授权被重新启用；既有串流不因此强制结束。

提交使用幂等请求标识，同一管理员重发相同内容不重复创建。新终端激活密钥仅在首次成功响应中返回，页面可下载并在关闭时清除；数据库和审计不保存密钥明文或源 CSV。重复请求不再返回密钥，丢失后到终端管理重新激活。

接口：`POST /api/v1/imports/preview`、`POST /api/v1/imports/commit`，后者要求 `Idempotency-Key` 和预检返回的 `previewToken`。

## 会话记录

`GET /api/v1/sessions/history` 支持关键词、状态、起止时间和分页，默认最近 24 小时、最多查询 90 天。记录保留终端、用户及桌面名称快照，后续改名不影响旧记录。

- 消费票据生成“连接中”预约，不能记作已建立视频串流。
- 客户端画面就绪事件写入首次连接时间，重复事件不重置时间；结束事件记录结束原因。
- 新连接替代旧预约、身份重置、90 秒无心跳分别记录中断原因，旧设备或旧会话事件不能结束新会话。
- 超时只结束历史片段，不自动关闭 VM、不重置终端串流。之后合法事件或已连接状态的心跳恢复时，另记“首次观测”片段。
- 升级前的历史不补造。升级中已有连接从首次观测开始，不能将观测时间当成原始连接开始时间。
- 时长从画面就绪计算；活动会话只算到最近上报，尚未就绪显示“未就绪”。结束记录保留 90 天，活动记录不删。

这仍依赖终端对实际串流状态的上报；本轮真实 API 验证使用临时设备发送合成事件，没有开启现场视频串流。

## 监控与告警

PVE 节点同步约每 30 秒保存 CPU、内存、存储使用率，使用 PostgreSQL 保留 30 天；控制台每 15 秒刷新，单次可看最近 1 小时、6 小时、24 小时或 7 天，按时间范围分桶平均。存储值来自 PVE 节点 disk/maxdisk，不表示每台客体磁盘使用率。缺失分母或离线节点保存空值；无有效采样显示空态，采样间隔过大时曲线断开，不补零。

启动幂等创建五条默认规则，已有管理员修改不被覆盖：CPU/内存/存储 90% 持续 120 秒，节点离线或采集异常 120 秒，已激活启用终端离线 180 秒。水位阈值可设 1～100%、持续 0～3600 秒；离线阈值 90～86400 秒。

评估器每 15 秒运行，多 API 实例通过事务锁避免重复事件。指标持续越线才触发，同一规则/目标只保留一条活动告警；缺少新采样不会假称恢复，采集异常由独立规则检测。节点离线状态持续计时，在线且采集正常后恢复；终端真实心跳恢复后自动解除离线告警。目标移除或停用会结束对应告警。

确认仅表示已知悉，不将告警改为恢复；保留首次确认人和时间。修改/停用规则会结束旧告警并重新计时。已恢复事件保留 90 天。

接口包括 `/api/v1/monitor/series`、`/monitor/rules`、`/monitor/alerts` 及 `/monitor/alerts/:id/acknowledge`，完整契约见 [OpenAPI](openapi/platform.v1.json)。

本轮只实现控制台内告警。VictoriaMetrics、外部邮件/Webhook 通知、终端温度及完整 FPS/RTT 历史采集仍未接入；现有独立 vdi-monitor 的诊断采集继续保留。

## 迁移与回退

新增 `import_batches`、`session_history`、`resource_samples`、`alert_rules`、`alerts`、`alert_states` 六张表及索引；默认规则只在不存在时新增，没有向原业务表添加字段。原设备令牌、root 账号、桌面参数和用户授权保留。

更新前备份 `.local/live/backups/before-operations-20261110-133019.dump`；旧 API/控制台镜像标签 `before-operations-20261110-133019`。备份含业务数据，只放私有目录。旧版本不记录新增会话/采样；如需回退，先另行备份并评估新增数据，不能直接删除业务卷。本轮未做数据库恢复演练。

验证期间 Docker/本机进程中断，恢复后 PostgreSQL 正常完成启动恢复；原业务快照核对一致，随后继续测试和更新。镜像构建首次遇到 Docker Hub 鉴权网络 EOF，重试成功。

## 验证证据

独立临时 PostgreSQL 的 Go 全量测试与 go vet、前端 ESLint/类型检查、3 项单元测试、生产构建及 27 项指定浏览器回归通过。数据库测试没有连接真实业务库；浏览器回归使用接口拦截数据，截图以 `fixture-` 标记。

真实服务验证及页面检查见 [接口核验](evidence/cloud-operations-20261110/live-verification.json)、[页面核验](evidence/cloud-operations-20261110/browser-verification.json)、[自动检查范围](evidence/cloud-operations-20261110/automated-verification.json)。临时用户/终端/授权/导入批次和测试规则/告警定向清理，操作审计保留。告警验证只调整临时终端的测试心跳时间，并通过真实设备心跳 API 验证恢复；没有修改默认规则或原设备。

真实验收结果：三类 CSV 均成功且重放未重复写入；会话预约、就绪和结束落库；真实 PVE 采样已返回有效点，历史从本次部署开始积累。临时终端离线告警触发、确认后由心跳自动恢复。清理后原业务快照一致，原盒子心跳正常，VM100/101/102 均运行。真实页面 9 张截图覆盖深浅主题与 390px 弹窗，无脚本错误、失败接口或页面检查产生的修改请求。