qipai/docs/mqtt-deployment.md

MQTT 部署记录

项目	当前值
Broker 主机	101.42.38.246
Broker 软件	EMQX 5.x（最低 5.3），待生产安装/验证
安装方式	Ubuntu Apt 原生安装，禁止 Docker
安装说明	deploy/emqx/install-ubuntu24-amd64.md
MQTTX	服务器不安装，Windows 可使用
命令行工具	mosquitto-clients 可选
匿名连接	待验证关闭
ACL	已按三个厂商 Topic 固定 deploy/emqx/acl.conf.template，生产未应用
授权配置	已生成 deploy/emqx/authorization.hocon.template，生产未应用
1883	菜单第 3 项/setup.sh --mqtt 可检查，生产未验证
18083	菜单第 3 项/setup.sh --mqtt 可检查；必须限制访问，生产未验证
备份	菜单 6 已检查 EMQX 导出能力与备份目录；生产导出演练待执行
恢复	deploy/backup/backup-restore-runbook.md 已有入口；生产恢复演练待执行

菜单 3 行为

• 先检查 Ubuntu 架构、EMQX 包、systemd、自启、1883/18083、ACL 模板和服务器是否误装 MQTTX。
• 未安装时可由管理员输入 I，已安装时可输入 U；脚本使用 EMQX 官方 Apt 安装脚本并执行 apt-get install -y emqx。
• Codex 不远程执行生产安装。账号、密码及认证数据只从 /etc/qipai/qipai.secrets 建立，脚本和日志不打印凭据。

后端 MQTT 基础

• MQTT.js 5.15.1，协议固定 MQTT 3.1（protocolVersion: 3）。
• QoS 1；订阅 /devicesend/+、/devicewill/+，发布 /deviceaccept/{DeviceID}。
• 持久会话、3 秒自动重连、每次连接后显式恢复订阅。
• 默认消息上限 65536 字节，超限上行拒绝进入业务处理，超限下行不发布。
• /app-api/ready 与 /admin-api/ready 分别返回 MQTT 是否配置、是否连接、订阅是否恢复。
• 生产环境缺少 MQTT 账号或密码时拒绝启动；真实值只写 /etc/qipai/qipai.secrets。

WSL 本地开发 Broker

项目	当前值
用途	本地开发/测试，不代表生产 Broker
EMQX	5.8.9
systemd	active/enabled
MQTTX CLI	/usr/local/bin/mqttx，1.13.0
监听端口	1883、8883、8083、8084、18083
可重复检查	scripts/dev/wsl/check-local-mqtt.sh
认证/ACL 冒烟入口	scripts/dev/wsl/mqtt-smoke.sh，本地账号文件 scripts/dev/wsl/mqtt-smoke.env 不入库
验收边界	未配置本地 MQTT 账号前，认证、ACL、TLS、遗嘱消息、重复消息幂等和真实硬件联调未完成

当前 M06-A 结论

• 已提供可选择安装/更新的 Ubuntu 24.04 amd64 菜单、正式 Topic ACL、后端连接生命周期和可复现单元测试。
• 未在生产 Ubuntu 安装 EMQX，未创建真实设备账号，未执行生产发布/订阅，因此 IOT-001 保持 PARTIAL/BLOCKED_EXTERNAL。