Azure IoT Edge Module基于MQTTSoWS连接时认证失败问题

核心报错为ECONNREFUSED 172.18.0.4:8883，即连接目标IP的8883端口被拒绝，结合当前设备采用MQTT over WebSocket（MQTTS over WS）协议、同代码MQTTS直连设备正常的场景，按以下优先级排查：

1. 端口与协议匹配校验 #

• 默认MQTTS（非WebSocket）协议使用8883端口，而MQTT over WebSocket的标准监听端口通常为443、9443，部分自定义部署的IoT Edge会使用其他端口，你当前配置中指定的8883端口与协议不匹配是最高概率诱因：
  • 先确认当前IoT Edge Hub的WebSocket监听端口，修改Node模块连接配置中的端口参数
  • 在故障设备上执行nc -zv 172.18.0.4 [确认后的WS端口]验证端口可达性，如果是容器部署的Edge Hub，还要确认容器的WS端口已经正确映射到对应docker网络、没有端口冲突

2. SDK传输配置校验 #

Azure IoT Node SDK连接MQTT over WebSocket需要显式指定传输实例，配置错误会导致默认请求8883端口：

• 检查代码是否调用了正确的WebSocket传输实例，正确示例如下：

// 注意此处引入的是MqttWs，而非对应MQTTS协议的Mqtt
const MqttTransport = require('azure-iot-device-mqtt').MqttWs;
const Client = require('azure-iot-device').Client;

const deviceConnectionString = "你的设备连接字符串";
const client = Client.fromConnectionString(deviceConnectionString, MqttTransport);

• 不要混用Mqtt和MqttWs实例，二者对应的传输协议、默认端口完全不同，混用会直接触发端口拒绝报错

3. 网络与防火墙校验 #

• 检查故障设备的出站安全规则，是否允许WS对应端口的TCP请求，有没有本地防火墙、安全组拦截
• 检查IoT Edge Hub的入站规则，是否允许当前故障设备的IP访问WS监听端口

4. 认证信息校验 #

报错附带的Not authorized提示说明端口通后还需要校验身份信息：

• 确认设备连接字符串是否正确，设备ID、对称密钥/证书信息没有填写错误
• 确认对应设备已经在IoT Hub/Edge Hub中完成注册、设备状态为启用
• 若采用X.509证书认证，检查证书有效期、根证书是否已经正确配置到设备受信任列表中

5. 循环报错临时处理 #

循环报错是Azure IoT SDK默认的自动重连机制导致的，排查阶段可以临时关闭自动重连，避免日志刷屏影响定位，问题修复后再开启即可。

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