PVE USB 直通：三种绑定方式与链路故障处置

1. 概述

Proxmox VE 提供三种 USB 直通方式，适用场景与失效模式差异明显：

配置通过 qm set 写入虚拟机配置，立即持久化，下次启动生效。

2. 设备绑定

lsusb
# Bus 002 Device 004: ID 0403:6001 FTDI FT232R USB UART

qm set 100 -usb0 host=0403:6001

host= 支持三种取值：

• vendor:product（0403:6001）——同型号多设备时产生冲突
• 序列号（host=FTDI1234）——同型号多设备的唯一可靠标识
• 端口路径（见第 3 节）

约束：设备重新插拔后，QEMU 不会重新枚举，直通关系失效，需重新执行 qm set 或重启虚拟机。宿主侧设备节点保留，可与虚拟机争用。

3. 端口绑定

qm set 100 -usb0 host=2-1.4

绑定对象为 USB 拓扑路径（bus-port.port），与设备身份无关。适用于端口固定、设备频繁更换的场景。主板或 HUB 拓扑变更后配置失效。

4. 控制器直通

lspci -nn | grep -i usb
# 00:14.0 USB controller [0c03]: Intel Corporation ... [8086:a36d]

qm set 100 -hostpci0 0000:00:14.0,pcie=1

将整条 PCI USB 控制器移交虚拟机，其下所有设备（含后续热插拔）一并可见，无需重复配置。

前置条件：

• 该控制器下不得承载宿主关键设备（键鼠、系统盘所在 USB 存储）
• 需启用 IOMMU，且控制器位于独立 IOMMU 组
• 执行 lsusb -t 确认拓扑，避免误选与其他功能共享的控制器

移交后宿主完全失去该控制器，无法再用于其他虚拟机。

5. 串口设备命名稳定性

USB 串口设备的 /dev/ttyACM*、/dev/ttyUSB* 编号在重新枚举时可能变化，直接写入应用配置会导致连接失败。

两种稳定化方案：

# 方案一：使用 by-id 固定路径
ls -l /dev/serial/by-id/
# usb-FTDI_FT232R_USB_UART_A50285BI-if00-port0 -> ../../ttyUSB0

# 方案二：udev 规则建立固定符号链接
SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", SYMLINK+="serial_dev"

方案一依赖设备序列号，更换设备后路径改变；方案二按 VID 匹配，同型号设备共存时仍会冲突，必要时追加 ATTRS{serial} 条件。

6. 整盘直通与链路故障

块设备可按 by-id 路径直接挂载至虚拟机：

qm set 101 -sata2 /dev/disk/by-id/ata-WDC_WD40EFRX_XXXX

该方式性能优于 USB 设备直通，但不具备链路故障容错能力。

6.1 故障表现

USB-SATA 桥接芯片在供电波动、线材接触不良或设备休眠唤醒时可能触发链路重置。内核日志呈现规律性 reset：

usb 2-3.2: reset SuperSpeed USB device number 4
I/O error, dev sdb, sector 16785280 op 0x1:(WRITE)

重置次数累积后，QEMU 进入 io-error 状态：虚拟机进程存活，vCPU 停止调度，表现为存储服务无响应。上层现象具有传导性：

• CIFS/NFS 客户端返回 Host is down
• 依赖该挂载点的应用进入崩溃循环
• 存储管理界面中指向该卷的共享目录无法删除（所属存储空间不可用）

6.2 处置流程

# 1. 备份虚拟机配置
cp /etc/pve/qemu-server/101.conf /root/101.conf.bak

# 2. 移除故障直通盘
qm set 101 --delete sata2

# 3. 启动虚拟机
qm start 101

恢复顺序应为：存储层就绪 → 挂载点可读写 → 启动应用。存储未就绪时提前启动应用，会因读取失败进入崩溃循环并掩盖真实故障点。

6.3 遗留问题

直通盘卸载后，宿主机与虚拟机侧可能残留失效挂载：

• 挂载点目录项损坏，umount 返回 not mounted（路径无法解析）
• 引用该挂载点的容器需重启以重建挂载表

7. 运维注意事项

备份策略：直通盘应在配置中标记 backup=0，避免备份任务读取不稳定设备导致任务超时或失败。

宿主设备占用：串口设备若被 ModemManager 等守护进程持有，直通后虚拟机无法获取数据流：

systemctl disable --now ModemManager

配置变更时机：qm set 即时写入配置，但设备移交发生在下次启动。生产环境变更应安排维护窗口。

故障可见性：io-error 状态不会主动告警，需在监控侧采集 qm status 或依赖上层服务探活。

8. 选型建议

USB 直通配置本身不复杂，工程难点在于链路异常后的检测与恢复。部署前应明确监控手段与恢复顺序，再确定直通方式。