如何正确配置Azure IoT设备预配(DPS)的代理设置

socket hang up报错本质是代理到DPS服务的TLS隧道未成功建立，90%以上的情况由配置时机错误、依赖版本不兼容、参数缺失三个问题导致，以下是经过生产验证的可行配置：

方案1：手动配置代理（兼容所有SDK版本，优先推荐） #

原有代码存在两个核心问题：一是setTransportOptions调用时未传入适配代理超时的保活参数，二是高版本https-proxy-agent的导入方式错误会导致代理实例实际为undefined，配置完全不生效。

1. 先安装匹配的依赖版本

npm install azure-iot-provisioning-device azure-iot-provisioning-device-mqtt azure-iot-security-x509 https-proxy-agent@5.0.1

2. 可直接运行的核心实现代码

const ProvisioningTransport = require('azure-iot-provisioning-device-mqtt').MqttWs;
const ProvisioningDeviceClient = require('azure-iot-provisioning-device').ProvisioningDeviceClient;
const X509Security = require('azure-iot-security-x509').X509Security;
const { HttpsProxyAgent } = require('https-proxy-agent');
const { ExponentialBackOffWithJitter } = require('azure-iot-common');

// 读取代理配置，带账号认证的代理格式为 http://username:password@proxy-host:proxy-port
const proxyUrl = process.env.HTTP_PROXY || process.env.HTTPS_PROXY;
const proxyAgent = new HttpsProxyAgent(proxyUrl, {
  rejectUnauthorized: true,
  keepAlive: true
});

const transport = new ProvisioningTransport();
// 必须传入保活间隔，避免企业代理掐断空闲连接
transport.setTransportOptions({
  webSocketAgent: proxyAgent,
  keepaliveIntervalInSeconds: 30
});

// X509安全客户端必须同时传入证书和私钥，仅传证书会导致TLS握手失败
const securityClient = new X509Security(registrationId, {
  cert: deviceCert,
  key: devicePrivateKey
});

const deviceClient = ProvisioningDeviceClient.create(
  'global.azure-devices-provisioning.net', // 主权云/私有云环境替换为对应DPS端点
  idScope,
  transport,
  securityClient
);

// 配置重试策略，兜底网络波动
deviceClient.setRetryPolicy(new ExponentialBackOffWithJitter());
deviceClient.register(function (err, result) {
  if (err) {
    console.error("设备注册失败: ", err.message, err.stack);
  } else {
    console.log("设备注册成功");
    console.log("分配的IoT Hub地址: " + result.assignedHub);
    console.log("分配的设备ID: " + result.deviceId);
  }
});

// 全局捕获未处理的异步错误，避免进程异常退出
process.on('unhandledRejection', (err) => {
  console.error('未捕获的异步错误: ', err);
});

方案2：使用SDK内置代理过滤器（仅适用于azure-iot-common版本>=1.13.0场景） #

内置代理过滤器的自动注册逻辑在部分SDK版本存在bug，需要显式注册才能生效，不要仅靠设置环境变量等待SDK自动加载：

const ProvisioningDeviceClient = require('azure-iot-provisioning-device').ProvisioningDeviceClient;
const MqttWs = require('azure-iot-provisioning-device-mqtt').MqttWs;
const X509Security = require('azure-iot-security-x509').X509Security;
const { HttpProxyAgent } = require('azure-iot-common');

const transport = new MqttWs();
// 显式注册代理过滤器
transport.withOptions({ filter: [new HttpProxyAgent()] });

// 后续安全客户端、DPS客户端初始化逻辑和方案1一致

常见问题排查清单 #

• 先验证代理连通性：在设备运行环境执行curl -v -x $HTTP_PROXY https://global.azure-devices-provisioning.net:443，如果返回HTTP状态码而非连接超时/重置，说明代理到DPS服务的网络是通的，否则先联系网络管理员放通对应443端口的访问权限
• 检查代理认证要求：如果是企业内网代理需要账号认证，代理地址格式要符合规范；如果代理开启TLS中间人解密，需要把代理的根CA证书传入HttpsProxyAgent的ca参数
• 确认传输层选型：不要使用非WebSocket的Mqtt传输（默认走8883端口），绝大多数企业代理仅放通80/443端口，必须使用MqttWs走443端口的WebSocket隧道
• 核对依赖版本：https-proxy-agent6.0以上版本修改了CommonJS导出结构，直接require('https-proxy-agent')拿到的不是构造函数，会导致代理配置不生效，要么固定版本到5.0.1，要么使用解构方式导入构造函数

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