Guest Agent：为什么重要以及如何重装
qemu-guest-agent 提供什么，如何判断它已消失，以及如何在 Debian、Ubuntu、AlmaLinux 和 Windows Server 上恢复它。
更新于 2026年8月23日
面板的部分数据并非来自外部，而是来自系统内部的一个小型服务——qemu-guest-agent。它不会开放端口，也不会接触网络：通信通过内部虚拟化通道进行。
它提供什么
- 概览环形图中显示的真实已用磁盘空间。没有该代理，面板只能知道镜像大小。
- 优雅重启和关机：系统收到信号后正确停止服务，而不是直接断电。
- 机器网络地址的准确列表。
没有该代理，机器仍会继续运行；只是面板显示的信息更少，而且重启会变得困难——这会给数据库和文件系统带来各种风险。
如何判断它缺失
第一个迹象是，在 /hosting/vds/m/<id> 的概览中，已用磁盘空间消失了。这种情况下，面板本身会显示适用于您系统的安装命令。
从内部检查：
systemctl status qemu-guest-agent
ls -l /dev/virtio-ports/org.qemu.guest_agent.0
如果 /dev/virtio-ports 中没有设备，该服务会启动后立即进入休眠：它所需的通道不存在。
安装
Debian 和 Ubuntu：
apt update
apt install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent
AlmaLinux 和 CentOS Stream：
dnf install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent
Windows Server 2022 和 2025：该代理是 virtio-win 驱动集的一部分。安装 virtio-win-guest-tools，然后在“服务”管理单元中确认 QEMU Guest Agent 正在运行并已设置为自动启动。
几秒钟后，刷新概览——已用空间应该会出现。
它为什么会消失
| 原因 | 发生了什么 |
|---|---|
| 安装时选择了最小软件包集 | 该代理从一开始就不存在 |
apt autoremove | 被当作“不需要的依赖”移除 |
| “额外服务”清理 | 该服务被手动禁用 |
| 重装操作系统 | 全新镜像，不含您的自定义配置 |
您可以随时安全地把它装回来：该服务不会造成明显的负载，也不会接触网络。
常见错误
- 服务处于
active状态，但面板中没有数据——等待图表更新，并检查/dev/virtio-ports中是否有设备。 Unit qemu-guest-agent.service not found——软件包未安装，而不是损坏了。- 代理已安装，但重启仍然困难——检查自启动：
systemctl is-enabled qemu-guest-agent。
该代理不能替代对机器的访问。如果系统无法启动，能帮您的不是它——而是救援磁盘。