模组不出现或不识卡

这页按现象列出模组与 SIM 卡的常见问题。下面用到的 lsusb、dmesg 都在主机上执行。

「添加设备」里找不到模组

可能的原因：

模组没通电，或供电不足。多块模组共用 hub 时尤其常见。
主机系统还没识别出它。
容器看不到主机的 /dev。
「设置 › 设备接管」里打开了「只接管清单内的设备」，而这台不在清单里。

怎么处理：

在主机上运行 lsusb，找 Quectel 的厂商 ID 2c7c。没有它，检查供电与线缆，多块模组用带独立供电的 hub。
运行 ls /dev/ttyUSB* /dev/cdc-wdm*，确认有设备节点。
用 Docker 部署时，在容器里运行同一条命令，节点数量应与主机一致。不一致时检查 /dev:/dev 挂载，见用 Docker 安装。
在「添加设备」里点「重新扫描」。
仍然没有，检查「设置 › 设备接管」里的「设备接管清单」。

容器里看得见节点但打不开

可能的原因：

日志里有 operation not permitted 一类报错：容器没有放行这些设备的访问权限。

怎么处理：

在 compose 文件里补上 device_cgroup_rules 三条，用 docker compose up -d --force-recreate 重建容器。写法见用 Docker 安装。

/dev 要整个挂载，不要用 devices: 逐个列出。逐个列出的节点在模组重新枚举后就失效了。

模组出现后又消失

可能的原因：

模组正在重启。重启模组、切换卡槽、写入模组配置都会触发。
USB hub 端口卡住了，见模组掉出 USB 总线，一直不回来。

怎么处理：

等 20 到 30 秒。模组重启后会以新的节点重新出现，nSIM 按 IMEI 自动认回，设备 ID 和名称都不变。
运行 dmesg | tail -50。看到 unable to enumerate USB device，按模组掉出 USB 总线，一直不回来处理。
模组已插回、列表却一直没变化，在「设备」页点「重新扫描 USB 设备」。

模组掉出 USB 总线，一直不回来

可能的原因：

一次碰线或接触抖动让 USB 枚举失败，Linux 内核随后永久放弃这个端口。模组硬件还连着，放多久都不会自己回来。这通常不是硬件坏了，模组和卡都没事。

确认方法：读 hub 的端口状态。<bus>:<hubdev> 换成 lsusb 里那个 hub 的总线号和设备号。

lsusb -v -s <bus>:<hubdev> 2>/dev/null | grep "Port [0-9]:"

状态位	含义
`0x0503`	正常
`0x0101`	卡住：设备连着，但端口没有启用
`0x0100`	空口

怎么处理：

nSIM 会自动处理：模组失踪一段时间后，它把那个端口关一下再打开。用 Docker 部署时要满足两个前提，见用 Docker 安装：

compose 里挂载了 /sys/devices:/hostsys/devices。
config.yaml 里写了 usb_recovery: { sysfs_write_root: /hostsys }。

要手动恢复，在主机上运行下面两行。路径里的 hub 与端口号按你的情况替换：

P=/sys/bus/usb/devices/<hub>/<hub>:1.0/<hub>-port<N>/disable
echo 1 > $P; sleep 6; echo 0 > $P

设备一直是「离线」或「控制面恢复中」

可能的原因：

nSIM 接管了这台设备，但和模组的控制口通信不上。各状态的含义见设备状态与指示器。

怎么处理：

等一两分钟。「控制面恢复中」这类过渡状态一般会自己恢复。
看「状态」页签横幅上写的原因。
多台用 QMI 控制的模组同时掉线，而 lsusb 与设备节点都还在：重启 nSIM。
当前控制面一直起不来，可以在「模组」页签换一个控制面试试，见设备状态与指示器。

卡插着却显示「无 SIM 卡」

可能的原因：

常见的是模组的「SIM 热插拔检测」设反了：模组误以为卡被拔出，给卡断了电。运行中拔插卡表现正常，并不能证明设置是对的。只有模组重启后卡还在，才说明设置正确。

其次是卡本身的问题：设了 PIN 码、损坏或接触不良。

怎么处理：

看「设备」页「模组配置漂移」里「SIM 热插拔检测」一项的说明：

说明的开头	处理
「SIM 卡已就绪，但检测结果为未插卡」	设反了，下次重启模组时卡会断电。点「重启验证」
「检测结果为已插卡，但 SIM 卡未就绪」	与检测设置无关，是卡的问题。取下卡检查 PIN、接触与卡本身
「热插拔检测未启用」	运行中插拔卡后，要重启模组才能识别。想改就点「重启验证」

点「重启验证」前，先排除物理问题：换个 USB 口、换个 hub、重新插卡。坏的 hub 也会让检测读数出错。

不要用 AT 命令自己改这一项。nSIM 会在验证失败时自动改回。

设了 PIN 码的卡用不了

可能的原因：

nSIM 界面上没有输入 SIM PIN 的地方。

怎么处理：

把卡插到手机里关掉 PIN 码，再插回模组。

运行中换卡后，新卡迟迟认不出来

可能的原因：

模组的「SIM 热插拔检测」没有启用。关着时，运行中插进去的卡要等 nSIM 定期重置 SIM 接口才认得出，可能要几分钟。

怎么处理：

等几分钟，或重启模组。想让以后几秒内就认出，按卡插着却显示「无 SIM 卡」的方法用「重启验证」打开热插拔检测。

重启后网卡名变了

wwan0、ttyUSB2 这类名字每次 USB 枚举都可能重排，这是正常的。nSIM 按 IMEI 认设备，界面上的设备 ID 和名称不变。写脚本或调接口时用设备 ID，不要写死网卡名或 /dev 路径。