> 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/xi-tong-guan-li/usb-passthrough.md).

# USB 直通

如何在 VergeOS 中配置 USB 设备直通，包括主机设置、资源组创建、虚拟机来宾配置以及将 USB 设备分配给租户。

连接到主机的 USB 设备可以传递给 VM（以及租户再传递给其 VM），使设备看起来并行为就像直接连接在 VM 内部一样。

示例 USB 直通设备包括：

* 包含软件许可证密钥的驱动器
* 安防摄像头/监控设备
* 键盘/鼠标（支持在多个 VM 之间使用；对于专用硬件，通常比双系统/多系统 VM 配置更方便）

## 主机安装/配置

以下说明将通过为每个所选设备自动创建一条新规则并将设备附加到资源组来配置设备直通。有关资源组和资源规则的工作原理的更多信息，请参见： [**设备直通 - 资源规则**](/run-the-platform/zh/xi-tong-guan-li/device-pass-overview.md#resource-rules).

1. 导航到 **资源管理器仪表板** (*基础架构 > 资源*) **-或-** 导航到一个 **特定节点** USB 设备插入的节点。（*基础架构 > 节点* > 在列表中双击所需节点。）
2. 单击 **USB 设备**。将显示检测到的 USB 设备列表。

{% hint style="success" %}
**在 *****资源组***** 和 *****资源规则***** 列中显示值的 USB 设备已经配置为直通。**
{% endhint %}

3. **从列表中** 选择适当的 **USB 设备** 。

{% hint style="info" %}
**所有选定设备都将添加到同一个资源组（资源池），但每个设备都会创建单独的资源规则。**
{% endhint %}

4. 单击 **创建资源** 在左侧菜单中。
5. **创建新的 USB 资源组** **-或-** **选择一个 USB 资源组** 。

### USB 资源组字段

* **名称**：用于标识资源组（即设备池）的标签；请使用描述性名称，以便用户能够轻松识别此组中的设备类型。
* **类型**: ***USB***.
* **描述**：（可选）用于提供有关资源组的更多管理文本的字段。
* **类别**：允许为该组选择一个通用设备分类；例如，通用 USB 设备、人体输入设备、媒体等。此字段仅用于应用关联图标，不影响功能。

#### USB 设置

* **允许来宾重置**：勾选后，VM 用户可以重置 USB 设备。
* **允许来宾重置全部**：勾选后，VM 用户可以重置设备所连接的 USB 集线器。

{% hint style="info" %}
**USB 设备的重置操作取决于设备驱动程序；某些设备支持重置，某些则不支持。**
{% endhint %}

在选择资源组或新建资源组后，\**成功* 消息应该会出现，表明已为设备创建资源规则。

6. **可能需要重启相关节点**；资源管理器仪表板顶部会显示一条消息。

{% hint style="warning" %}
**重启节点时请遵循正确的** [**维护模式**](/run-the-platform/zh/yun-wei/maintenance-mode.md) **流程，以避免工作负载中断。**
{% endhint %}

资源组仪表板包含为所选设备自动生成的资源规则。您可以单击单个规则查看配置详情。系统创建的规则可根据需要修改；例如， *节点* 筛选器可以更改为 *-- 无 --* 以包含来自所有节点的匹配设备。有关资源规则的信息可在以下位置查看： [**设备直通概述 - 资源规则**](/run-the-platform/zh/xi-tong-guan-li/device-pass-overview.md#resource-rules)

## VM/来宾配置

1. 导航到 **VM 仪表板** （从顶部菜单：虚拟机 > 列表 > 在列表中双击所需 VM）
2. 单击 **设备** 在左侧菜单中。
3. 单击 **新建** 在左侧菜单中。

{% hint style="success" %}
**您也可以通过资源管理器将设备附加到 VM：从资源组仪表板 > 双击所需的 SR-IOV 组 > 查看机器设备 > 新建；从机器下拉列表中选择 VM。**
{% endhint %}

### 设备条目表单字段

* **名称**：提供一个名称来标识设备，例如“exapp 许可证密钥”，或者留空以允许系统自动生成设备名称。
* **类型**: ***USB***
* **描述**（可选）：可在此输入附加文本用于管理目的。
* **资源组**：从下拉列表中选择适当的 USB 资源组
* **USB 设置**：见上文。

4. 单击 **提交** 以完成添加新设备。
5. 安装任何所需的客户端驱动程序；如有需要，请查阅设备硬件文档。
6. VM 需要 **重启** 才能附加该设备。在 VM 仪表板中，单击顶部显示消息中的 *重启* 链接，或单击 **重启** 在左侧菜单中。

## 将 USB 设备直通给租户

USB 设备可以传递给租户，由租户再传递到其自己的 VM。当您将 USB 设备直通给租户时，会在租户内创建一个新的资源组。

{% hint style="info" %}
**当设备共享给租户时，它们采用厚置备（即租户随后拥有这些设备，因此即使未使用，也不能再分配给其他 VM 或租户。）**
{% endhint %}

1. 导航到所需的 **租户仪表板** （从顶部菜单：租户 > 列表 > 在列表中双击该租户。）
2. 单击 **节点** 在左侧菜单中。
3. **双击其中一个租户节点**.
4. 单击 **设备** 在左侧菜单中。
5. 单击 **新建** 在左侧菜单中。
6. 输入一个 **名称** 或留空以允许系统自动创建名称；此名称将用于在租户中创建的资源组。
7. **类型**: ***USB***.
8. **描述**：用于存储有关设备/设备池的附加管理信息。
9. **USB 设置**：见上文。
10. 完成字段后，单击 **提交** 以完成传递给租户。
11. 这些设备现在将作为可附加到租户 VM 的资源组可用。请遵循 [**VM/来宾配置**](#vmguest-configuration) 上面的说明。为了使用该直通设备，VM 必须在连接了该设备的租户节点上运行。

## 故障排除

### 节点重启后 VM 无法启动

**症状：** 带有 USB 直通设备的 VM 在其主机节点重启后无法启动（例如，在 VergeOS 更新后）。VM 会反复尝试启动，但无法打开 USB 设备。

**原因：** 自动生成的资源规则使用设备的物理总线地址（路径筛选器）来识别设备。每次 USB 设备枚举时都会分配该地址。服务器硬件拓扑的变化（例如添加或移除 PCI 设备）可能会改变 USB 控制器呈现其端口的方式，从而导致路径不同。在极少数系统上，主板固件在控制器重置后可能会以不同方式重新枚举 USB 端口，即使没有任何硬件更改也会导致路径变化。当设备出现在新地址时，该规则将不再匹配正在运行的设备，从而阻止 VM 启动。

**修复：** 编辑资源规则，使其使用稳定的硬件 ID 而不是物理地址来匹配设备：

1. 导航到 **基础架构 > 资源**.
2. 在 ***规则*** 部分中，找到该 USB 设备的自动生成规则。
3. **双击该规则** 将其打开以进行编辑。
4. 启用 **供应商 ID** (`vendor_id`）和 **型号 ID** (`model_id`）筛选字段。型号 ID 即 USB 产品 ID。
5. 启用 **序列号** 字段（仅支持的设备）以将规则锁定到某个特定设备。大多数知名品牌的 USB 闪存盘、外置 HDD/SSD、摄像头以及打印机/扫描仪都包含唯一的、出厂编程的序列号。
6. 如果您的服务器在不同启动之间无法分配一致的 PCI 路径，请禁用物理位置筛选字段（路径和设备）。如果您希望规则与设备匹配，而不管它插入哪个 USB 端口，也可以禁用这些字段。
7. 单击 **提交** 以保存规则。
8. 启动 VM。

供应商 ID、型号 ID 和序列号在重启后保持稳定，因此无论设备如何重新枚举，该规则都能匹配到该设备。


---

# 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/xi-tong-guan-li/usb-passthrough.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.