USB/IP — sing-box

两个服务通过 USB/IP 共享 USB 设备：usbip-server 导出本地设备，usbip-client 从远端服务器导入设备。二者都基于 sing-usbip，它在标准协议之上增加了热插拔等增强功能，同时保持与标准协议的互通：标准 USB/IP 客户端可以从 usbip-server 导入，但 usbip-client 需要 sing-box（sing-usbip）服务端。

服务端 —— usbip-server

services[] 下的 type: "usbip-server"：

字段	类型	默认值	允许值	描述
provider	string	default	default | dynamic	导出设备的来源。default 导出与 devices 匹配的本地设备（仅限在 Linux、Windows、macOS 上以 CLI 运行，且需提升权限）。dynamic 则在运行时由 sing-box API 客户端提供设备 —— macOS 和 Android 上的图形客户端，或基于 Chromium 的浏览器中的 sing-box Dashboard。

源码： option/usbip.go:17-21 · 锚定版本 v1.14.2 (af6e64c)

服务端还嵌入了 ListenOptions（见入站）；listen_port 默认为 3240，即标准 USB/IP 端口。使用 provider: "default" 时接受：

字段	类型	默认值	允许值	描述
devices	[]USBIPDeviceMatch	(required)	[USBIPDeviceMatch]	要导出的本地设备。使用 default 提供方时必填。

源码： option/usbip.go:77-79 · 锚定版本 v1.14.2 (af6e64c)

dynamic 提供方没有额外字段。

设备匹配

字段	类型	默认值	允许值	描述
bus_id	string	(any)	<bus-port>	USB 总线 ID，例如 1-2。
vendor_id	uint16	(any)	<uint16>	USB 厂商 ID，以 JSON 数字表示（十进制 —— 例如 0x046d 写作 1133）。
product_id	uint16	(any)	<uint16>	USB 产品 ID，以 JSON 数字表示。
serial	string	(any)	<string>	设备序列号。

源码： option/usbip.go:70-75 · 锚定版本 v1.14.2 (af6e64c)

同一对象中设置的所有字段都必须匹配；多个对象之间取并集。每个对象至少需要一个字段。

客户端 —— usbip-client

services[] 下的 type: "usbip-client"：

字段	类型	默认值	允许值	描述
server	string	(required)	<host>	远端 usbip-server 的地址。
server_port	uint16	3240	<port>	远端 usbip-server 的端口。

源码： option/outbound.go:183-186 · 锚定版本 v1.14.2 (af6e64c)

字段	类型	默认值	允许值	描述
devices	[]USBIPDeviceMatch	(all exported)	[USBIPDeviceMatch]	要导入的远端设备，匹配对象与服务端相同。为空则导入所有已导出的设备。

源码： option/usbip.go:64-68 · 锚定版本 v1.14.2 (af6e64c)

客户端嵌入了拨号字段（见出站），但只有 detour 生效。

最简示例

服务端按厂商 / 产品 ID 导出一个键盘，外加插在总线端口 1-2 上的设备：

{
  "services": [
    {
      "type": "usbip-server",
      "tag": "usb-share",
      "listen": "0.0.0.0",
      "devices": [
        { "vendor_id": 1133, "product_id": 49948 },
        { "bus_id": "1-2" }
      ]
    }
  ]
}

客户端只导入总线端口 1-2 上的设备：

{
  "services": [
    {
      "type": "usbip-client",
      "tag": "usb-remote",
      "server": "192.0.2.10",
      "devices": [{ "bus_id": "1-2" }]
    }
  ]
}

说明

• 需要 with_usbip 构建标签，且只为 Linux、Windows 和启用 CGO 的 macOS 构建。在其他平台（包括 iOS）上两种类型仍存在，但会在启动时以 "USB/IP is not included in this build" 失败。
• provider: "default" 只在直接通过 CLI 运行 sing-box 时可用，并需要提升权限；在 macOS 上导出设备还需要禁用系统完整性保护（SIP）。
• 使用 provider: "dynamic" 时，设备在运行时通过 API 服务 共享 —— 来自图形客户端、Dashboard 或 sing-box api 命令。
• 标准 USB/IP 没有加密和鉴权，两个服务也都没有凭据字段。只在可信网络中暴露 usbip-server，或通过客户端的 detour 经隧道访问。

跨内核说明

• Xray-core 和 mihomo 都没有 USB/IP 的对应功能。

源码： option/usbip.go:17-81 · v1.14.2 (af6e64c)