> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/run-the-platform/zh/xu-ni-ji/vm-guest-agent.md).

# VM 来宾代理

来宾代理是在来宾操作系统内安装的一个程序，允许主机在虚拟机内运行命令。这通过在快照之前冻结来宾文件系统并在不依赖 ACPI、策略等的情况下正确关闭来宾，来实现一致、可靠的备份。

## 要求

* 为虚拟机启用来宾代理
* 安装来宾代理（在来宾操作系统内）

## 启用来宾代理

每个虚拟机都必须单独启用来宾代理；这可以在创建虚拟机时完成，也可以通过编辑现有虚拟机来完成。虚拟机仪表板上的“来宾代理”复选框会指示代理是否已启用。

![agent-enabled-notconnected.png](/files/d3b089b3d6b88e4ed6c3e260fe3946b6d21cfe67)

### 在现有虚拟机上启用来宾代理

1. 进入虚拟机仪表板
2. 单击 **编辑** 左侧菜单中的。
3. 单击以勾选 **QEMU Guest Agent** 复选框。
4. 单击 **提交** 以保存更改。

## 在 Windows 虚拟机上安装代理软件

### 下载/安装来宾工具安装程序

可从以下链接下载来宾代理安装程序（并在来宾中运行）： <https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/virtio-win-guest-tools.exe>

{% hint style="success" %}
在 VirtIO 安装程序设置过程中，务必选择 *安装* 设备软件按钮。
{% endhint %}

为了应用更改并连接代理，虚拟机需要重新启动。

### 将完整 VirtIO ISO 下载到 vSAN

以下说明介绍如何将 win-virtio.iso 文件（包含必要的来宾代理软件）放置到 vSAN 上；这样可以将软件加载到虚拟机的 CD-ROM 驱动器中，方便在来宾操作系统内安装。

1. 点击下面的链接以访问 VirtIO ISO。
2. “通过 URL 上传”链接会显示出来，所有字段都已自动填充；通常无需进行任何更改；不过，如有需要，可以选择性地更改“文件名”、“文件描述”和/或“首选层”字段。
3. 单击“提交”将 VirtIO iso 文件下载到 vSAN。
4. 当进度显示 100% 完成（右上角的进度条）时，文件即已可用，会出现在文件列表中，并可在任何 CD 驱动器上进行选择。请参阅下面的说明，了解如何从下载的 VirtIO iso 安装来宾代理软件。

### 从 VirtIO ISO 安装来宾代理（Windows）

{% hint style="info" %}
虚拟机必须有一个 CD-ROM 设备
{% endhint %}

1. 导航到 **虚拟机仪表板**.
2. 单击 CD-ROM 选择按钮（左上角） ![fa-eject.png](/files/5a4807d7ee5d46c0958dfd5aff90401fa7af0195)
3. 选择 **virtio-win.iso（或下载时修改后的文件名）**.
4. 单击 **提交** 以应用 CD 更改。
5. 单击 **远程控制台** 在左侧菜单中进入控制台，以连接到来宾操作系统。
6. 前往 **Windows 设备管理器**.
7. 右键单击 **“PCI 简单通讯控制器”**.
8. 选择 **更新驱动程序**.
9. 浏览到 **CD-ROM 驱动器路径** 其中包含已下载的 iso。
10. 导航到： **vioserial\您的 Windows 版本（例如：2k12R2、WIN10 等）**.
11. 单击 **下一步** 以完成驱动程序更新。
12. 在 Windows 文件资源管理器中， **浏览到 CD-ROM** 其中包含 VirtIO iso。
13. 进入 **guest-agent** 文件夹。
14. **双击** 在正确的 MSI 上 **（qemu-ga-x86.msi\[64 位] 或 qemu-ga-1386.msi\[32 位]）** 文件以启动安装程序。

{% hint style="success" %}
可能需要重新启动虚拟机，以便将代理连接到主机。
{% endhint %}

## 在 Linux 虚拟机上安装代理软件

在 Linux 虚拟机上， **qemu-guest-agent 软件包** 必须安装。安装说明会因具体的 Linux 发行版/版本而异。

* 在使用 apt 进行安装的系统上 **（基于 Debian/Ubuntu）**:

  ```
  apt-get install qemu-guest-agent
  ```
* 在使用以下工具的系统上 **Yum（Redhat）**:

  ```
  yum install qemu-guest-agent
  ```
* 某些发行版将需要 **重启或手动启动** 该代理：

  ```
  systemctl start qemu-guest-agent
  ```

## 验证虚拟机来宾代理连接

当来宾代理成功连接时，版本号将显示在虚拟机仪表板上已勾选的“来宾代理”复选框旁边。

![agent-connected-version.png](/files/d948ed18ecdb6a7562f9eaa301d42172e97a6995)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/run-the-platform/zh/xu-ni-ji/vm-guest-agent.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.