阿里云MQTT协议接入

约 1668 字大约 6 分钟

设备接入第三方协议阿里云MQTT

2026-05-12

简介

阿里云MQTT协议是联犀物联网平台对接阿里云IoT生态的协议网关，支持阿里云Link SDK格式的设备接入。设备可使用阿里云标准的MQTT认证方式（HMAC-SHA256/SHA1/MD5）连接到联犀平台，无需修改设备固件即可实现云端互通。

应用场景

存量阿里云设备迁移：已使用阿里云Link SDK的设备，可无缝接入联犀平台
阿里云生态兼容：支持与阿里云IoT平台一致的物模型和消息格式
一型一密/一机一密：支持阿里云标准的安全认证模式

前置条件

协议容器已部署：protocol-aliyun-mqtt 容器运行正常
MQTT Broker 可访问：平台MQTT服务端口 1883 开放
etcd 服务正常：dm.rpc 和 timedjob.rpc 已注册

截图位置：协议管理页面显示 aliyunMqtt 协议状态为"运行中"

产品配置

1. 创建产品

在联犀平台创建产品时，选择 传输协议 为 MQTT，协议类型 选择 aliyunMqtt（显示名称为 阿里Alink协议-mqtt）。

截图位置：产品创建页面，打开主协议下拉框，在"普通设备"分组中找到并选择 阿里Alink协议-mqtt

2. 物模型配置

配置产品的物模型，定义设备需要上报和接收的属性、事件、服务。

3. 协议配置参数

参数	说明	示例值
`productID`	产品ID	`aliyun_test_01`
`protocolCode`	协议编码	`aliyunMqtt`
`authMode`	认证方式	`1` (密钥认证)

设备接入

1. 创建设备

在产品下创建设备，获取设备密钥 deviceSecret。

截图位置：设备列表/详情页面，显示 deviceName 和 secret

2. 阿里云格式凭据生成

ClientID 格式

{productID}.{deviceName}|securemode={mode},signmethod={method},timestamp={timestamp}|

字段	说明
`productID`	产品ID
`deviceName`	设备名称
`securemode`	`3` 预注册模式 / `-2` 自动注册模式
`signmethod`	`hmacsha256` / `hmacsha1` / `hmacmd5`
`timestamp`	毫秒级时间戳

Username 格式

{deviceName}&{productID}

Password 生成

Password 为 HMAC 签名结果，签名内容格式如下：

clientId{clientID}deviceName{deviceName}productKey{productID}timestamp{timestamp}

使用 deviceSecret 作为密钥进行 HMAC 签名。

Python 示例：

import hmac, hashlib, time

productID = 'aliyun_test_01'
deviceName = 'dev001'
deviceSecret = 'testsecret001'
timestamp = str(int(time.time() * 1000))

clientID = f'{productID}.{deviceName}|securemode=3,signmethod=hmacsha256,timestamp={timestamp}|'
username = f'{deviceName}&{productID}'

content = f'clientId{clientID}deviceName{deviceName}productKey{productID}timestamp{timestamp}'
password = hmac.new(deviceSecret.encode(), content.encode(), hashlib.sha256).hexdigest()

print(f'ClientID: {clientID}')
print(f'Username: {username}')
print(f'Password: {password}')

消息格式

属性上报（设备→云）

Topic：

/sys/{productID}/{deviceName}/thing/event/property/post

Payload：

{
  "id": "123",
  "version": "1.0",
  "params": {
    "temperature": {
      "value": 25.5,
      "time": 1778593628940
    }
  },
  "method": "thing.event.property.post"
}

属性设置（云→设备）

Topic：

/sys/{productID}/{deviceName}/thing/service/property/set

Payload：

{
  "id": "456",
  "version": "1.0",
  "params": {
    "temperature": 30
  },
  "method": "thing.service.property.set"
}

事件上报（设备→云）

Topic：

/sys/{productID}/{deviceName}/thing/event/{eventIdentifier}/post

服务调用（云→设备）

Topic：

/sys/{productID}/{deviceName}/thing/service/{serviceIdentifier}

接入示例

mosquitto 命令行测试

1. 设备连接并订阅属性设置

export CLIENT_ID="aliyun_test_01.dev001|securemode=3,signmethod=hmacsha256,timestamp=1778593628940|"
export USERNAME="dev001&aliyun_test_01"
export PASSWORD="87954302c6bbb203f8f386d84574dae4227f1f8cc1bdc8b83407c324edce95c8"

mosquitto_sub -h <mqtt-broker-host> -p 1883 \
  -i "$CLIENT_ID" \
  -u "$USERNAME" \
  -P "$PASSWORD" \
  -t "/sys/aliyun_test_01/dev001/thing/service/property/set"

2. 设备属性上报

mosquitto_pub -h <mqtt-broker-host> -p 1883 \
  -i "$CLIENT_ID" \
  -u "$USERNAME" \
  -P "$PASSWORD" \
  -t "/sys/aliyun_test_01/dev001/thing/event/property/post" \
  -m '{
    "id": "123",
    "version": "1.0",
    "params": {
      "temperature": {
        "value": 25.5,
        "time": 1778593628940
      }
    },
    "method": "thing.event.property.post"
  }'

3. 平台下发属性设置

mosquitto_pub -h <mqtt-broker-host> -p 1883 \
  -i "cloud_publisher_001" \
  -u "$USERNAME" \
  -P "$PASSWORD" \
  -t "/sys/aliyun_test_01/dev001/thing/service/property/set" \
  -m '{
    "id": "456",
    "version": "1.0",
    "params": {
      "temperature": 30
    },
    "method": "thing.service.property.set"
  }'

接入流程图

┌─────────────┐     MQTT连接      ┌─────────────────┐
│   设备端     │ ────────────────→ │  MQTT Broker    │
│ (阿里云SDK)  │                   │  (EMQX/Comqtt)  │
└─────────────┘                   └────────┬────────┘
       ↑                                   │
       │  属性上报/事件上报                  │  认证请求
       │  /sys/{pid}/{dn}/thing/...       │
       │                                   ↓
       │                          ┌─────────────────┐
       │                          │  aliyunMqtt     │
       │                          │  协议容器        │
       │                          │  (协议网关)      │
       │                          └────────┬────────┘
       │                                   │
       │                                   │ NATS/消息转换
       │                                   ↓
       │                          ┌─────────────────┐
       │                          │     dmsvr       │
       │                          │  (设备管理服务)  │
       │                          └─────────────────┘
       │
       └───────────────────────────────────
              属性设置/服务调用
              /sys/{pid}/{dn}/thing/service/...

认证模式说明

securemode	模式	说明
`3`	预注册模式	设备必须在平台预先创建，使用设备级密钥认证
`-2`	自动注册模式	设备首次连接时自动注册，使用产品级密钥认证

自动注册模式

使用 securemode=-2 时，设备首次连接会自动在平台创建设备记录：

aliyun_test_01.dev001|securemode=-2,signmethod=hmacsha256,timestamp=1778593628940|

此时 Password 使用 产品密钥 而非设备密钥进行 HMAC 签名。

常见问题排查

1. 连接被拒绝 "bad user name or password"

原因： HMAC 签名计算错误

排查步骤：

确认 timestamp 为毫秒级（13位数字）

确认签名内容格式正确：

clientId{clientID}deviceName{deviceName}productKey{productID}timestamp{timestamp}

确认 deviceSecret 正确（预注册模式）或 productSecret 正确（自动注册模式）
确认 signmethod 与计算方式一致

2. 消息上报后平台无数据

原因： Topic 格式错误或消息 Payload 格式错误

排查步骤：

确认 Topic 格式：/sys/{productID}/{deviceName}/thing/event/property/post
确认 Payload 为有效 JSON
确认 method 字段值为 thing.event.property.post
检查协议容器日志：docker logs protocol-aliyun-mqtt

3. 设备无法收到平台下发指令

原因： 设备未订阅正确 topic 或已离线

排查步骤：

确认设备已订阅：/sys/{productID}/{deviceName}/thing/service/property/set
确认设备连接保持活跃（MQTT KeepAlive）
检查设备在线状态

4. 协议容器无法启动

原因： etcd 未注册或服务依赖缺失

排查步骤：

检查 etcd 是否有 dm.rpc 和 timedjob.rpc 注册：

docker exec saas-etcd etcdctl get --prefix dg.rpc

检查协议容器日志：
```
docker logs protocol-aliyun-mqtt
```
确认 MQTT Broker 可访问

测试验证

联犀平台测试记录

测试环境： 115 测试环境
测试时间： 2026-05-12
测试协议： aliyunMqtt

测试项	状态	详情
MQTT 连接认证	✅ 通过	HMAC-SHA256 签名验证正确
属性上报（设备→云）	✅ 成功	消息格式转换正确，平台收到数据
属性设置（云→设备）	✅ 成功	设备正确接收并解析
协议容器运行	✅ 正常	端口 9108，etcd 注册正常

测试命令记录：

# 设备凭据
ClientID: aliyun_test_01.dev001|securemode=3,signmethod=hmacsha256,timestamp=1778593628940|
Username: dev001&aliyun_test_01
Password: 87954302c6bbb203f8f386d84574dae4227f1f8cc1bdc8b83407c324edce95c8

# 属性上报测试
mosquitto_pub -h 127.0.0.1 -p 1883 -i "$CLIENT_ID" -u "$USERNAME" -P "$PASSWORD" \
  -t "/sys/aliyun_test_01/dev001/thing/event/property/post" \
  -m '{"id":"123","version":"1.0","params":{"temperature":{"value":25.5,"time":1778593628940}},"method":"thing.event.property.post"}'

# 属性设置测试
mosquitto_pub -h 127.0.0.1 -p 1883 -i "cloud_publisher_001" -u "$USERNAME" -P "$PASSWORD" \
  -t "/sys/aliyun_test_01/dev001/thing/service/property/set" \
  -m '{"id":"456","version":"1.0","params":{"temperature":30},"method":"thing.service.property.set"}'

参考链接

更新日志

2026/5/13 16:43

查看所有更新日志

aac64-docs(aliyunMqtt): 更新阿里云MQTT协议文档截图于 2026/5/13
94722-阿里云MQTT协议接入文档完善于 2026/5/13
952c9-docs: 新增阿里云MQTT协议接入文档于 2026/5/13

物模型

AI交互

阿里云MQTT协议接入