# 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`。