# 本地 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
bash scripts/dev/wsl/check-local-mqtt.sh
```

## 认证与 ACL 冒烟入口

```bash
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 探测。

如果未配置 `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 连接。

## 验收边界

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

- TLS 证书链和客户端校验。
- MQTT 客户端认证账号实际可用性。
- 错误密码拒绝实际结果。
- ACL 越权拒绝实际结果。
- MQTT 3.1 / QoS 1 业务协议联调。
- 遗嘱消息。
- 重复消息幂等。
- 真实控制箱、门锁、插座执行结果。

## 账号记录规则

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