问题说明

适用于排查 GPU 直通、vGPU 切割、vGPU 还原、GPU 驱动安装、NVIDIA vGPU 许可证、云主机启动失败和 GPU 资源显示异常等问题。此类问题需要从 BIOS/IOMMU、物理机内核参数、vfio 驱动、NVIDIA 驱动、mdev 数据、许可证服务器和 Guest OS 驱动共同确认。

现象

• GPU 透传到云主机后，Guest OS 识别异常或驱动安装失败。
• Windows 设备管理器提示 该设备找不到足够的资源可以使用，错误码 12。
• 物理机显示有实际不存在的 vGPU，云主机调度到该物理机后启动失败。
• vGPU 还原失败，存在两套切割信息或旧 mdev 残留。
• 未授权 NVIDIA vGPU 出现帧率限制、CUDA 不可用或资源分配受限。
• 升级物理机 GPU 驱动后，vGPU 切割失败或数据库存在残留记录。

适用环境

• 产品：ZCF
• 组件：Cloud
• 涉及对象：ZStack Cloud；GPU 透传、vGPU、NVIDIA 驱动、vfio、IOMMU、mdev、许可证服务器
• 版本：4.x-4.8.38

可能原因

• BIOS 未开启 Intel VT-d/AMD-Vi，或物理机内核未启用 IOMMU。
• vfio/vfio-pci 模块未加载，同一 IOMMU 组内仍有设备绑定原生驱动。
• NVIDIA host/guest 驱动版本、Guest OS 版本或 GRID 驱动不匹配。
• 大显存 GPU 直通时，UEFI/OVMF MMIO 空间不足。
• vGPU 切割/还原过程中未先卸载云主机 vGPU，导致 mdev 数据残留。
• NVIDIA vGPU 许可证未配置、无法访问 CLS/DLS，或 gridd 服务未加载 token。
• 平台数据库中 MdevDeviceVO、PciDeviceMdevSpecRefVO 等记录与物理机实际状态不一致。

排查步骤

1. 检查物理机基础能力

cat /proc/cmdline
dmesg | grep -i iommu
lsmod | grep vfio
lspci | grep -i nvidia
lspci -v -s <pci-address> | grep -i "Kernel"

• BIOS 需开启 VT-d 或 AMD-Vi。
• 内核参数需启用 IOMMU，并按需屏蔽 nouveau、nvidiafb 等原生驱动。
• 透传前确认目标 GPU 及同 IOMMU 组设备已满足 vfio 绑定要求。

2. 检查云主机透传与 Guest OS 驱动

• 管理节点日志关注 hot_plug_pci_device、handle_vfio_irq_conflict、hot_unplug_pci_device。
• KVM agent、libvirt、Guest OS 系统日志中检索 vfio、pci、nvidia、iommu。
• Windows 驱动问题需结合设备管理器、系统事件日志和蓝屏 minidump。
• Linux 驱动问题需检查 DKMS 编译日志和内核版本匹配情况。

3. 处理大显存 GPU error 12

• 对 A40 等大显存 GPU，若 Windows 提示 error 12，可评估使用 UEFI 并调整 OVMF 64-bit MMIO 空间。
• 相关场景中使用 X-PciMmio64Mb 方式将 MMIO 空间设置为显存两倍，具体参数需由技术支持按环境确认后变更。

4. 检查 vGPU 切割、还原和残留

select * from MdevDeviceVO;
select * from PciDeviceMdevSpecRefVO;

• 升级驱动或还原切割前，应先关闭加载了 vGPU 的云主机并卸载 vGPU。
• 未还原切割直接卸载驱动，可能导致数据库残留。
• 涉及数据库修复前必须备份数据库，并由技术支持确认 SQL。

5. 检查 NVIDIA 许可证

• vGPU 未授权时可能出现帧率限制、资源分配受限、CUDA 禁用等现象。
• CLS 授权需要云主机可访问 NVIDIA 在线服务；DLS 需要内网许可证服务器。
• Windows token 目录通常为 %SystemDrive%\Program Files\NVIDIA Corporation\vGPU Licensing\ClientConfigToken。
• Linux token 目录通常为 /etc/nvidia/ClientConfigToken，并需检查 nvidia-gridd 服务。

补充排查方法

基础排查命令

# 管理节点服务和集群基础状态
zstack-ctl status
systemctl status zstack-ha.service 2>/dev/null || true
systemctl status mariadb.service mysqld.service 2>/dev/null || true
zsha2 status 2>/dev/null || true

# 管理节点主日志和近期错误
ls -lh /usr/local/zstack/apache-tomcat/logs/management-server.log*
grep -iE 'ERROR|WARN|Exception|failed|timeout' /usr/local/zstack/apache-tomcat/logs/management-server.log | tail -n 200

# 基础资源与系统状态
df -hT
free -m
top -b -n 1 | head -n 30
journalctl -p warning --since '2 hours ago' --no-pager | tail -n 200

临时解决方案

• 先区分管理面显示异常、资源状态异常和底层业务异常；只在确认底层状态正常时，才考虑重连、刷新缓存、重试任务或重启管理服务。
• 如需重启管理节点服务，先确认 HA 状态、当前任务和业务窗口，优先单节点逐台处理，并保留 /usr/local/zstack/apache-tomcat/logs/management-server.log*。
• 涉及数据库修复、资源强制删除、主存储/镜像服务器重连等操作时，先完成数据库备份并记录回退方案。

硬件、驱动、安全与升级专项检查

uname -a
rpm -qa | egrep 'zstack|qemu|libvirt|kernel|nvidia|vfio|spice|qxl' | sort
lspci -nn
lsmod | egrep 'vfio|kvm|nvidia|mlx|ixgbe|i40e|bnx|megaraid'
dmesg -T | grep -iE 'error|failed|reset|timeout|nmi|mce|iommu|vfio|gpu|driver' | tail -n 200
systemctl list-units --failed

硬件/升级类临时处理建议

• 驱动、GPU、外设或升级依赖异常时，先确认内核、驱动、固件和 ZStack 版本组合；不要在未确认兼容性前直接升级内核或替换驱动。
• 安全加固或漏洞修复后异常，优先核对防火墙、SELinux、系统库、端口监听和服务启动权限，必要时按变更方案回退加固项。
• 升级失败应保留升级日志、版本包、依赖检查输出和当前服务状态；只在确认继续条件满足时执行 continue/retry。

补充信息

• 排查结论需结合当前版本、服务状态、日志、集群健康、近期变更和现场影响面确认。
• 涉及数据库修改、强制删除、OSD/MON 重建、Pool 删除、服务重启或网络变更等高风险操作时，应先完成备份、审批和技术支持确认。