本地 MQTT 调试环境

环境边界：WSL 本地 Broker 仅用于开发/测试，不代表生产 101.42.38.246 已完成部署。

已核验服务级基线

项目	期望	本轮结果	状态
EMQX 包版本	`5.8.9`	`emqx 5.8.9`	PASS
EMQX 服务状态	`active`	`active`	PASS
EMQX 自启	`enabled`	`enabled`	PASS
MQTTX CLI 路径	`/usr/local/bin/mqttx`	`/usr/local/bin/mqttx`	PASS
MQTTX CLI 版本	`1.13.0`	`1.13.0`	PASS
MQTT TCP	`1883` 监听	`0.0.0.0:1883`	PASS
MQTT TLS	`8883` 监听	`0.0.0.0:8883`	PASS
WebSocket	`8083` 监听	`0.0.0.0:8083`	PASS
WebSocket TLS	`8084` 监听	`0.0.0.0:8084`	PASS
Dashboard	`18083` 监听	`0.0.0.0:18083`	PASS

可重复检查

bash scripts/dev/wsl/check-local-mqtt.sh

认证与 ACL 冒烟入口

cp scripts/dev/wsl/mqtt-smoke.env.example scripts/dev/wsl/mqtt-smoke.env
# 在本地被 Git 忽略的 mqtt-smoke.env 中填写最小权限 MQTT 账号
bash scripts/dev/wsl/mqtt-smoke.sh --check-config
bash scripts/dev/wsl/mqtt-smoke.sh

当前脚本覆盖：

MQTTX CLI 存在性检查。
MQTT 3.1.1。
QoS 1。
允许发布 Topic。
允许订阅 Topic 连接检查。
错误密码拒绝。
越权订阅 Topic 探测。
可选 TLS 发布探测。
可选遗嘱消息观测探测。
可选重复消息发布，用于下游幂等验证取证。

如果未配置 QIPAI_MQTT_USERNAME 和 QIPAI_MQTT_PASSWORD，脚本会输出 SKIP，不得视为认证/ACL 已通过。

本轮验证结果：未配置本地账号时，scripts/dev/wsl/mqtt-smoke.sh 已按预期输出 SKIP。示例文件验证结果：scripts/dev/wsl/mqtt-smoke.env.example 可在 set -u 下安全加载，'$SYS/#' 保持为字面 Topic。

配置注意：

QIPAI_MQTT_DENIED_SUBSCRIBE_TOPIC 默认值为 '$SYS/#'，必须保留引号，避免 shell 把 $SYS 当作本地变量展开。
--check-config 只确认本地账号配置存在，不打印口令，不执行 MQTT 连接。
QIPAI_MQTT_ENABLE_TLS_SMOKE=true 时会对 QIPAI_MQTT_TLS_PROTOCOL://QIPAI_MQTT_TLS_HOST:QIPAI_MQTT_TLS_PORT 执行一次发布探测；本地自签证书可临时使用 QIPAI_MQTT_TLS_INSECURE=true，生产验收必须提供 CA/证书链证据。
QIPAI_MQTT_ENABLE_WILL_SMOKE=true 时会尝试观测遗嘱消息；如果 MQTTX 退出路径被 Broker 视为正常断开，脚本会输出 WARN，仍需结合 Broker 和客户端故障日志验收。
QIPAI_MQTT_ENABLE_IDEMPOTENCY_SMOKE=true 时会向同一 Topic 连续发布相同 idempotencyKey 的消息；脚本只证明重复消息已发出，最终幂等必须由后端/设备日志证明。

验收边界

端口监听正常只证明服务级可用，不能证明以下项目已完成：

TLS 证书链和客户端校验；当前仅有可选发布探测入口。
MQTT 客户端认证账号实际可用性。
错误密码拒绝实际结果。
ACL 越权拒绝实际结果。
MQTT 3.1 / QoS 1 业务协议联调。
遗嘱消息；当前仅有可选观测探测入口。
重复消息幂等；当前仅能发布重复消息，尚未接入下游消费断言。
真实控制箱、门锁、插座执行结果。

账号记录规则

本地 admin 账号只能记录为“已知调试账号”，不得在 Git 中记录口令。
需要区分 Dashboard 管理员账号与 MQTT 客户端认证账号。
MQTT 客户端账号应在后续测试中使用最小权限账号和 ACL。
scripts/dev/wsl/mqtt-smoke.env 已加入 .gitignore，仅允许本地保存，不得提交。

3.6 KiB Raw Blame History