Windows 虚拟机热添加 VirtIO 网卡后，首次配置网络失败 | 故障排查 · KB

文档目录

问题说明

热添加 VirtIO网卡后，Windows PnP/netkvm设备就绪可能晚于平台首次同步。已观察到两类表现：Get-NetAdapter阻塞超过Host超时，或命令快速返回但固定重试窗口内找不到目标MAC。稍后网卡就绪，旧任务可能继续执行或后台同步成功。

现象

Attach NIC后立即配置网络，首次API约120秒失败，或日志报 failed to find nic after retrying。
QGA心跳正常，但目标MAC在最初数十秒内不出现在 Get-NetAdapter。
约1分钟到数分钟后网卡出现，重试成功或IP最终生效。
IP最终生效不代表首次API成功；可能是超时后的旧Guest进程继续运行。

适用环境

ZSphere 5.1.0、Windows VirtIO热插网卡已验证。冷启动网卡、e1000或MAC不一致需要单独分析。

可能原因

按时间线对齐热插、首次配置、Windows PnP设备启动、QGA首次上报MAC和后续成功。QGA健康只证明通道可用，不证明网卡已经ready。

问题定性

类型：产品 Bug/Windows PnP时序兼容问题。
已知问题：是；ZSV-12857截至2026-08-06为Open/P1，影响版本5.1.0，尚无fixVersion。
根因：首次配置早于VirtIO/netkvm设备ready；固定等待和Host超时不能覆盖Windows PnP就绪时间，且超时后Guest进程可能未终止。
置信度：高，前提是完整时间线一致。

排查步骤

检查一：确认目标MAC是否已枚举

只读 PowerShell：

  Get-NetAdapter -IncludeHidden |
    Format-Table Name,ifIndex,Status,MacAddress,InterfaceDescription -Auto
  Get-PnpDevice -PresentOnly | Where-Object { $_.FriendlyName -match 'VirtIO|Ethernet' } |
    Format-Table Status,Class,FriendlyName,InstanceId -Auto

找不到目标MAC但平台刚完成热插：支持PnP未就绪分支，继续查事件时间。
目标MAC已存在且状态Up：首次失败可能已过时；仍需查 zs-tools日志，不能直接判定修复。
MAC与平台记录不一致：转MAC/inventory问题，不适用本篇。

检查二：对齐Windows PnP事件

只读 PowerShell：

  Get-WinEvent -LogName 'Microsoft-Windows-Kernel-PnP/Configuration' -MaxEvents 100 |
    Where-Object { $_.Id -in 400,410 } |
    Select-Object TimeCreated,Id,LevelDisplayName,Message
  Get-WinEvent -LogName System -MaxEvents 200 |
    Where-Object { $_.Id -eq 7036 -and $_.Message -match 'Network Setup' } |
    Select-Object TimeCreated,Id,Message

设备启动完成晚于首次配置失败：时序证据成立。
PnP早已完成：需查驱动错误、MAC匹配或Guest工具本身。

检查三：对齐平台和GuestTools日志

只读检索：按VM UUID/MAC/API时间搜索审计、zstack-kvmagent.log和Guest内zs-tools.log。
120秒Host超时后Guest日志仍继续，或出现重复命令：存在残留进程/并发风险。
5次固定重试均找不到MAC，稍后QGA首次上报同一MAC：符合ZSV-12857另一表现。

处理建议

Note:

本节操作须由具备权限的管理员人工执行。

热添加后等待 Windows中目标MAC已出现且设备状态正常，再由人工重试一次网络配置。重试前确认没有仍运行的旧 zs-tools net任务，避免并发改网。生产网络变更应有控制台/带外和原配置回退方案；不要因QGA在线就连续快速重试。

长期方案

跟踪ZSV-12857：按目标MAC等待设备ready；为子命令和完整进程树设置deadline；Host超时后终止Guest任务；zs-tools net增加全局互斥并输出PID/耗时/最后子命令。

补充信息

升级人工条件

目标MAC长期不出现或设备黄色感叹号。
配置失败后存在多个残留 zs-tools进程。
已等待设备ready仍失败。
需要终止进程、重启服务/Guest或变更生产IP。

需要收集的信息

ZSphere/Windows/VirtIO驱动版本、VM与NIC UUID/MAC、API与热插时间、审计、KVM Agent日志、zs-tools日志、PnP 400/410和System 7036事件。