USB/IP — sing-box

دو سرویس دستگاه‌های USB را از طریق USB/IP به اشتراک می‌گذارند: usbip-server دستگاه‌های محلی را صادر می‌کند و usbip-client دستگاه‌ها را از یک سرور راه‌دور وارد می‌کند. هر دو بر پایهٔ sing-usbip ساخته شده‌اند که بهبودهایی مانند اتصال داغ (hotplug) را روی پروتکل استاندارد می‌افزاید و در عین حال با آن سازگار می‌ماند: یک کلاینت استاندارد USB/IP می‌تواند از usbip-server وارد کند، اما usbip-client به سرور sing-box ‏(sing-usbip) نیاز دارد.

سرور — usbip-server

type: "usbip-server" زیر services[]:

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
provider	string	default	default | dynamic	منبع دستگاه‌های صادرشده. default دستگاه‌های محلی منطبق با devices را صادر می‌کند (فقط اجرای CLI روی Linux،‏ Windows و macOS، با دسترسی ارتقایافته). dynamic در عوض دستگاه‌ها را در زمان اجرا از یک کلاینت API در sing-box می‌گیرد — کلاینت‌های گرافیکی در macOS و Android، یا sing-box Dashboard در یک مرورگر مبتنی بر Chromium.

منبع: 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، مثلاً 1-2.
vendor_id	uint16	(any)	<uint16>	شناسهٔ سازندهٔ USB به‌صورت عدد JSON (دهدهی — مثلاً 1133 برای 0x046d).
product_id	uint16	(any)	<uint16>	شناسهٔ محصول USB به‌صورت عدد JSON.
serial	string	(any)	<string>	شمارهٔ سریال دستگاه.

منبع: option/usbip.go:70-75 · ثابت‌شده در v1.14.2 (af6e64c)

همهٔ فیلدهای تنظیم‌شده در یک شیء باید تطبیق داشته باشند؛ چند شیء به‌صورت اجتماع ترکیب می‌شوند. هر شیء دست‌کم یک فیلد لازم دارد.

کلاینت — usbip-client

type: "usbip-client" زیر services[]:

فیلد	نوع	پیش‌فرض	مقادیر مجاز	توضیحات
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 اثر دارد.

مثال حداقلی

سروری که یک صفحه‌کلید را با شناسهٔ سازنده / محصول صادر می‌کند، به‌علاوهٔ هر چه به پورت گذرگاه 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 و macOS با CGO ساخته می‌شود. در جاهای دیگر (از جمله iOS) هر دو نوع وجود دارند اما هنگام راه‌اندازی با "USB/IP is not included in this build" شکست می‌خورند.
• provider: "default" فقط وقتی sing-box مستقیماً از CLI اجرا شود کار می‌کند و به دسترسی ارتقایافته نیاز دارد؛ صادر کردن در macOS افزون بر آن غیرفعال‌کردن System Integrity Protection را لازم دارد.
• با 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)