# PVE 接入、桌面规格与登录限流（2026-11-10）

本批已部署到本机真实服务，入口仍为 `http://127.0.0.1:5182`，使用原管理员账号。

| 功能 | 使用入口 | 当前行为 |
| --- | --- | --- |
| PVE 接入 | 系统设置 → 平台接入 → 配置 Proxmox 接入 | 检查 HTTPS、Token 与资源读取；保存后热生效，重启保留；密钥不回显，留空保留同地址同 Token ID 的原密钥 |
| CPU / 内存 | 桌面管理 → 查看详情 → 规格管理 | 读取真实规格；正常关机、无活动会话、无锁和待应用配置时，先预检再确认提交任务 |
| 虚拟磁盘扩容 | 规格管理 → 磁盘扩容 | 选择现有磁盘，填写扩容后总容量；禁止缩容，客体分区与文件系统需另行扩展 |
| 登录限流 | 登录时自动执行 | 5 分钟窗口内同账号最多 10 次、同来源 IP 最多 30 次，包含成功与失败；超限返回 429 和剩余等待秒数 |

## 接入配置

仅超级管理员可读取、检查和保存接入配置。没有数据库配置时读取原服务端环境；保存后以数据库配置为准。始终验证 TLS，可使用系统信任或输入 PEM CA 公证书，不提供忽略证书选项。保存前再次检查 `/cluster/resources` 至少能读取一个节点，检查失败保留原配置。

首次接入后，本期只支持维护相同地址的凭据和证书；不提供在线更换集群地址或多集群管理。这样可以避免同步中的旧集群资源混入新集群。计算任务排队或执行时，配置保存会被拒绝。并发编辑通过版本冲突提示重新加载，不覆盖他人的配置。

配置以 AES-GCM 加密保存在 `pve_connection`，随机 nonce，响应、错误和操作审计不记录 Token 密钥。加密密钥由服务端 `VDI_JWT_SECRET` 派生，备份数据库时必须一并安全保管对应服务端密钥。**本期没有在线密钥迁移工具，不可单独更换 JWT Secret 后继续使用原密文。** 失配会明确拒绝启动或返回配置不可用，需在维护窗口恢复匹配密钥或迁移密文。当前启动仍保留原有效环境配置与 CA 文件作为未保存时的基线。

## 规格任务

规格操作仅超级管理员可提交。CPU/内存和单块磁盘扩容分开执行。只写目标规格字段，保留 CPU 型号、GPU 直通和其他设备配置。CPU 每插槽 1～256 核，1～8 插槽，总核不超过 1024；内存 512～1048576 MiB，按 128 MiB 递增且不低于已有 balloon 最小值。带自定义 NUMA、PVE 锁或待应用配置的 VM 需先在 PVE 处理。

扩容仅支持可识别的 scsi/sata/virtio/ide 虚拟存储磁盘，不接受物理磁盘、ISO、cloud-init、EFI 或 TPM 设备。目标容量最大 65536 GiB，要求存储启用、在线且有扩容量加 1 GiB 余量。CPU、内存和磁盘分别预检 `VM.Config.CPU`、`VM.Config.Memory`、`VM.Config.Disk`；扩容另需对应存储的 `Datastore.AllocateSpace`。PVE 仍执行最终权限和资源校验。

提交和执行前都重新读取真实电源状态、配置摘要、权限和余量。相同请求标识返回原任务，参数或桌面变化不得复用标识。CPU/内存使用 PVE 配置异步任务，磁盘发送**绝对目标容量**，不发送增量扩容。收到 UPID 后等待结束，再读取实际规格确认成功。接口依据 [PVE Qemu 官方实现](https://github.com/proxmox/qemu-server/blob/master/src/PVE/API2/Qemu.pm)。

任务状态与原请求保存在 `hardware_jobs`。修改发送前先持久化提交阶段；发送后网络异常、服务中断或最终规格无法确认时显示「结果未确认」。恢复进程只查询原任务，不自动重发修改。此时后续规格、电源操作和新连接票据均被阻止；「任务与审计 → 目标任务 → 核对规格结果」只读取原 UPID 与目标规格，确认后解除保护。缺失 UPID 或实际规格未达到目标时保留未知状态，需在 PVE 人工核查并安排离线恢复，本期没有一键清除未知结果的入口。

排队过期且尚未发送的任务明确失败；已经进入提交阶段的过期任务保持未知结果。规格与电源任务共享同桌面的活动任务限制，长规格任务与克隆共用执行通道，不阻塞普通终端命令。

## 登录限流

计数保存在 PostgreSQL，多实例和重启共享。账号按去空格、小写后的值计数，账号/IP 存为 HMAC 摘要，不保存明文计数键或密码。旧计数按保留策略清理。

默认不信任转发头；`VDI_TRUSTED_PROXIES` 仅配置实际可信代理的 IP/CIDR。现场 Nginx 覆盖客户端提交的 `X-Forwarded-For`，API 信任现场容器网络。更换网关拓扑时同步调整可信代理配置，否则来源 IP 可能聚合在网关地址。该限流只作用于管理员登录，设备注册、心跳与票据鉴权继续使用原机制。

## 验收与限制

- Go 全量测试与 `go vet` 通过，数据库仅使用独立临时 `vdi_configuration_test`。本地 PVE 测试服务覆盖 CPU/内存、绝对磁盘扩容、权限/余量、运行/锁/待应用配置/摘要冲突、幂等、任务互斥、未知结果、重启不重发、只读核对和连接保护。
- 前端 lint、类型检查、3 项单元测试和生产构建通过；23 项既有管理页面回归及新增 6 项接入/规格流程通过。深浅主题、窄屏、取消确认及只读角色入口检查通过。
- 真实 PVE 连接检查、同地址原凭据加密保存、热加载、错误保存保留原配置、API 重启后继续读取均通过。临时只读账号验证第 11 次登录返回 429 与 `Retry-After`，账号和对应限流摘要已定向清理，审计保留。
- 三台现场 VM 的真实规格读取和运行中修改拒绝通过；现场 Token **仍缺少三台 VM 的 CPU/内存/磁盘配置权限**。实际规格写入成功仅在隔离测试服务验证，未在现场执行关机、重启、扩容、克隆或其他 VM 修改。
- 重启后原业务快照一致：管理员密码指纹、桌面参数、用户授权及终端身份未改变；三台 VM 运行，`qt-platform/0.3.0` 盒子心跳正常。

证据：[真实接口验收](evidence/cloud-configuration-20261110/live-verification.json)、[重启与业务快照](evidence/cloud-configuration-20261110/restart-verification.json)、[浏览器验收](evidence/cloud-configuration-20261110/browser-verification.json)、[测试汇总](evidence/cloud-configuration-20261110/test-summary.json)。页面见[真实规格](evidence/cloud-configuration-20261110/live-hardware-dark.png)与[真实接入配置](evidence/cloud-configuration-20261110/live-pve-light.png)。

## 接口与迁移

接口契约见 `docs/openapi/platform.v1.json`：`GET/PUT /settings/pve`、`POST /settings/pve/check`、`GET/POST /desktops/{id}/hardware`、`POST /desktops/{id}/hardware/check`、`POST /tasks/{id}/hardware-reconcile`。均以 `/api/v1` 为前缀。

启动新增 `pve_connection`、`hardware_jobs`、`login_limits` 与规格/电源活动任务唯一索引，不删除既有业务表或列。部署前数据库备份为私有 `.local/live/backups/before-configuration-20261110-151859.dump`，对应 API/控制台旧镜像标签为 `before-configuration-20261110-151859`。本次只重建 API/控制台容器，未重建 PostgreSQL 或删除业务卷。

回退前需再次备份并核查新增任务、接入配置与凭据变化。旧 API 使用环境中的 PVE 配置且不识别规格任务，存在排队或未知规格任务时不可直接切回旧执行器；恢复数据库快照会丢弃快照后的业务记录，当前未进行恢复演练。