Windows 虚拟机已安装 VMTools，但平台显示未安装 | 故障排查 · KB

文档目录

问题说明

“平台显示未安装”是一类现象，不是唯一根因。本篇是导航文章，只负责收集区分性证据并路由，不能仅凭页面状态直接认定为驱动问题或产品 Bug。

现象

Windows 中能看到 VMTools/GuestTools 目录或服务，页面仍显示“未安装”。
可能同时出现 QGA 不通、版本为空、安装失败标签残留或 Defender 隔离事件。
最关键的区分点是：VirtIO Serial 是否正常、服务是否运行、VERSION 是否有效、安全软件是否隔离文件。

适用环境

Windows Guest 已执行 VMTools 安装，但平台状态仍为未安装、安装失败或版本不正确。

可能原因

按“设备驱动 → 服务/进程 → 版本文件 → 安全软件 → 平台状态刷新”的顺序检查。先排除 Guest 内明确故障，再判断是否只是控制面状态未刷新。

问题定性

类型：现象导航/证据分流，本篇不直接定性。
已知问题：不唯一。驱动异常见 TIC-6202/TIC-5001；VERSION 异常见 TIC-5977；状态刷新见 TIC-3099；旧失败标签见 TIC-5236/ZSTAC-81243；Defender 隔离见 ZSV-12861。
已验证版本：TIC-6202 为 ZSphere 4.10.25。其他分支必须以各自 Jira 为准。
置信度：本篇只对路由结论给出高置信，不能替代根因文章。

排查步骤

检查一：检查 VirtIO 设备状态

检查目的：确认 QGA 通道依赖的 VirtIO Serial 驱动是否异常。
只读 PowerShell：

  Get-PnpDevice | Where-Object { $_.FriendlyName -match 'VirtIO|Serial|Balloon' } |
    Format-Table Status,Class,FriendlyName,InstanceId -Auto

VirtIO Serial/Balloon 为 Error、Unknown 或设备管理器黄色感叹号：转到 KB-100554。
设备均为 OK：继续检查服务，不能引用 TIC-6202 作为根因。

检查二：检查服务和进程

只读 PowerShell：

  Get-Service | Where-Object { $_.Name -match 'qemu|guest|zwatch' } |
    Format-Table Name,Status,StartType -Auto
  Get-Process | Where-Object { $_.ProcessName -match 'qemu-ga|zs-tools|zwatch' } |
    Select-Object ProcessName,Id,Path

qemu-ga/GuestTools 服务停止：属于 Guest 服务异常分支，收集事件日志，不直接归因驱动。
服务运行：继续检查版本文件和 Defender。

检查三：检查安装标识和安全软件

只读 PowerShell（路径以现场实际安装目录为准）：

  Get-ChildItem 'C:\Program Files\GuestTools' -Force -ErrorAction SilentlyContinue
  Get-Content 'C:\Program Files\GuestTools\VERSION' -ErrorAction SilentlyContinue
  Get-MpThreatDetection | Select-Object InitialDetectionTime,ThreatName,Resources

VERSION 为空/不存在：接近 TIC-5977 的安装落盘异常，收集安装日志。
Defender 记录隔离 zs-tools.exe：转到 KB-100562；ZSV-12861 截至 2026-08-13 为 Open，必须升级人工。
文件和服务均正常、无隔离：检查平台审计和状态更新时间；可能是 TIC-3099 的非实时刷新或旧 GuestTools::InstallFailed 标签分支，需平台侧人工确认。

处理建议

Note:

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

按命中的分支处理。更新驱动、恢复被隔离文件、重启服务、刷新平台状态或清理标签均需要人工审批；在没有分支证据前不要反复重装 VMTools。

长期方案

平台应分别展示“驱动/通道异常、服务未运行、版本未知、安全软件隔离、状态待刷新”，减少统一显示“未安装”造成的误判。

补充信息

升级人工条件

所有 Guest 检查正常但页面持续未安装。
Defender 检测或隔离 VMTools 文件。
需要更新驱动、重启 Guest、清理标签或刷新平台状态。
Windows 2012 偶现、重启后恢复但无证据：参考 ZSV-9951（Open），不得自行定根因。

需要收集的信息

ZSphere/Windows 版本、VMTools 版本、设备管理器截图、上述命令输出、安装日志、Windows System/Defender 事件、平台审计时间和 VM UUID（提交工单时脱敏）。