guest agent 是平台与虚机之间的通道
在 KVM 及基于它的信创云平台、超融合环境里，虚拟机内部的 qemu-guest-agent 通过 virtio 串口设备与宿主机平台通信。平台侧的「优雅关机」「在线改密」「冻结文件系统做快照」等操作都依赖这条通道；agent 没就绪时，这些操作会失败、超时，或者被平台降级成硬关机。
基本信息
| 检查服务 | systemctl status qemu-guest-agent |
|---|---|
| 设备文件 | /dev/virtio-ports/org.qemu.guest_agent.0 |
| 平台侧要求 | 虚拟机配置中需有对应 channel 设备 |
| 常见依赖 | 内核 virtio_console 模块与 qemu-guest-agent 包 |
| 权限要求 | root |
典型使用场景
- 平台侧发起优雅关机或重启失败、一直超时
- 在线改密、在线调整配置在平台上不生效
- 创建快照前需要冻结文件系统以保证一致性
- 批量巡检确认所有虚机的 agent 是否就绪
- 从其他平台迁移来的虚机补装 agent 后验证握手
自查命令
自查命令
systemctl status qemu-guest-agent --no-pager | head # 服务是否 active
ls -l /dev/virtio-ports/ 2>/dev/null # virtio 串口设备是否存在
dmesg -T | grep -i virtio | head # 内核侧 virtio 设备注册情况
journalctl -u qemu-guest-agent --no-pager | tail -20 # agent 日志与握手记录
lsmod | grep virtio_console # 关键模块是否已加载
systemctl enable --now qemu-guest-agent # 未启用时开启并设为开机自启
# 平台侧：确认虚拟机配置中存在 org.qemu.guest_agent.0 通道状态逐项判读
| 检查项 | 正常表现 | 异常含义 |
|---|---|---|
| 服务状态 | active (running) | inactive 表示 agent 未运行 |
| 串口设备 | 存在 org.qemu.guest_agent.0 | 不存在说明虚拟机缺 channel 配置 |
| agent 日志 | 能看到与平台的消息往来 | 无日志说明通道没建立 |
| 平台侧显示 | 显示已就绪 | 未就绪则平台操作不可用 |
agent 未就绪时平台侧操作会失败或超时：排查顺序是先看虚机内的服务与设备，再看虚拟机的 channel 配置，最后才怀疑平台侧问题。
安全加固收紧 /dev/virtio-ports 权限后，agent 可能读不到设备：加固项调整时要把它纳入核查范围并复验平台操作是否仍可用。
批量巡检建议做成清单：逐台记录服务状态、串口设备是否存在、平台侧是否显示已就绪三项，任何一项不符就单独跟进，比逐台登录排查效率高很多。