blp/railwaysystem
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1def568f24e17248c2dc7fd34fa5b04f92cf9f18
railwaysystem/RuoYi-Vue/docs/mqtt_usage_and_status.md
T

259 lines
11 KiB
Markdown
Raw Normal View History

refactor(iot): 移除 MQTT 传输层，仅保留设备开放接口与门禁写操作策略
2026-11-10 16:06:23 +08:00
# MQTT 使用情况与生效状态分析
> **分析对象**：RuoYi-Vue（`railwaysystem`）全部模块
> **分析时间**：2026-11-10
> **分析方式**：源码静态梳理 + 运行时探测（进程、端口、Broker 连通性、日志），**未修改任何代码**
---
## 目录
- [1. 结论摘要](#1-结论摘要)
- [2. MQTT 功能清单](#2-mqtt-功能清单)
- [2.1 连接与消息通道](#21-连接与消息通道)
- [2.2 上行：设备 → 平台（5 个订阅主题）](#22-上行设备--平台5-个订阅主题)
- [2.3 下行：平台 → 设备](#23-下行平台--设备)
- [2.4 运维与辅助](#24-运维与辅助)
- [3. 相关代码文件清单](#3-相关代码文件清单)
- [4. 生效状态分析](#4-生效状态分析)
- [4.1 配置层](#41-配置层)
- [4.2 运行时证据](#42-运行时证据)
- [4.3 日志证据](#43-日志证据)
- [4.4 断连时的代码行为](#44-断连时的代码行为)
- [4.5 功能可用性对照](#45-功能可用性对照)
- [5. 判断依据与恢复方向](#5-判断依据与恢复方向)
---
## 1. 结论摘要
| 维度 | 结论 |
|---|---|
| 配置状态 | **已启用**：`enabled=true`、`mock=false`、`protocol-verified=true`、`real-device-write-enabled=true` |
| 运行状态 | **当前未生效（连接断开）**：应用进程对 Broker 处于 `SYN_SENT`，健康检查每约 30s 重连并持续失败 |
| 消息收发 | **上行不可用**（未订阅，收不到任何上行报文）；**下行不可用**（命令派发前即判失败） |
| 代码可用性 | **链路完好**：2026-11-09 日志中 27 次连接成功，并有真实上行报文处理记录 |
| 根因定位 | **环境问题，非代码缺陷**：配置的 Broker `192.168.1.202:1883` 网络不可达；本机 `127.0.0.1:1883` 实际运行着 mosquitto，但配置未指向 |
> 一句话结论：**MQTT 代码与配置都已就绪，但当前连不上配置的 Broker，所有门禁上下行功能处于停摆状态。**
---
## 2. MQTT 功能清单
### 2.1 连接与消息通道
| # | 功能点 | 说明 | 关键代码 |
|---|---|---|---|
| 1 | 客户端建立与重连 | 启动异步连接；失败后由 `iot-mqtt-health` 线程每 30s 兜底重连 | `MqttClientManager#connect / startHealthExecutor` |
| 2 | 启动自动订阅 | 5 个上行主题，QoS 1；重连后 `resubscribe()` 恢复订阅 | `MqttClientManager#resubscribe` |
| 3 | 消息分发 | 按主题分发至业务监听器，并发布 `MqttMessageEvent`；单监听器异常隔离 | `MqttMessageDispatcher#dispatch` |
| 4 | 报文留痕 | 收/发报文写入 `lock_mqtt_log`，payload 脱敏为 `[redacted]` | `LockMqttLogServiceImpl` |
### 2.2 上行：设备 → 平台（5 个订阅主题）
| # | 功能点 | 主题 | 处理结果 |
|---|---|---|---|
| 5 | 网关上下线 | `ydlink/+/thing/onoff_line` | 更新网关在线状态 |
| 6 | 属性设置响应 | `ydlink/+/thing/property/set_response` | 命令状态机推进 |
| 7 | 远程开关锁响应 | `ydlink/+/thing/action/execute_response` | 命令状态机推进 |
| 8 | 授权批量下发回执 | `ydlink/+/thing/data/batch_report` | 授权命令确认 / 拒绝 |
| 9 | 开门记录上报 | `ydlink/+/thing/event/trigger` | 写入开门记录 |
| 10 | 信号/电量上报 | `ydlink/+/thing/event/trigger`（op=RSSI） | 更新设备信号值 |
### 2.3 下行：平台 → 设备
| # | 功能点 | 触发入口 | 说明 |
|---|---|---|---|
| 11 | 门锁授权下发 / 撤销 | 学员入住、退宿、换宿 | 事务提交后派发（outbox 模式） |
| 12 | 远程开锁 / 关锁 | 管理端门锁操作 | 同上 |
| 13 | 网关属性设置（校时、网络参数） | 管理端网关管理 | 同上 |
| 14 | 命令补偿重发 | `LockCommandRetryTask`（每 60s） | **`retry-task-enabled=false`，当前不执行** |
| 15 | 派发安全门禁 | `RealIotSecurityGate` | 环境隔离、SN 白名单、协议审批、真实写入总开关；不通过则 `POLICY_BLOCKED_NOT_ATTEMPTED` |
### 2.4 运维与辅助
| # | 功能点 | 说明 |
|---|---|---|
| 16 | `/iot/mqtt/status|publish|subscribe` | 仅 `mock=true` 或 `qa-api-enabled=true` 时加载，**当前不加载** |
| 17 | `/qa/mock/**` 模拟接口 | 同上，**当前不可用** |
| 18 | 网关离线判定 | `GatewayOfflineCheckTask`、`LockDeviceOfflineCheckTask`（定时任务，遗嘱消息已关闭） |
> **不属于 MQTT 的部分**：报到机人脸上传后的"门锁入住"走 HTTP 开放平台（`TrainLockStayApiClient#callStayCheckin`），不受本次断连影响。
---
## 3. 相关代码文件清单
### 3.1 连接核心与配置（`ruoyi-iot`）
```
com/ruoyi/iot/config/IotMqttProperties.java
com/ruoyi/iot/config/IotMqttConfig.java
com/ruoyi/iot/core/MqttClientManager.java
com/ruoyi/iot/core/MqttCallbackHandler.java
com/ruoyi/iot/core/MqttConnectionCallback.java
com/ruoyi/iot/core/MqttMessageDispatcher.java
com/ruoyi/iot/core/IMqttMessageListener.java
com/ruoyi/iot/domain/MqttMessageDTO.java
com/ruoyi/iot/domain/MqttPublishRequest.java
com/ruoyi/iot/event/MqttMessageEvent.java
com/ruoyi/iot/service/IMqttService.java
com/ruoyi/iot/service/impl/MqttServiceImpl.java
com/ruoyi/iot/controller/IotMqttController.java
```
### 3.2 门禁协议与消息处理
```
com/ruoyi/iot/lock/mqtt/LockTopicSubscriber.java
com/ruoyi/iot/lock/mqtt/LockMessageListener.java
com/ruoyi/iot/lock/mqtt/handler/GatewayOnlineHandler.java
com/ruoyi/iot/lock/mqtt/handler/CommandRespHandler.java
com/ruoyi/iot/lock/mqtt/handler/AccessRecordHandler.java
com/ruoyi/iot/lock/mqtt/handler/LockSignalHandler.java
com/ruoyi/iot/lock/protocol/YdlinkCodec.java
com/ruoyi/iot/lock/protocol/YdlinkFrameDTO.java
com/ruoyi/iot/lock/protocol/YdlinkOp.java
com/ruoyi/iot/lock/protocol/YdlinkTopicBuilder.java
com/ruoyi/iot/lock/protocol/YdlinkTopicDTO.java
com/ruoyi/iot/lock/protocol/YdlinkTopicType.java
```
### 3.3 门禁业务
```
com/ruoyi/iot/lock/security/RealIotSecurityGate.java
com/ruoyi/iot/lock/service/impl/LockCommandServiceImpl.java
com/ruoyi/iot/lock/service/impl/LockAuthServiceImpl.java
com/ruoyi/iot/lock/service/impl/LockDeviceServiceImpl.java
com/ruoyi/iot/lock/service/impl/LockGatewayServiceImpl.java
com/ruoyi/iot/lock/service/impl/LockMqttLogServiceImpl.java
com/ruoyi/iot/lock/service/ILockMqttLogService.java
com/ruoyi/iot/lock/domain/LockMqttLog.java
com/ruoyi/iot/lock/mapper/LockMqttLogMapper.java
com/ruoyi/iot/lock/controller/LockMqttLogController.java
com/ruoyi/iot/lock/task/LockCommandRetryTask.java
com/ruoyi/iot/lock/task/GatewayOfflineCheckTask.java
com/ruoyi/iot/lock/task/LockDeviceOfflineCheckTask.java
```
### 3.4 业务桥接（`ruoyi-train`）
```
com/ruoyi/train/integration/lock/service/impl/TrainIotLockAuthBridgeServiceImpl.java
com/ruoyi/train/integration/lock/service/ITrainLockAuthBridgeService.java
com/ruoyi/train/integration/lock/dto/LockAuthBridgeResult.java
```
> 同目录 `client/TrainLockStayApiClient.java`、`dto/LockStayCheckinResult.java` 为 **HTTP** 门锁开放平台调用，不走 MQTT。
### 3.5 QA 与测试
```
ruoyi-admin/src/main/java/com/ruoyi/web/controller/tool/QaMockMqttApiController.java
ruoyi-iot/src/test/java/...（MqttClientManagerTest、MqttMessageDispatcherTest、LockMessageListenerTest 等）
```
### 3.6 配置文件
```
ruoyi-admin/src/main/resources/application.yml # iot.mqtt.*（195-259 行，当前生效）
ruoyi-admin/src/main/resources/application_localhost.yml # broker 指向 202/24
ruoyi-admin/src/main/resources/application_localhost_24.yml
ruoyi-admin/src/main/resources/application_localhost_230.yml
```
> 激活 profile 为 `druid`，其 `application-druid.yml` 无 `iot.mqtt` 覆盖项，最终以 `application.yml` 为准。
---
## 4. 生效状态分析
### 4.1 配置层
```yaml
mqtt:
enabled: true # 创建连接
mock: false # 真实收发
protocol-verified: true # 允许真实下发
real-device-write-enabled: true
environment-id: railway-iot-01
retry-task-enabled: false # 补偿任务关闭
broker-url: tcp://192.168.1.202:1883
username: admin3
password: admin3
automatic-reconnect: true
health-check-interval: 30000
topics: 5 个上行主题（QoS 1）
```
### 4.2 运行时证据
| 检查项 | 结果 | 含义 |
|---|---|---|
| 应用进程 | `java.exe` PID 26688 监听 `0.0.0.0:8096` | 应用正在运行 |
| MQTT socket | 对 `192.168.1.202:1883` 处于 **`SYN_SENT`** | TCP 连接未建立，正在重试 |
| Broker 连通性 | `Test-NetConnection 192.168.1.202:1883` → TCP 失败、Ping 超时 | Broker 不可达 |
| 本机 1883 | `127.0.0.1:1883` 由 `mosquitto.exe`（PID 6032）监听 | 本地有可用 Broker，配置未指向 |
### 4.3 日志证据
| 日志 | 证据 |
|---|---|
| `logs/sys-error.log` | `[iot-mqtt-health] ERROR MqttClientManager - MQTT 连接失败, broker=tcp://192.168.1.202:1883`，累计 **448 次**，间隔约 30s；今日 13:52:50 仍有新记录 |
| `logs/sys-info.2026-11-09.log` | `MQTT 连接成功` **27 次**；含真实上行处理（网关状态更新、开门记录落库） |
| `logs/sys-info.log`（今日） | 无任何 MQTT 行 —— 今日连接从未成功，失败仅写 error 日志 |
### 4.4 断连时的代码行为
```java
// LockCommandServiceImpl#dispatch
if (!mqttService.isConnected()) {
log.warn("[TRACE-DISPATCH] cid={} isConnected=false -> TRANSPORT_DISCONNECTED", commandId);
command.setCommandStatus(LockConstants.STATUS_FAIL);
command.setErrorMsg("TRANSPORT_DISCONNECTED_NOT_ATTEMPTED");
commandMapper.updateCommand(command);
return null;
}
```
断连时命令**在发送前即被标记失败**，不会进入 `AWAITING_ACK`，因此不存在"平台显示已下发、设备未收到"的假成功。
### 4.5 功能可用性对照
| 功能 | 状态 | 依据 |
|---|---|---|
| MQTT 连接 | ❌ 未连接 | `SYN_SENT` + 448 次失败日志 + Broker 不可达 |
| 上行 5 个主题 | ❌ 无订阅 | 订阅在 `connect()` 成功后执行，当前未连接 |
| 网关状态 / 开门记录 / 回执处理 | ❌ 停止 | 依赖上行报文 |
| 授权下发 / 远程开关锁 / 网关设置 | ❌ 直接失败 | `isConnected=false` → `STATUS_FAIL` |
| 命令补偿重发 | ❌ 不执行 | `retry-task-enabled=false` |
| `/iot/mqtt/status`、`/qa/mock/**` | ❌ 未加载 | `@ConditionalOnProperty` 条件不满足，**无法用接口自证状态** |
| 报到机人脸采集与门锁入住（HTTP） | ✅ 正常 | 走 HTTP 开放平台，与 MQTT 无关 |
---
## 5. 判断依据与恢复方向
### 5.1 判断依据
1. **配置齐备**：开关、Mock、协议审批、真实写入、白名单均已就位 → 具备生效条件。
2. **运行证据否证**：应用存活但 TCP 未连通，健康检查持续失败 → 连接未建立。
3. **产物证据缺失**：无订阅即无上行；命令侧有明确的失败状态码 → 收发均不可用。
4. **历史反证代码无缺陷**：曾出现 27 次连接成功与真实报文处理 → 问题在环境与配置指向，而非实现。
### 5.2 恢复方向（无需改代码）
1. 排查 `192.168.1.202:1883`：主机连通性、防火墙、Broker 进程、网段隔离；
2. 若现场已有本机 Broker，将 `iot.mqtt.broker-url` 改为 `tcp://127.0.0.1:1883`，并核对 `username/password`；
3. 恢复后按序验证：
- 日志出现 `MQTT 连接成功`
- 5 个主题订阅成功
- 收到网关 `onoff_line` 上行
- 对白名单内 SN 下发一次授权，确认回执进入 `CONFIRMED`
4. 如需离线补偿能力，再评估开启 `retry-task-enabled=true`（会周期性重发至真实设备，属生产变更，需审批）。
---
*文档结束。如需补充时序图或按模块拆分，可在此基础上扩展。*
Reference in new issue Copy Permalink