Codex
74 lines
2.7 KiB
Markdown
74 lines
2.7 KiB
Markdown
# 本地 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`，仅允许本地保存，不得提交。
|