Ubuntu下将USB设备接入Docker容器报错的解决方法

问题复现 #

主机侧已确认ttyUSB设备节点、串口ID映射均正常，但使用--device参数挂载设备启动容器时提示设备不存在：

# 主机设备节点验证
$ ls -l /dev/ttyUSB0
crw-rw---- 1 root dialout 188, 0 Jun 21 20:47 /dev/ttyUSB0

# 串口固定ID映射验证
$ ls -l /dev/serial/by-id
total 0
lrwxrwxrwx 1 root root 13 Jun 21 20:47 usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_1ec67e3b0b86ec11b4cd631719c2d21c-if00-port0 -> ../../ttyUSB0

# 启动容器报错
$ docker run --device /dev/ttyUSB0 alpine
docker: Error response from daemon: error gathering device information while adding custom device "/dev/ttyUSB0": no such file or directory.

排查解决步骤 #

按优先级从高到低操作，每步完成后测试容器启动命令验证是否修复。

• 第一步：排查brltty服务抢占设备
  Ubuntu桌面版默认预装brltty盲文辅助服务，会自动抢占所有ttyUSB类串口设备，锁死设备访问权限，是这个场景下最高发的诱因。

  1. 检查服务状态：systemctl status brltty
  2. 如果服务处于运行状态，直接停止并禁用：

     sudo systemctl stop brltty
     sudo systemctl disable brltty
     

  3. 不需要盲文功能的话直接卸载更彻底：sudo apt remove -y brltty
  4. 重载udev规则让设备节点权限恢复：sudo udevadm control --reload-rules && sudo udevadm trigger，重新插拔一次USB dongle。

• 第二步：修复cgroupv2下Docker的设备访问权限
  Ubuntu 22.04及以上版本默认使用cgroupv2，Docker服务默认没有188号字符设备（USB串口对应的主设备号）的访问权限，会导致读取设备信息失败。

  1. 临时放开权限测试：

     echo 'c 188:* rwm' | sudo tee /sys/fs/cgroup/system.slice/docker.service/devices.allow
     

  2. 永久生效配置：新增udev规则给USB串口设备设置正确权限，将docker组加入设备访问组
     新建/etc/udev/rules.d/99-zigbee-dongle.rules文件，写入以下内容：

     SUBSYSTEM=="tty", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", MODE="0666", GROUP="docker"
     

     注：上述idVendor、idProduct为Sonoff Zigbee 3.0 Dongle Plus（CP2102N芯片版）的默认USB ID，若使用其他芯片版本，可通过lsusb命令查询实际ID替换
  3. 重载规则生效，将当前用户加入docker组避免权限问题：

     sudo udevadm control --reload-rules && sudo udevadm trigger
     sudo usermod -aG docker $USER
     newgrp docker
     

• 第三步：使用固定by-id路径挂载设备
  不建议直接使用/dev/ttyUSB0这类动态分配的设备名，设备重连、主机重启后设备序号可能发生漂移，直接用串口固定ID路径挂载更稳定：

  docker run --device /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_1ec67e3b0b86ec11b4cd631719c2d21c-if00-port0:/dev/ttyUSB0 alpine
  

• 兜底验证方案
  若上述步骤操作后仍有问题，可使用特权模式临时测试，确认硬件层面设备可被容器识别：

  docker run --privileged -v /dev/ttyUSB0:/dev/ttyUSB0 alpine ls /dev/ttyUSB0
  

  若该命令能正常输出设备路径，说明问题仍出在权限/规则配置层面，回头检查前两步的配置是否正确即可。特权模式存在安全风险，禁止长期在生产环境使用。

内容的提问来源于stack exchange，提问作者user709029