# GPU 清单与配置引用（2026-11-10）

已部署真实控制台 [GPU 资源](http://127.0.0.1:5182/gpus)，侧栏入口为「GPU 资源」。沿用现有深浅主题和图标，三个管理员角色均可查看。

## 当前能力

- 选择计算节点，读取真实显示控制器类 PCI 设备的厂商、型号、PCI 地址、厂商/设备 ID 和 IOMMU 分组；分组 0 正常显示，无分组报告显示「未报告」。
- 搜索显卡、PCI 地址、虚拟机名称/VMID 和纳管桌面名称，按配置引用状态筛选。
- 检查该节点所有当前 PVE 凭据可见的 QEMU VM，包括未纳管 VM、关机 VM 和模板；详情区分当前配置、待应用配置与待移除项。
- 解析 `hostpciN` 的短地址、完整域地址、整槽所有功能、分号多地址、PCI 映射和介导设备标记；显示引用 VM、配置槽位、平台纳管关系和映射来源。
- 展示已检查/可见 VM 数、读取时间与检查失败原因，超过 90 秒提醒刷新。手动刷新重新读取，页脚明确说明按需读取，无后台高频 GPU 采集。

状态含义：

| 状态 | 含义 |
| --- | --- |
| 有配置引用 | 查到一台 VM 的当前或待应用配置引用 |
| 多 VM 引用 | 查到多台 VM 的配置引用，需进一步核查；不直接判定运行冲突，介导设备也可能有合法共享 |
| 未发现配置引用 | 本次 QEMU 配置检查无异常且没有查到引用，不表示设备可分配 |
| 待核查 | 没有查到引用，但检查范围不完整，例如部分 VM 不可读、映射不可见或有自定义参数 |

## 接口和边界

新增管理员鉴权后的 `GET /api/v1/resources/gpus?node=<节点>`，返回节点、读取时间、检查完整性、可见/已检查 VM 数、显卡及逐条引用、检查问题；没有 GPU 写接口。请求节点必须在实时 PVE 资源清单中可见。

读取 PVE `/cluster/resources`、`/nodes/{node}/hardware/pci?verbose=1`、`/nodes/{node}/qemu/{vmid}/pending` 和根路径权限；按需读取 `/cluster/mapping/pci`。PCI 清单需要根路径 `Sys.Audit` 等 PVE 允许的审计权限，判断全局 VM 可见范围检查根路径 `VM.Audit`；映射仍受 `Mapping.Audit/Use/Modify` 可见性约束。平台不自动增加权限。

每节点每次最多检查 200 台 VM，以 4 个并发读取任务、12 秒总预算控制请求；超出范围、读取失败或映射候选不唯一时标明不完整。自定义 `args` / `hookscript` 的额外引用不解析，不将其原文输出至接口。前端请求失败显示明确错误，旧清单清除，避免把旧记录当作本次结果。

本轮不查询宿主驱动实际绑定、运行中 QEMU 的实际设备、LXC 设备挂载、GPU 温度/利用率/显存，也不确认硬件健康、IOMMU 隔离可用性或硬编能力。多次 PVE 读取不是原子状态快照。配置引用、运行状态和可分配性是不同信息；绑定/解绑、独占锁、GPU broker 和健康采集仍待实现。

此功能无数据库表或字段迁移，不创建任务、审计或显卡分配记录。API 契约见 [OpenAPI](openapi/platform.v1.json)。

接口语义参考 Proxmox 官方 [PCI API 源码](https://github.com/proxmox/pve-manager/blob/master/PVE/API2/Hardware/PCI.pm)、[映射 API 源码](https://github.com/proxmox/pve-manager/blob/master/PVE/API2/Cluster/Mapping/PCI.pm) 和 [PCI 直通文档](https://github.com/proxmox/pve-docs/blob/master/qm-pci-passthrough.adoc)。

## 验证与部署

- 本地 PVE HTTP 测试服务和独立临时 PostgreSQL 覆盖只读请求、管理员鉴权及只读角色访问、输入校验、PCI 功能/域地址、映射解析、待应用与待移除、关机 VM 引用、未纳管 VM、多引用、权限缺失、配置失败及原始参数不泄露。Go 全量测试和 `go vet` 通过。
- ESLint、TypeScript、3 项前端单元测试和生产构建通过；新增 6 项 GPU 浏览器测试，连同已有用例共 51/51 通过。覆盖错误重试、过期、空态、只读角色、搜索、详情与 390px 浅色窄屏；页脚刷新说明修正后，GPU 6 项用例再次通过。
- API/控制台镜像已更新到 5182，保留原 PostgreSQL 容器和业务卷。真实浏览器深浅主题与 390px 页面检查通过，无脚本错误或失败响应。
- 现场 `starhe` 读取 2 块显卡、检查 3 台 VM：Intel `0000:00:02.0` / IOMMU 0；NVIDIA GTX 965M `0000:01:00.0` / IOMMU 2，当前配置引用为 VM100 `win10-test` / 已纳管 Windows 10。
- VM100 有自定义参数，因此页面说明检查未完整，Intel 显示「待核查」，没有标成可分配。没有改动显卡直通或启动任何 VM 电源/快照/磁盘操作。
- 三台 VM 仍运行，配置摘要和原管理员密码哈希指纹、桌面配置、授权、终端身份与更新前一致；盒子心跳正常，任务及快照数量未增加。

更新前数据库备份：私有 `.local/live/backups/before-gpu-inventory-20261110-170206.dump`；已验证备份目录可读。旧 API/控制台镜像标签均为 `before-gpu-inventory-20261110-170206`。本轮无数据库结构变更，可在核实版本配套后回退这两个应用镜像；无须因本功能删除或重建数据库。备份恢复演练尚未执行。

证据：[51 项页面回归](evidence/cloud-gpu-inventory-20261110/playwright-report.json)、[真实接口与业务基线核查](evidence/cloud-gpu-inventory-20261110/live-verification.json)、[真实页面核查](evidence/cloud-gpu-inventory-20261110/browser-verification.json)、[现场清单](evidence/cloud-gpu-inventory-20261110/live-gpu-inventory-dark.png)、[现场详情](evidence/cloud-gpu-inventory-20261110/live-gpu-detail-light.png)、[现场窄屏](evidence/cloud-gpu-inventory-20261110/live-gpu-detail-mobile.png)。`fixture-` 图片使用测试数据，不代表现场存在测试显卡或映射。

专用 VM、Windows 副本、存储准备和真实快照内容恢复仍按用户要求暂缓，后续统一见 [计划](roadmap.md)。