documentation: Add USB/IP server and client

2026-06-17 18:53:38 +08:00
parent a23c66fa65
commit 70a767a14a
15 changed files with 337 additions and 7 deletions
@@ -256,7 +256,9 @@ Fragment TLS handshake into multiple TLS records to bypass firewalls.

 !!! question "Since sing-box 1.14.0"

-==Linux/macOS/Windows only, requires elevated privileges==
+!!! quote ""
+
+    Only supported on Linux, macOS, and Windows, and requires elevated privileges.

 Inject a forged TLS ClientHello carrying this SNI before the real one,
 to fool SNI-filtering middleboxes that permit specific hostnames.
@@ -248,7 +248,9 @@ UDP 连接超时时间。

 !!! question "自 sing-box 1.14.0 起"

-==仅 Linux/macOS/Windows，需要管理员权限==
+!!! quote ""
+
+    仅支持 Linux、macOS 和 Windows，需要提升的权限。

 在真实 ClientHello 之前注入携带本字段所指定 SNI 的伪造 TLS ClientHello，
 用于欺骗仅放行特定主机名的 SNI 过滤中间盒。
@@ -8,6 +8,10 @@ icon: material/new-box

 The sing-box API service is a gRPC server for observing and controlling the running sing-box instance.

+It can be accessed by the [sing-box graphical clients](/clients/) for iOS, macOS, and
+Android (via the Remote Control feature), or the
+[sing-box dashboard](https://github.com/SagerNet/sing-box-dashboard).
+
 The server also accepts [gRPC-Web](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md) requests,
 including the WebSocket transport of [@improbable-eng/grpc-web](https://github.com/improbable-eng/grpc-web)
 for bidirectional streaming methods.
@@ -8,6 +8,8 @@ icon: material/new-box

 sing-box API 服务是用于观察与控制正在运行的 sing-box 实例的 gRPC 服务器。

+它可以由 iOS、macOS 和 Android 上的 [sing-box 图形客户端](/zh/clients/)（通过 Remote Control 功能）或 [sing-box dashboard](https://github.com/SagerNet/sing-box-dashboard) 访问。
+
 服务器同时接受 [gRPC-Web](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md) 请求,
 包括用于双向流方法的 [@improbable-eng/grpc-web](https://github.com/improbable-eng/grpc-web) WebSocket 传输。

@@ -30,6 +30,8 @@ icon: material/new-box
 | `ocm`             | [OCM](./ocm)                          |
 | `resolved`        | [Resolved](./resolved)                |
 | `ssm-api`         | [SSM API](./ssm-api)                  |
+| `usbip-server`    | [USB/IP Server](./usbip-server)       |
+| `usbip-client`    | [USB/IP Client](./usbip-client)       |

 #### tag

@@ -30,6 +30,8 @@ icon: material/new-box
 | `ocm`             | [OCM](./ocm)                          |
 | `resolved`        | [Resolved](./resolved)                |
 | `ssm-api`         | [SSM API](./ssm-api)                  |
+| `usbip-server`    | [USB/IP Server](./usbip-server)       |
+| `usbip-client`    | [USB/IP Client](./usbip-client)       |

 #### tag

@@ -0,0 +1,78 @@
+---
+icon: material/new-box
+---
+
+!!! question "Since sing-box 1.14.0"
+
+# USB/IP Client
+
+USB/IP Client service imports remote USB devices over [USB/IP](https://usbip.sourceforge.net/),
+exported by the [USB/IP Server](/configuration/service/usbip-server/).
+
+Available on Linux, Windows, and macOS (macOS requires a build with CGO). Not available on iOS.
+
+The server must be a sing-box (or sing-usbip) server.
+
+### Structure
+
+```json
+{
+  "type": "usbip-client",
+
+  ... // Dial Fields
+
+  "server": "",
+  "server_port": 0,
+  "devices": []
+}
+```
+
+!!! info "Difference from the official USB/IP protocol"
+
+    sing-box uses [sing-usbip](https://github.com/SagerNet/sing-usbip), which uses an additional
+    set of protocols to support enhancements such as hotplug, while remaining interoperable with
+    the standard USB/IP protocol.
+
+### Dial Fields
+
+See [Dial Fields](/configuration/shared/dial/) for details.
+
+Only `detour` takes effect.
+
+### Fields
+
+#### server
+
+==Required==
+
+The remote `usbip-server` address.
+
+#### server_port
+
+The remote `usbip-server` port. Defaults to `3240`.
+
+#### devices
+
+List of device matches selecting which remote devices to import. If empty, all exported devices
+are imported.
+
+Object format:
+
+```json
+{
+  "bus_id": "",
+  "vendor_id": 0,
+  "product_id": 0,
+  "serial": ""
+}
+```
+
+Object fields:
+
+- `bus_id`: USB bus ID, e.g. `1-2`.
+- `vendor_id`: USB vendor ID, as a number.
+- `product_id`: USB product ID, as a number.
+- `serial`: Device serial number.
+
+Within one object, all specified fields must match; multiple objects are combined as a union. At
+least one field is required.
@@ -0,0 +1,73 @@
+---
+icon: material/new-box
+---
+
+!!! question "自 sing-box 1.14.0 起"
+
+# USB/IP Client
+
+USB/IP Client 服务通过 [USB/IP](https://usbip.sourceforge.net/) 导入由 [USB/IP Server](/zh/configuration/service/usbip-server/) 导出的远程 USB 设备。
+
+可用于 Linux、Windows 和 macOS（macOS 需要使用 CGO 构建）。不支持 iOS。
+
+服务端必须是 sing-box（或 sing-usbip）服务端。
+
+### 结构
+
+```json
+{
+  "type": "usbip-client",
+
+  ... // 拨号字段
+
+  "server": "",
+  "server_port": 0,
+  "devices": []
+}
+```
+
+!!! info "与官方 USB/IP 协议的区别"
+
+    sing-box 使用 [sing-usbip](https://github.com/SagerNet/sing-usbip)，它使用一套附加协议来支持热插拔等增强功能，但仍然可以与标准 USB/IP 互操作。
+
+### 拨号字段
+
+参阅 [拨号字段](/zh/configuration/shared/dial/) 了解详情。
+
+仅 `detour` 生效。
+
+### 字段
+
+#### server
+
+==必填==
+
+远程 `usbip-server` 地址。
+
+#### server_port
+
+远程 `usbip-server` 端口。默认为 `3240`。
+
+#### devices
+
+设备匹配列表，用于选择要导入的远程设备。如果为空，则导入所有已导出的设备。
+
+对象格式：
+
+```json
+{
+  "bus_id": "",
+  "vendor_id": 0,
+  "product_id": 0,
+  "serial": ""
+}
+```
+
+对象字段：
+
+- `bus_id`：USB 总线 ID，例如 `1-2`。
+- `vendor_id`：USB 供应商 ID，为数字。
+- `product_id`：USB 产品 ID，为数字。
+- `serial`：设备序列号。
+
+在一个对象内，所有指定的字段都必须匹配；多个对象之间取并集。至少需要一个字段。
@@ -0,0 +1,83 @@
+---
+icon: material/new-box
+---
+
+!!! question "Since sing-box 1.14.0"
+
+# USB/IP Server
+
+USB/IP Server service exports local USB devices over [USB/IP](https://usbip.sourceforge.net/),
+to be imported by the [USB/IP Client](/configuration/service/usbip-client/) or a standard USB/IP
+client.
+
+Available on Linux, Windows, and macOS (macOS requires a build with CGO, and exporting devices
+requires disabling System Integrity Protection). Not available on iOS.
+
+### Structure
+
+```json
+{
+  "type": "usbip-server",
+
+  ... // Listen Fields
+
+  "provider": "",
+  "devices": []
+}
+```
+
+!!! info "Difference from the official USB/IP protocol"
+
+    sing-box uses [sing-usbip](https://github.com/SagerNet/sing-usbip), which uses an additional
+    set of protocols to support enhancements such as hotplug, while remaining interoperable with
+    the standard USB/IP protocol.
+
+### Listen Fields
+
+See [Listen Fields](/configuration/shared/listen/) for details.
+
+`listen_port` defaults to `3240`.
+
+### Fields
+
+#### provider
+
+The device source provider.
+
+- `default`: Exports the local devices matched by `devices`. The default value.
+- `dynamic`: Devices are provided at runtime through a [sing-box API](/configuration/service/api/)
+  client instead of from configuration, on supported platforms: the sing-box graphical clients on
+  [macOS](/clients/apple/) and [Android](/clients/android/), and Chromium-based browsers with
+  [sing-box Dashboard](https://github.com/SagerNet/sing-box-dashboard).
+
+!!! quote ""
+
+    The `default` provider is only supported when running directly via the CLI on Linux, Windows,
+    and macOS, and requires elevated privileges.
+
+#### devices
+
+==Required== with the `default` provider.
+
+List of device matches selecting which local USB devices to export.
+
+Object format:
+
+```json
+{
+  "bus_id": "",
+  "vendor_id": 0,
+  "product_id": 0,
+  "serial": ""
+}
+```
+
+Object fields:
+
+- `bus_id`: USB bus ID, e.g. `1-2`.
+- `vendor_id`: USB vendor ID, as a number.
+- `product_id`: USB product ID, as a number.
+- `serial`: Device serial number.
+
+Within one object, all specified fields must match; multiple objects are combined as a union. At
+least one field is required.
@@ -0,0 +1,73 @@
+---
+icon: material/new-box
+---
+
+!!! question "自 sing-box 1.14.0 起"
+
+# USB/IP Server
+
+USB/IP Server 服务通过 [USB/IP](https://usbip.sourceforge.net/) 导出本地 USB 设备，供 [USB/IP Client](/zh/configuration/service/usbip-client/) 或标准 USB/IP 客户端导入。
+
+可用于 Linux、Windows 和 macOS（macOS 需要使用 CGO 构建，且导出设备需要禁用系统完整性保护）。不支持 iOS。
+
+### 结构
+
+```json
+{
+  "type": "usbip-server",
+
+  ... // 监听字段
+
+  "provider": "",
+  "devices": []
+}
+```
+
+!!! info "与官方 USB/IP 协议的区别"
+
+    sing-box 使用 [sing-usbip](https://github.com/SagerNet/sing-usbip)，它使用一套附加协议来支持热插拔等增强功能，但仍然可以与标准 USB/IP 互操作。
+
+### 监听字段
+
+参阅 [监听字段](/zh/configuration/shared/listen/) 了解详情。
+
+`listen_port` 默认为 `3240`。
+
+### 字段
+
+#### provider
+
+设备来源提供者。
+
+- `default`：导出由 `devices` 匹配的本地设备。默认值。
+- `dynamic`：设备在运行时通过 [sing-box API](/zh/configuration/service/api/) 客户端提供，而非来自配置文件，支持的平台包括 [macOS](/zh/clients/apple/) 和 [Android](/zh/clients/android/) 上的 sing-box 图形客户端，以及配合 [sing-box Dashboard](https://github.com/SagerNet/sing-box-dashboard) 的基于 Chromium 的浏览器。
+
+!!! quote ""
+
+    `default` 提供者仅支持通过 CLI 直接运行在 Linux、Windows 和 macOS 上，并且需要提升的权限。
+
+#### devices
+
+使用 `default` 提供者时 ==必填==。
+
+设备匹配列表，用于选择要导出的本地 USB 设备。
+
+对象格式：
+
+```json
+{
+  "bus_id": "",
+  "vendor_id": 0,
+  "product_id": 0,
+  "serial": ""
+}
+```
+
+对象字段：
+
+- `bus_id`：USB 总线 ID，例如 `1-2`。
+- `vendor_id`：USB 供应商 ID，为数字。
+- `product_id`：USB 产品 ID，为数字。
+- `serial`：设备序列号。
+
+在一个对象内，所有指定的字段都必须匹配；多个对象之间取并集。至少需要一个字段。
@@ -678,7 +678,11 @@ Fragment TLS handshake into multiple TLS records to bypass firewalls.

 !!! question "Since sing-box 1.14.0"

-==Client only, Linux/macOS/Windows only, requires elevated privileges==
+==Client only==
+
+!!! quote ""
+
+    Only supported on Linux, macOS, and Windows, and requires elevated privileges.

 Inject a forged TLS ClientHello carrying a whitelisted SNI before the real one,
 to fool SNI-filtering middleboxes that permit specific hostnames.
@@ -673,7 +673,11 @@ ECH 配置路径，PEM 格式。

 !!! question "自 sing-box 1.14.0 起"

-==仅客户端，仅 Linux/macOS/Windows，需要提权==
+==仅客户端==
+
+!!! quote ""
+
+    仅支持 Linux、macOS 和 Windows，需要提升的权限。

 在真实 ClientHello 之前注入一个伪造的、携带白名单 SNI 的 TLS ClientHello，
 以欺骗基于 SNI 过滤的中间盒放行连接。
@@ -194,6 +194,8 @@ nav:
          - CCM: configuration/service/ccm.md
          - OCM: configuration/service/ocm.md
          - Hysteria Realm: configuration/service/hysteria-realm.md
+          - USB/IP Server: configuration/service/usbip-server.md
+          - USB/IP Client: configuration/service/usbip-client.md
 markdown_extensions:
  - toc:
      slugify: !!python/object/apply:pymdownx.slugs.slugify
@@ -51,7 +51,7 @@ func (o *USBIPServerServiceOptions) UnmarshalJSON(content []byte) error {

 type USBIPClientServiceOptions struct {
 	DialerOptions
-	Server  string             `json:"server,omitempty"`
+	ServerOptions
 	Devices []USBIPDeviceMatch `json:"devices,omitempty"`
 }

@@ -13,7 +13,6 @@ import (
 	"github.com/sagernet/sing-box/option"
 	"github.com/sagernet/sing-usbip"
 	E "github.com/sagernet/sing/common/exceptions"
-	M "github.com/sagernet/sing/common/metadata"
 )

 type ClientService struct {
@@ -37,7 +36,7 @@ func NewClientService(ctx context.Context, logger log.ContextLogger, tag string,
 	inner, err := usbip.NewClientService(ctx, usbip.ClientOptions{
 		Logger:        logger,
 		Dialer:        serviceDialer,
-		ServerAddress: M.ParseSocksaddr(options.Server),
+		ServerAddress: options.ServerOptions.Build(),
 		Devices:       toDeviceMatches(options.Devices),
 	})
 	if err != nil {