在 Docker Desktop 中使用 USB/IP

引進於 Docker Desktop 版本 4.35.0

注意事項
適用於使用 Hyper-V 後端的 Mac、Linux 和 Windows 版 Docker Desktop。

USB/IP 讓您能夠透過網路分享 USB 裝置，然後可以從 Docker 容器內部存取這些裝置。本頁著重於分享連接到您執行 Docker Desktop 之機器的 USB 裝置。您可以視需要重複下列流程來連接和使用其他 USB 裝置。

注意事項
Docker Desktop VM 核心映像檔已預先設定許多常見 USB 裝置的驅動程式，但 Docker 無法保證所有可能的 USB 裝置都能與此設定搭配使用。

設定和使用

步驟一：執行 USB/IP 伺服器

要使用 USB/IP，您需要執行 USB/IP 伺服器。在本指南中，將使用 jiegec/usbip 所提供的實作。

複製儲存庫。

$ git clone https://github.com/jiegec/usbip
$ cd usbip

執行模擬的人機介面裝置 (HID) 裝置範例。

$ env RUST_LOG=info cargo run --example hid_keyboard

步驟二：啟動具備權限的 Docker 容器

要連接 USB 裝置，請啟動 PID 命名空間設定為 host 的具備權限 Docker 容器

$ docker run --rm -it --privileged --pid=host alpine

步驟三：進入 PID 1 的掛載命名空間

在容器內，進入 init 流程的掛載命名空間，以存取預先安裝的 USB/IP 工具

$ nsenter -t 1 -m

步驟四：使用 USB/IP 工具

現在您可以像在任何其他系統上一樣使用 USB/IP 工具

列出 USB 裝置

要從主機列出可匯出的 USB 裝置

$ usbip list -r host.docker.internal

預期輸出

Exportable USB devices
======================
 - host.docker.internal
      0-0-0: unknown vendor : unknown product (0000:0000)
           : /sys/bus/0/0/0
           : (Defined at Interface level) (00/00/00)
           :  0 - unknown class / unknown subclass / unknown protocol (03/00/00)

連接 USB 裝置

要連接特定 USB 裝置，或在本例中連接模擬鍵盤

$ usbip attach -r host.docker.internal -d 0-0-0

驗證裝置連接

連接模擬鍵盤後，請檢查 /dev/input 目錄中是否有裝置節點

$ ls /dev/input/

範例輸出

event0  mice

步驟五：在另一個容器中使用連接的裝置

當初始容器持續執行以保持 USB 裝置運作時，您可以從另一個容器存取連接的裝置。例如

使用連接的裝置啟動新的容器。

$ docker run --rm -it --device "/dev/input/event0" alpine

安裝 evtest 之類的工具來測試模擬鍵盤。
$ apk add evtest $ evtest /dev/input/event0

與裝置互動，並觀察輸出。

範例輸出

Input driver version is 1.0.1
Input device ID: bus 0x3 vendor 0x0 product 0x0 version 0x111
...
Properties:
Testing ... (interrupt to exit)
Event: time 1717575532.881540, type 4 (EV_MSC), code 4 (MSC_SCAN), value 7001e
Event: time 1717575532.881540, type 1 (EV_KEY), code 2 (KEY_1), value 1
Event: time 1717575532.881540, -------------- SYN_REPORT ------------
...

重要
初始容器必須持續執行才能維持與 USB 裝置的連線。結束容器將會停止裝置運作。