56 lines
6.7 KiB
Markdown
56 lines
6.7 KiB
Markdown
# 关机快照与手动还原（2026-11-10）
|
||
|
||
本批接入真实 PVE API，补充公共池自动还原所需的基础能力。入口为「桌面管理 → 查看详情 → 快照与还原」，异步结果在「任务与审计」查看。本批不包含公共池自动领取、退出还原、自动回收、备份或迁移。
|
||
|
||
## 功能与范围
|
||
|
||
- 全部管理员角色可查看快照名称、描述、时间、父快照及内存标记；仅超级管理员可预检、创建、删除、还原和核对未知结果。
|
||
- 创建保存关机后的磁盘与配置，不保存内存；名称由字母开头，1～40 位字母、数字、下划线或短横线，不使用 current/pending。
|
||
- 删除只支持已完成且没有子快照的恢复点，不使用 PVE force 删除。
|
||
- 还原前输入当前 VMID，明确确认回退快照内磁盘和配置。数据盘若在快照内也会回退，不保证只还原系统盘。拒绝内存快照，完成后保持关机。
|
||
- 还原提交前撤销旧连接票据并将桌面标记为待初始化。管理员需核对系统身份、IP、Sunshine 服务和终端配对，再在「配置连接」确认初始化。PVE 明确拒绝还原时也保留此标记，核查后重新确认即可。
|
||
- 页面沿用现有深浅主题，窄屏保留弹窗标题和底部操作，内容区内部滚动。参数变更会使预检失效；取消二次确认不提交写入。
|
||
|
||
## 预检与执行保护
|
||
|
||
所有快照写操作都要求正常关机、无 PVE 锁、无待应用配置、无活动终端会话，且没有其他电源/规格/快照任务或未确认的维护结果。创建时检查存储快照能力；删除/还原校验选定快照版本；还原另检查磁盘布局、容量和配置目标。
|
||
|
||
本期仅支持普通虚拟磁盘（包含 EFI/TPM），跳过 CD-ROM/cloud-init。包含直通设备、宿主 args/hookscript、未使用磁盘、物理盘、共享盘或排除快照的磁盘时不允许平台快照写入；列表仍可查看。自定义 NUMA 等既有配置限制也会拦截。磁盘配置字符串的严格比较可能拒绝等价但格式不同的配置，需要在 PVE 人工核查。
|
||
|
||
读取需 VM.Audit；创建/删除需 VM.Snapshot；还原允许 VM.Snapshot 或 VM.Snapshot.Rollback。平台不修改 PVE 权限。PVE 的 start=0 无法保证含内存快照不启动，所以本期拒绝这类还原。依据 [PVE QEMU API 源码](https://raw.githubusercontent.com/proxmox/qemu-server/master/src/PVE/API2/Qemu.pm) 与 [QemuConfig 实现](https://raw.githubusercontent.com/proxmox/qemu-server/master/src/PVE/QemuConfig.pm)。
|
||
|
||
任务使用持久化请求、幂等键、桌面行锁和活动任务唯一索引。排队与执行前分别核对配置摘要及快照指纹；进入 submitting 后只发送一次，服务重启仅查询原 UPID。普通任务不等待长快照完成，当前长维护任务仍单个串行执行。
|
||
|
||
成功需要原 PVE 任务 stopped/OK 和实际状态一致；还原不能只凭配置相同就断言磁盘数据已经恢复。PVE 最终失败、网络异常或缺少 UPID 时，发送后的结果保持未确认，阻止后续电源/规格变更、新连接及重新开放初始化。任务详情的「核对快照结果」仅查原任务和实际状态，不重发修改；缺 UPID、PVE 任务失败或残留状态需在 PVE 人工核查，当前无一键清除未知保护入口。
|
||
|
||
预检无法防止管理员绕过平台直接修改 PVE：这些快照写接口没有配置 digest 条件参数，执行前检查与 PVE 接收之间仍有竞态。请避免从其他入口同时维护同一 VM。
|
||
|
||
## API 与数据
|
||
|
||
| 方法 | 路径 | 用途 |
|
||
| --- | --- | --- |
|
||
| GET | /desktops/{id}/snapshots | 列表、配置摘要、磁盘范围、限制及操作权限 |
|
||
| POST | /desktops/{id}/snapshots/check | 只读预检 |
|
||
| POST | /desktops/{id}/snapshots/actions | 幂等提交 create/delete/rollback，返回 202 任务 |
|
||
| POST | /tasks/{id}/snapshot-reconcile | 只读核对原任务 |
|
||
|
||
提交字段为 action/name/digest，创建可带 description，删除/还原需 revision，还原需 confirmVmid。拒绝未知字段和不适用参数。接口契约见 [OpenAPI](openapi/platform.v1.json)。
|
||
|
||
新增 snapshot_jobs 表，保存请求、请求散列、目标配置散列和阶段；不保存完整 PVE 配置。新增 tasks_vm_maintenance_target 唯一索引，与既有电源/规格队列互斥；启动幂等迁移，无业务表删列。
|
||
|
||
## 验证与现场限制
|
||
|
||
已部署本机控制台 http://127.0.0.1:5182。现场只读结果：三台 VM 均在运行且没有快照；Token 缺 VM.Snapshot 和 VM.Snapshot.Rollback。PVE 报告 VM101/102 支持快照，VM100 不支持；VM100 还含显卡直通和宿主 args，本期写入范围也会拒绝。此次未对真实 VM 执行关机、快照创建/删除/还原、规格修改或克隆。
|
||
|
||
Go 全量测试与 vet、ESLint、TypeScript、3 项前端单元测试及生产构建通过。37 项浏览器回归通过，其中快照 8 项；随后修复窄屏弹窗滚动，8 项快照流程重新通过。新增后端覆盖权限二选一、关机/锁/待应用/活动会话限制、磁盘与内存限制、幂等、执行前变更、未知状态不重发、只读核对、过期、维护互斥与还原票据撤销。完整测试摘要见 [记录](evidence/cloud-snapshots-20261110/test-verification.json)。
|
||
|
||
真实深浅主题和 390px 页面检查无脚本错误、失败响应或写请求；原 root 密码指纹、桌面连接、用户授权和终端身份与更新前一致，三台桌面运行、盒子心跳正常。
|
||
|
||
验证记录在 [证据目录](evidence/cloud-snapshots-20261110/)。写入链路用独立临时 PostgreSQL 和本机 PVE HTTP 测试服务验证；不能将其视为真实磁盘恢复验收。
|
||
|
||
部署和现场只读检查结果见 [真实 API 核验](evidence/cloud-snapshots-20261110/live-verification.json) 与 [页面核验](evidence/cloud-snapshots-20261110/browser-verification.json)。快照真实写入与磁盘内容还原需要后续补充 Token 权限，在无直通的专用测试 VM 验收。
|
||
|
||
页面证据：[现场深色](evidence/cloud-snapshots-20261110/live-snapshots-dark.png)、[现场窄屏](evidence/cloud-snapshots-20261110/live-snapshots-mobile.png)、[隔离数据创建表单](evidence/cloud-snapshots-20261110/fixture-snapshot-create-dark.png)、[隔离数据还原确认](evidence/cloud-snapshots-20261110/fixture-snapshot-restore-light-mobile.png)。fixture 图片不代表现场已有快照。
|
||
|
||
更新前私有备份为 .local/live/backups/before-snapshots-20261110-155834.dump，API/控制台旧镜像标签为 before-snapshots-20261110-155834。数据库备份包含业务数据，不提交仓库。本批不改终端程序。回退前需停写并评估新增任务记录及 schema 兼容性，不能只切旧镜像后丢弃维护保护；备份恢复尚未演练。
|