QEMU Guest Agent 安装与命令

作用

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

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

qm agent <VMID> ping

命令成功退出、没有报 Guest Agent 不可用，表示通信正常。CLI 不一定输出正文；{"return":{}} 是底层 QGA 协议的响应形式，不应作为 qm CLI 的必需输出。

命令格式：

qm agent <VMID> <cmd>

qm agent 是 qm guest cmd 的别名，仅用于下表这类 QGA 指令。执行客户机程序使用独立入口 qm guest exec。

示例 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 shutdown 101

重启：

qm reboot 101

这两个是 PVE 的虚拟机生命周期命令；启用 Guest Agent 后，PVE 可使用相应客户机能力。若明确需要通过 QGA 请求关机，可用 qm guest cmd 101 shutdown。不要写成不存在的 qm guest shutdown 或 qm guest reboot。

Linux 示例：

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

Windows 示例：

qm guest exec 101 -- cmd.exe /c "echo Hello from PVE"

默认同步等待执行结果；若使用 --synchronous 0 返回 PID，后续用 qm guest exec-status 101 <PID> 查询状态。

冻结文件系统：

qm agent 101 fsfreeze-freeze

解冻文件系统：

qm agent 101 fsfreeze-thaw

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

依据：Proxmox VE qm 官方手册。本文于 2026-10-15 校订命令层级，未在本轮连接真实 PVE 节点执行。