45 lines
5.5 KiB
Markdown
45 lines
5.5 KiB
Markdown
# 桌面批量电源操作（2026-11-10）
|
||
|
||
已部署本机真实控制台 [5182](http://127.0.0.1:5182/desktops)，入口为「桌面管理」。勾选卡片或列表中的桌面，选择「批量开机 / 批量关机 / 批量重启」，先逐台预检，再确认提交；「批量记录」查看最近 100 个批次及逐台结果。跨页保留选择，每批最多 50 台。超级管理员和运维可操作，只读角色可查看历史。
|
||
|
||
## 执行与保护
|
||
|
||
- 预检读取真实 PVE 配置、电源与 `VM.PowerMgmt` 权限；不存在、模板、锁定、状态不适用、活动会话、维护任务或原结果未确认的桌面逐台跳过。批量关机使用正常 shutdown，重启使用 reboot。
|
||
- 预检结果签名并绑定当前账号、登录会话、动作和所选桌面，有效 5 分钟。提交时再次检查，只允许预检批准且标识/电源状态一致的桌面进入队列；原先不可用的目标不会后来自动加入。
|
||
- 提交必须携带 `Idempotency-Key`。重复相同请求返回原批次，参数变化返回冲突；确认取消不创建批次或任务。所有跳过项及原因也保留在批次中。
|
||
- 执行前再次读取状态和权限，成功需确认原 PVE UPID 完成且实际电源状态符合预期；开机完成不表示 Sunshine 已就绪。页面区分已提交、执行中、成功、失败、未确认和跳过。
|
||
- 明确的 PVE 4xx 拒绝记为失败；发送后的通信异常、任务失败或缺少 UPID 保守记为未确认。重启恢复只查询已记录的原任务，不自动重发。未确认阻止后续桌面修改和新连接。
|
||
- 对有原 UPID 且最终任务成功的未确认结果，可在批次或任务页「核对电源结果」。该操作只读取 PVE 并更新平台记录，不重新下发；缺少 UPID、PVE 失败或实际状态不符仍须管理员核查，当前无强制解除隔离入口。
|
||
- 电源、规格、快照共用每桌面活动任务约束。批量与克隆/规格/快照共用一次一个的长任务执行通道，普通命令继续处理；排队超过 2 小时且尚未发送的任务失败，执行中超过恢复期限按原阶段保守处理。
|
||
|
||
外部直接在 PVE 操作 VM 不受平台行锁约束，预检与发送之间仍可能发生变化；平台会核对任务和最终状态，不承诺跨系统原子操作。当前只支持单个队列运行者，没有批量发放、批量规格修改或定时电源策略。
|
||
|
||
## 接口与持久化
|
||
|
||
路径均位于 `/api/v1`：
|
||
|
||
| 方法 | 路径 | 用途 |
|
||
| --- | --- | --- |
|
||
| POST | `/desktop-batches/check` | 只读预检，返回逐台原因及签名凭证 |
|
||
| POST | `/desktop-batches` | 确认后持久化批次与子任务，返回 202 |
|
||
| GET | `/desktop-batches` | 最近 100 批分页列表 |
|
||
| GET | `/desktop-batches/{id}` | 批次汇总、每台任务或跳过原因 |
|
||
| POST | `/tasks/{id}/batch-power-reconcile` | 核对原 PVE 任务及实际状态 |
|
||
|
||
新增 `power_batches`、`power_batch_items` 和覆盖 `batch-desktop` 的活动任务唯一索引；子任务与审计同事务写入，启动幂等迁移，不增加原业务表字段。API 契约见 [OpenAPI](openapi/platform.v1.json)。
|
||
|
||
## 验证与现场边界
|
||
|
||
- 独立临时 PostgreSQL 与本地 PVE HTTP 测试服务验证三种电源动作、逐台跳过、角色与签名绑定、幂等并发、提交/执行复查、活动会话与维护互斥、网络未知、重启不重发、过期及单连接池核对。Go 全量测试和 `go vet` 通过。
|
||
- 前端 ESLint、TypeScript、3 项单元测试和生产构建通过；8 项新增浏览器用例及 37 项已有回归全部通过，共 45/45，覆盖深浅主题、390px 窄屏、跨页选择、取消、重复提交和只读权限。接口全部拦截，不操作现场 VM。
|
||
- API/控制台镜像已更新，业务 PostgreSQL 容器和卷保留。现场三台运行中的桌面：批量开机预检全部跳过，关机/重启预检各 3 台可执行。真实浏览器打开确认后取消，空批次历史验证通过；没有提交批次或执行 VM 电源操作。
|
||
- 核查时 VM100/101/102 均运行，盒子心跳正常；原管理员及密码哈希指纹、桌面连接配置、用户授权与终端身份和更新前一致。批次数与批量任务数均为 0。真实批量电源执行尚未做现场验收。
|
||
|
||
证据：[45 项页面回归](evidence/cloud-batch-operations-20261110/playwright-report.json)、[真实接口核查](evidence/cloud-batch-operations-20261110/live-verification.json)、[真实页面核查](evidence/cloud-batch-operations-20261110/browser-verification.json)、[现场批量预检](evidence/cloud-batch-operations-20261110/live-batch-preview-dark.png)、[现场窄屏](evidence/cloud-batch-operations-20261110/live-batch-preview-mobile.png)。`fixture-` 图片为拦截接口的测试数据，不代表现场已有对应批次或执行结果。
|
||
|
||
## 备份与后续
|
||
|
||
更新前备份为私有 `.local/live/backups/before-batch-operations-20261110-163850.dump`，已检查备份目录可读；API/控制台旧镜像标签均为 `before-batch-operations-20261110-163850`。尚未做恢复演练。回退前须评估新增批量任务；旧后端不识别新任务与隔离状态，不可带着活动或未确认批次直接回退，不删除业务卷。
|
||
|
||
用户已明确暂缓专用测试 VM、Windows 模板副本、存储准备及依赖它们的真实快照内容还原验收；本批没有创建 VM、格式化或挂载额外磁盘、修改 PVE 权限。公共池自动领取/退出还原仍未实施，后续顺序见 [计划](roadmap.md)。
|