mqsub 1.0.1

mqsub

mqsub 是一个跨平台的 .NET 全局工具，用于订阅 MQTT 主题并将收到的消息输出到标准输出（stdout）。

安装

从 NuGet 安装（推荐）

dotnet tool install --global mqsub

从本地包安装

dotnet tool install --global --add-source ./packages mqsub

安装为本地工具

# 在项目目录中
dotnet new tool-manifest
dotnet tool install --local mqsub

更新

dotnet tool update --global mqsub

基本用法

mqsub -b tcp://broker.example.com:1883/sensor/#

命令行选项

选项	简写	说明	默认值
--broker	-b	MQTT Broker URI，例如 tcp://broker:1883/topic/#	tcp://localhost:1883 或环境变量 MQSUB_BROKER
--topic	-t	要订阅的主题，可多次指定或用逗号分隔	从 URI 路径提取
--username	-u	用户名（会覆盖 URI 中的用户信息）	无
--password	-p	密码（会覆盖 URI 中的用户信息）	无
--client-id	-i	MQTT Client ID	自动生成 mqsub-{guid}
--qos	-q	服务质量等级，可选 0、1、2	0
--format	-f	输出格式：info（默认）、raw、json、base64、binary	info
--verbose	-v	在 stderr 输出详细日志	false
--help	-h	显示帮助信息	-
--version		显示版本信息	-

URI 格式

Broker URI 支持以下形式：

tcp://broker.example.com:1883
tcp://broker.example.com:1883/sensor/#
ssl://broker.example.com:8883
mqtts://user:pass@broker.example.com:8883/topic1/#,topic2/+

支持的 scheme：

• tcp、mqtt：普通 TCP 连接，默认端口 1883
• ssl、mqtts、tls：TLS 加密连接，默认端口 8883

URI 中的 user:pass@ 和路径中的主题会被自动解析。路径中的多个主题可用逗号 , 分隔。

输出格式

info（默认）

第一行输出本地时间戳（带时区偏移）和主题，第二行输出 payload 内容：

mqsub -b tcp://broker.example.com:1883/sensor/#
# 或显式指定
mqsub -b tcp://broker.example.com:1883/sensor/# -f info

示例输出：

2026-08-18T10:43:18.6140000+08:00 sensor/temp
23.5

raw

将 MQTT 消息 payload 作为 UTF-8 文本输出：

mqsub -b tcp://broker.example.com:1883/sensor/# -f raw

json

每行输出一个 JSON 对象，包含本地时间戳（带时区偏移）、主题和 payload：

mqsub -b tcp://broker.example.com:1883/sensor/# -f json

示例输出：

{"timestamp":"2026-08-18T10:43:18.6140000+08:00","topic":"sensor/temp","payload":"23.5"}

base64

将 payload 以 Base64 编码输出：

mqsub -b tcp://broker.example.com:1883/sensor/# -f base64

binary

将原始二进制 payload 直接写入 stdout：

mqsub -b tcp://broker.example.com:1883/sensor/# -f binary

注意：binary 格式不会自动添加换行符。

身份验证

通过命令行参数

mqsub -b tcp://broker.example.com:1883 -u myuser -p mypass -t sensor/#

通过 URI

mqsub -b tcp://myuser:mypass@broker.example.com:1883/sensor/#

安全提示：命令行参数和 URI 中的密码可能出现在 shell 历史或进程列表中。生产环境建议使用环境变量（见下节）。

环境变量

变量名	说明
MQSUB_BROKER	默认 Broker URI，当命令行未指定 --broker 时使用
MQSUB_PASSWORD	默认密码，优先级低于 --password，但高于 URI 中的密码

示例：

export MQSUB_BROKER=tcp://broker.example.com:1883
export MQSUB_PASSWORD=mysecret
mqsub -u myuser -t sensor/#

示例

订阅本地 Mosquitto 的所有主题

mqsub -b tcp://localhost:1883/#

以 JSON 格式订阅多个主题

mqsub -b ssl://broker.example.com:8883 -t sensor/temp -t sensor/humidity -f json

保存二进制流到文件

mqsub -b tcp://broker.example.com:1883/camera/+/frame -f binary > frames.bin

使用 QoS 1

mqsub -b tcp://broker.example.com:1883/sensor/# -q 1 -v

TLS 连接

使用 ssl://、mqtts:// 或 tls:// scheme 即可启用 TLS。默认使用系统证书链验证服务器证书。

mqsub -b ssl://broker.example.com:8883/sensor/#

退出

按 Ctrl + C 即可安全断开与 Broker 的连接并退出。

安全建议

1. 避免在命令行中直接输入密码，以防止泄露到 shell 历史或进程列表。
2. 优先使用环境变量 MQSUB_PASSWORD 或配置文件（如后续支持）提供密码。
3. 通过 TLS 连接到生产环境的 Broker，避免明文传输凭据和消息。
4. 在 CI/CD 中使用 MQSUB_BROKER 和 MQSUB_PASSWORD 等环境变量，而不是将凭据写入命令行。

开发

构建

dotnet build mqcli.slnx -c Release

测试

dotnet test mqcli.slnx -c Release

打包

dotnet pack mqsub/mqsub.csproj -c Release -o ./packages

许可证

本项目采用 MIT 许可证。