qipai/docs/devlogs/2026-06-22-M06-A-Broker与MQTT基础.md

M06-A Broker 与 MQTT 基础

• 日期：2026-06-22
• 起始 commit：a8c3e7d
• 工程 commit：c140613
• ENGINEERING_DELTA=YES
• 子阶段状态：PARTIAL/BLOCKED_EXTERNAL；可独立工程内容已完成并 push，游标推进 M06-B

工程增量

• 引入 MQTT.js 5.15.1，固定 MQTT 3.1（protocolVersion: 3）和 QoS 1。
• 后端启动时连接 Broker，使用持久会话、3 秒自动重连，并在每次连接后显式恢复 /devicesend/+、/devicewill/+。
• 下行只允许 /deviceaccept/{DeviceID}；DeviceID 校验限制为安全字符和 64 字符以内。
• 上下行消息默认限制 64 KiB；超限上行拒绝进入后续处理，超限下行不发布。
• ready 接口新增 MQTT 已配置、真实连接和订阅恢复三层状态。
• 生产环境要求 MQTT 用户名和密码成对存在，缺失时拒绝启动，凭据不写日志。
• 菜单 3 支持管理员选择安装/更新 EMQX，并检查架构、systemd、端口、包架构和服务器未安装 MQTTX。
• ACL 切换为正式三个厂商 Topic，后端账号和单设备账号使用最小权限。

验证

• npm test：退出码 0，M01-A 至 M05-D 全量回归及 M06-A MQTT 测试通过。
• scripts/dev/windows/test-all.ps1：代码测试、构建、迁移计划、工作区和文档一致性通过；新文件暂存前完整性门禁按预期提示，显式暂存后复检通过。
• WSL bash -n：setup.sh、scripts/setup/emqx.sh、mqtt-smoke.sh 退出码 0。
• WSL EMQX：5.8.9、active/enabled、1883/8883/8083/8084/18083 均通过。
• WSL MQTT 认证冒烟：因本地 Git 忽略凭据未配置而 SKIP，未伪造通过。
• 工程 commit 已 push，HEAD == origin/main == c1406137186d857c81180eb3643d385d05e3bb03。

外部阻塞

生产 Ubuntu 的 EMQX 安装、正式账号、ACL、端口限制、备份和真实发布订阅尚未由管理员执行；M06-A 因此保持 PARTIAL/BLOCKED_EXTERNAL，但不阻塞 M06-B 设备资产模型。

后续

执行游标进入 M06-B：设备资产、能力和拓扑。