开始使用
在安装完成后，即可在终端直接运行 mqttx 命令。
快速使用
连接
mqttx conn -h 'broker.emqx.io' -p 1883 -u 'admin' -P 'public'
订阅
mqttx sub -t 'hello' -h 'broker.emqx.io' -p 1883
发布
mqttx pub -t 'hello' -h 'broker.emqx.io' -p 1883 -m 'from MQTTX CLI'
性能测试
# Connect Benchmark
mqttx bench conn -c 5000
# Subscribe Benchmark
mqttx bench sub -c 5000 -t bench/%i
# Publish Benchmark
mqttx bench pub -c 5000 -t bench/%i
版本检查
mqttx check
参数介绍
mqttx --help
| 参数 | 描述 |
|---|---|
| -v, --version | 输出当前 MQTT X CLI 的版本号 |
| -h, --help | 展示 mqttx 命令的帮助信息 |
| 命令 | 描述 |
|---|---|
| check | 检查更新 |
| conn | 创建一个连接并连接到 MQTT Broker |
| pub | 向主题发布一条消息 |
| sub | 订阅一个或多个主题 |
| bench | MQTT 性能测试 |
连接
mqttx conn --help
| 参数 | 描述 |
|---|---|
| -V, --mqtt-version <5/3.1.1/3.1> | MQTT 版本，默认为 5 |
| -h, --hostname <HOST> | MQTT Broker 的 Host 地址，默认为 localhost |
| -p, --port <PORT> | MQTT Broker 的端口号 |
| -i, --client-id <ID> | 客户端 ID |
| --no-clean | 取消 clean session 标志位，默认为 true |
| -k, --keepalive <SEC> | MQTT 的 Keep Alive，默认为 30 |
| -u, --username <USER> | 连接到 MQTT Broker 的用户名 |
| -P, --password <PASS> | 连接到 MQTT Broker 的密码 |
| -l, --protocol <PROTO> | 连接时的协议，mqtt 或 mqtts，默认为 mqtt |
| --key <PATH> | key 文件的路径 |
| --cert <PATH> | cert 文件的路径 |
| --ca | ca 证书的文件路径 |
| --insecure | 取消服务器的证书校验 |
| -rp, --reconnect-period <MILLISECONDS> | 自动重连的间隔时间，通过设置为 0 来禁用自动重连，默认为 1000ms |
| --maximun-reconnect-times <NUMBER> | 最大重连次数，默认为 10 次 |
| -up, --user-properties <USERPROPERTIES...> | MQTT 5.0 用户属性，例如：-up "name: mqttx cli" |
| -Wt, --will-topic <TOPIC> | 遗嘱消息的 Topic |
| -Wm, --will-message <BODY> | 遗嘱消息的 Payload |
| -Wq, --will-qos <0/1/2> | 遗嘱消息的 QoS |
| -Wr, --will-retain | 发送的遗嘱消息为保留消息，默认为 false |
| -Wd, --will-delay-interval <SECONDS> | 遗嘱消息延迟间隔，单位为秒 |
| -Wpf, --will-payload-format-indicator | 遗嘱消息是否为 UTF-8 编码的字符数据 |
| -We, --will-message-expiry-interval <SECONDS> | 遗嘱信息的有效期，单位为秒 |
| -Wct, --will-content-type <CONTENTTYPE> | 遗嘱消息内容的描述 |
| -Wrt, --will-response-topic <TOPIC> | 响应信息的主题名称 |
| -Wcd, --will-correlation-data <DATA> | 响应信息的关联数据 |
| -Wup, --will-user-properties <USERPROPERTIES...> | 遗嘱消息的自定义用户属性 |
| -se, --session-expiry-interval <SECONDS> | 会话过期间隔，单位为秒 |
| --rcv-max, --receive-maximum <NUMBER> | 接收消息的最大值 |
| --maximum-packet-size <NUMBER> | 客户端愿意接受的最大数据包大小 |
| --topic-alias-maximum <NUMBER> | 主题别名的最大值 |
| --req-response-info | 客户端要求服务器提供的响应信息 |
| --no-req-problem-info | 客户端向服务器请求问题信息 |
| --save [PATH] | 将参数保存到本地配置文件中，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-config.json |
| --config [PATH] | 从本地配置文件加载参数，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-config.json |
| --help | 展示 conn 命令的帮助信息 |
订阅
mqttx sub --help
| 参数 | 描述 |
|---|---|
| -V, --mqtt-version <5/3.1.1/3.1> | MQTT 版本，默认为 5 |
| -h, --hostname <HOST> | MQTT Broker 的 Host 地址，默认为 localhost |
| -p, --port <PORT> | MQTT Broker 的端口号 |
| -i, --client-id <ID> | 客户端 ID |
| -q, --qos <0/1/2> | 消息的 QoS，默认为 0 |
| --no-clean | 取消 clean session 标志位，默认为 true |
| -t, --topic <TOPIC> | 需要订阅的 Topic |
| -k, --keepalive <SEC> | MQTT 的 Keep Alive，默认为 30 |
| -u, --username <USER> | 连接到 MQTT Broker 的用户名 |
| -P, --password <PASS> | 连接到 MQTT Broker 的密码 |
| -l, --protocol <PROTO> | 连接时的协议，mqtt 或 mqtts，默认为 mqtt |
| -nl, --no_local | MQTT 5.0 订阅选项中的 no local 标识 |
| -rap, --retain-as-published | MQTT 5.0 订阅选项中的 retain as published 标识 |
| -rh, --retain-handling <0/1/2> | MQTT 5.0 订阅选项中的 retain handling 标识 |
| --key <PATH> | key 文件的路径 |
| --cert <PATH> | cert 文件的路径 |
| --ca | ca 证书的文件路径 |
| --insecure | 取消服务器的证书校验 |
| -rp, --reconnect-period <MILLISECONDS> | 自动重连的间隔时间，通过设置为 0 来禁用自动重连，默认为 1000ms |
| --maximun-reconnect-times <NUMBER> | 最大重连次数，默认为 10 次 |
| -up, --user-properties <USERPROPERTIES...> | MQTT 5.0 用户属性，例如：-up "name: mqttx cli" |
| -f, --format <TYPE> | 格式化 Payload，支持 base64、json、hex |
| -v, --verbose | 在接收到的 Payload 前显示当前 Topic |
| -Wt, --will-topic <TOPIC> | 遗嘱消息的 Topic |
| -Wm, --will-message <BODY> | 遗嘱消息的 Payload |
| -Wq, --will-qos <0/1/2> | 遗嘱消息的 QoS |
| -Wr, --will-retain | 发送的遗嘱消息为保留消息，默认为 false |
| -Wd, --will-delay-interval <SECONDS> | 遗嘱消息延迟间隔，单位为秒 |
| -Wpf, --will-payload-format-indicator | 遗嘱消息是否为 UTF-8 编码的字符数据 |
| -We, --will-message-expiry-interval <SECONDS> | 遗嘱信息的有效期，单位为秒 |
| -Wct, --will-content-type <CONTENTTYPE> | 遗嘱消息内容的描述 |
| -Wrt, --will-response-topic <TOPIC> | 响应信息的主题名称 |
| -Wcd, --will-correlation-data <DATA> | 响应信息的关联数据 |
| -Wup, --will-user-properties <USERPROPERTIES...> | 遗嘱消息的自定义用户属性 |
| -se, --session-expiry-interval <SECONDS> | 会话过期间隔，单位为秒 |
| -si, --subscription-identifier <NUMBER> | 订阅标识符 |
| --rcv-max, --receive-maximum <NUMBER> | 接收消息的最大值 |
| --maximum-packet-size <NUMBER> | 客户端愿意接受的最大数据包大小 |
| --topic-alias-maximum <NUMBER> | 主题别名的最大值 |
| --req-response-info | 客户端要求服务器提供的响应信息 |
| --no-req-problem-info | 客户端向服务器请求问题信息 |
| -Cup, --conn-user-properties <USERPROPERTIES...> | MQTT 5.0 的连接用户属性（例如，-Cup "name: mqttx cli"） |
| --save [PATH] | 将参数保存到本地配置文件中，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-config.json |
| --config [PATH] | 从本地配置文件加载参数，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-config.json |
| --help | 展示 sub 命令的帮助信息 |
发布
mqttx pub --help
| 参数 | 描述 |
|---|---|
| -V, --mqtt-version <5/3.1.1/3.1> | MQTT 版本，默认为 5 |
| -h, --hostname <HOST> | MQTT Broker 的 Host 地址，默认为 localhost |
| -p, --port <PORT> | MQTT Broker 的端口号 |
| -i, --client-id <ID> | 客户端 ID |
| -q, --qos <0/1/2> | 消息的 QoS，默认为 0 |
| -t, --topic <TOPIC> | 需要发布的 Topic |
| -m, --message<MSG> | 需要发布的 Payload 消息 |
| -r, --retain | 设置发送消息为 Retain 消息，默认为 fasle |
| -s, --stdin | 从 stdin 中读取信息体 |
| -M, --multiline | 可以通过多行发布多条消息 |
| -u, --username <USER> | 连接到 MQTT Broker 的用户名 |
| -P, --password <PASS> | 连接到 MQTT Broker 的密码 |
| -l, --protocol <PROTO> | 连接时的协议，mqtt 或 mqtts，默认为 mqtt |
| --key <PATH> | key 文件的路径 |
| --cert <PATH> | cert 文件的路径 |
| --ca | ca 证书的文件路径 |
| --insecure | 取消服务器的证书校验 |
| -rp, --reconnect-period <MILLISECONDS> | 自动重连的间隔时间，通过设置为 0 来禁用自动重连，默认为 1000ms |
| --maximun-reconnect-times <NUMBER> | 最大重连次数，默认为 10 次 |
| -up, --user-properties <USERPROPERTIES...> | MQTT 5.0 用户属性，例如：-up "name: mqttx cli" |
| -pf, --payload-format-indicator | 发布信息的有效载荷格式指标 |
| -e, --message-expiry-interval <NUMBER> | 发布信息的有效期，单位为秒 |
| -ta, --topic-alias <NUMBER> | 主题别名，识别主题的值，而不是使用主题名称 |
| -rt, --response-topic <TOPIC> | 作为响应信息的主题名称 |
| -cd, --correlation-data <DATA> | 请求信息的发送者在收到响应信息时用来识别是哪个请求的对比数据 |
| -si, --subscription-identifier <NUMBER> | 订阅标识符 |
| -ct, --content-type <TYPE> | 对发布信息内容的描述 |
| -Wt, --will-topic <TOPIC> | 遗嘱消息的 Topic |
| -Wm, --will-message <BODY> | 遗嘱消息的 Payload |
| -Wq, --will-qos <0/1/2> | 遗嘱消息的 QoS |
| -Wr, --will-retain | 发送的遗嘱消息为保留消息，默认为 false |
| -Wd, --will-delay-interval <SECONDS> | 遗嘱消息延迟间隔，单位为秒 |
| -Wpf, --will-payload-format-indicator | 遗嘱消息是否为 UTF-8 编码的字符数据 |
| -We, --will-message-expiry-interval <SECONDS> | 遗嘱信息的有效期，单位为秒 |
| -Wct, --will-content-type <CONTENTTYPE> | 遗嘱消息内容的描述 |
| -Wrt, --will-response-topic <TOPIC> | 响应信息的主题名称 |
| -Wcd, --will-correlation-data <DATA> | 响应信息的关联数据 |
| -Wup, --will-user-properties <USERPROPERTIES...> | 遗嘱消息的自定义用户属性 |
| -se, --session-expiry-interval <SECONDS> | 会话过期间隔，单位为秒 |
| --rcv-max, --receive-maximum <NUMBER> | 接收消息的最大值 |
| --maximum-packet-size <NUMBER> | 客户端愿意接受的最大数据包大小 |
| --topic-alias-maximum <NUMBER> | 主题别名的最大值 |
| --req-response-info | 客户端要求服务器提供的响应信息 |
| --no-req-problem-info | 客户端向服务器请求问题信息 |
| -Cup, --conn-user-properties <USERPROPERTIES...> | MQTT 5.0 的连接用户属性（例如，-Cup "name: mqttx cli"） |
| --save [PATH] | 将参数保存到本地配置文件中，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-config.json |
| --config [PATH] | 从本地配置文件加载参数，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-config.json |
| --help | 展示 pub 命令的帮助信息 |
性能测试
性能测试命令与普通命令参数基本相同，以下仅列出新增或有变化的参数。
连接性能测试
mqttx bench conn --help
| 参数 | 描述 |
|---|---|
| -c, --count <NUMBER> | 连接数量，默认为 1000 |
| -i, --interval <MILLISECONDS> | 创建连接的间隔时间，默认为 10ms |
| -I, --client-id <ID> | 客户端 ID，支持 %i (索引) 占位符 |
订阅性能测试
mqttx bench sub --help
| 参数 | 描述 |
|---|---|
| -c, --count <NUMBER> | 连接数量，默认为 1000 |
| -i, --interval <MILLISECONDS> | 创建连接的间隔时间，单位为毫秒，默认为 10ms |
| -I, --client-id <ID> | 客户端 ID，支持 %i (索引) 占位符 |
| -t, --topic <TOPIC...> | 需要订阅的 Topic, 支持 %u (用户名), %c (客户端 ID), %i (索引) 占位符 |
| -v, --verbose | 打印接收到的历史消息数量与消息速率 |
发布性能测试
mqttx bench pub --help
| 参数 | 描述 |
|---|---|
| -c, --count <NUMBER> | 连接数量，默认为 1000 |
| -i, --interval <MILLISECONDS> | 创建连接的间隔时间，单位为毫秒，默认为 10ms |
| -im, --message-interval <MILLISECONDS> | 发布消息的间隔时间，单位为毫秒，默认为 1000ms |
| -I, --client-id <ID> | 客户端 ID，支持 %i (索引) 占位符 |
| -t, --topic <TOPIC...> | 需要订阅的 Topic, 支持 %u (用户名), %c (客户端 ID), %i (索引) 占位符 |
| -v, --verbose | 打印发送出的历史消息数量与消息速率 |
典型压测场景
连接量测试
以每 10ms 创建一个连接的速率，创建 10000 个连接，客户端 ID 为 mqttx-bench-%i：
mqttx bench conn -c 10000 -i 10 -I "mqttx-bench-%i"
如果您使用的是 EMQX，在所有连接建立完成后，可以通过 dashboard 或执行 ./bin/emqx_ctl listeners 查看 EMQX 中连接数的信息：
tcp:default
listen_on : :1883
acceptors : 16
proxy_protocol : false
running : true
current_conn : 10000
max_conns : 1024000
吞吐测试
启动 500 个订阅客户端，订阅主题 mqttx/bench/t：
mqttx bench sub -c 500 -t mqttx/bench/t
然后启动 20 个发布客户端，向主题 mqttx/bench/t 发布消息，消息速率为每秒 10 条，消息内容为 mqttx bench test：
mqttx bench pub -c 20 -im 100 -t mqttx/bench/t -m "mqttx bench test"
回到订阅客户端，可以看到接收消息总数和实时消息速率，类似于：
Received total: 10989500, rate: 100000/s
使用配置文件
MQTT X CLI 支持配置的导入与导出，用户能够将命令参数保存到本地配置文件中，以便于下次使用。
配置文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-config.json。
这里以 conn 命令为例，演示如何导出、导入配置：
导出配置
# 保存到默认路径
mqttx conn --save
# 保存到指定路径
mqttx conn --save ../custom/mqttx-cli.json
# 保存到指定路径，并指定格式为 yaml
mqttx conn --save ../custom/mqttx-cli.yaml
导入配置
# 从默认路径导入配置
mqttx conn --config
# 从指定路径导入配置
mqttx conn --config ../custom/mqttx-cli.json
# 从指定路径导入格式为 yaml 的配置
mqttx conn --config ../custom/mqttx-cli.yaml