QEMU Guest Agent 安装与命令

作用

QEMU Guest Agent 让 PVE 宿主机能和虚拟机内部通信，用于：

• 在 PVE Web UI 显示虚拟机 IP。
• 安全关机 / 重启。
• 快照前冻结文件系统。
• 获取文件系统、OS、主机名等信息。

PVE 侧启用

1. 关闭虚拟机。
2. PVE Web UI -> 虚拟机 -> Options -> QEMU Guest Agent -> Enable。
3. 启动虚拟机。

Linux 虚拟机安装

Debian / Ubuntu：

sudo apt update
sudo apt install qemu-guest-agent -y
sudo systemctl enable --now qemu-guest-agent
systemctl status qemu-guest-agent

CentOS / Rocky / AlmaLinux：

sudo yum install qemu-guest-agent -y
sudo systemctl enable --now qemu-guest-agent
systemctl status qemu-guest-agent

Windows 虚拟机安装

1. PVE 中给虚拟机挂载 VirtIO ISO。
2. Windows 中打开 VirtIO ISO。
3. 进入 guest-agent 目录。
4. 运行 qemu-ga-x64.msi 或 qemu-ga-x86.msi。
5. 打开 services.msc，确认 QEMU Guest Agent 正在运行且启动类型为自动。

基础验证

qm agent <VMID> ping

返回：

{"return":{}}

表示通信正常。

常用命令速查

命令格式：

qm agent <VMID> <cmd>

示例 VMID 使用 101：

命令	作用
qm agent 101 ping	检查 Guest Agent 是否在线
qm agent 101 network-get-interfaces	查看虚拟机网卡和 IP
qm agent 101 get-osinfo	查看客户机系统信息
qm agent 101 get-host-name	查看主机名
qm agent 101 get-fsinfo	查看文件系统信息
qm agent 101 get-time	查看客户机时间
qm agent 101 get-timezone	查看时区
qm agent 101 get-users	查看当前用户
qm agent 101 get-vcpus	查看 CPU 数量
qm agent 101 fstrim	对支持的磁盘执行 TRIM
qm agent 101 fsfreeze-status	查看文件系统冻结状态
qm agent 101 fsfreeze-freeze	冻结文件系统
qm agent 101 fsfreeze-thaw	解冻文件系统
qm agent 101 info	查看支持的 Guest Agent 命令

关机和重启

安全关机：

qm guest shutdown 101

重启：

qm guest reboot 101

在客户机内执行命令

Linux 示例：

qm agent 101 exec -- /bin/echo "Hello from PVE"

Windows 示例：

qm agent 101 exec -- cmd /c "echo Hello from PVE"

快照一致性

冻结文件系统：

qm agent 101 fsfreeze-freeze

解冻文件系统：

qm agent 101 fsfreeze-thaw

冻结后必须及时解冻，否则虚拟机内部写入会受影响。一般只在备份或快照流程中短时间使用。