vGPU 重新分区后云主机启动报“mediated device not found”

适用场景

• 产品：ZCF
• 版本：4.x、5.x（适用于支持物理 GPU / vGPU 的 KVM 主机）
• 组件：Zstack Cloud
• 触发条件：一台此前已经绑定 vGPU 的云主机，在底层物理 GPU 被重新分区（vgpu re-cut）后无法启动；该 vGPU UUID 已不在该主机上。

问题现象

• 云主机启动任务失败。
• 管理节点日志中出现类似如下的堆栈：

failed to start vm[uuid:cb1334fe78f6408693b5ac3fac733b49 name:440-4] on kvm host[uuid:f8333e4b8c1c4211a3982fbbbacb45b5, ip:xxx.xxx.33.102], because Traceback (most recent call last):
  File "/var/lib/zstack/virtualenv/kvm/lib/python2.7/site-packages/kvmagent/plugins/vm_plugin.py", line 5583, in start_vm
    self._start_vm(cmd)
  File "/var/lib/zstack/virtualenv/kvm/lib/python2.7/site-packages/kvmagent/plugins/vm_plugin.py", line 5499, in _start_vm
    'unable to start vm[uuid:%s, name:%s], libvirt error: %s' % (cmd.vmInstanceUuid, cmd.vmName, str(e)))
KvmError: unable to start vm[uuid:cb1334fe78f6408693b5ac3fac733b49, name:440-4], libvirt error: device not found: mediated device '23cac439-232a-406c-8525-43ee08f55e36' not found

• 在主机内部，日志中引用的 mediated device UUID 23cac439-232a-406c-8525-43ee08f55e36 已经不再列出。

判断方法

1. 在管理节点 UI 中查看失败的任务，并从日志中捕获 libvirt 错误。
2. 在 KVM 主机上列出物理 GPU 当前可用的 mediated device（mdev 类型），确认错误信息中报告的 UUID 已不存在。
3. 确认 vGPU UUID 的变化来源于近期一次 GPU 重新分区操作。

风险与回滚

• 风险：卸载并挂载不同的 vGPU 会改变云主机内看到的设备标识，依赖稳定设备 ID 的 GPU 直通业务可能需要重新绑定授权 License。
• 回滚：停止云主机，重新挂载原 vGPU（如果其已恢复），然后重启云主机。

解决方案

1. 执行前准备

• 从错误信息中识别受影响的云主机 UUID 与失效的 vGPU UUID（示例中为 23cac439-232a-406c-8525-43ee08f55e36）。
• 确认同一主机上存在满足所需 profile 的健康 vGPU。

2. 处理步骤

1. 在管理节点 UI 上，将失效的 vGPU 23cac439-232a-406c-8525-43ee08f55e36 从云主机上卸载（detach）。
2. 为云主机挂载一块满足所需 profile 的健康 vGPU。
3. 启动云主机。云主机应能够使用新的 vGPU 绑定成功启动。

验证方法

• 云主机达到 Running（运行中）状态。
• 在云主机内部，GPU 设备可见，并且依赖该 GPU 的业务可正常运行。

原因说明

云主机仍在引用主机上已经不存在的 vGPU UUID。这通常发生在物理 GPU 被重新分区之后（例如，vGPU 被重新切分为不同的 profile 或容量），而云主机的绑定未被刷新。

补充说明

• 源案例中提到当时主存储使用率已超过 90%；建议提前扩容主存储容量，避免存储压力叠加导致启动失败。