thingsboard/summary/24-MQTT规则节点检查指南.md

# MQTT 规则节点检查指南

## 问题分析

根据日志分析，发现以下情况：

1. **消息处理流程**：
   - 设备数据正常进入规则链
   - 消息在 `Save Timeseries` 节点处被处理
   - **但没有继续到 MQTT 节点**

2. **日志显示**：
   ```
   Last Rule Node: [RuleChain: Root Rule Chain|RuleNode: Save Timeseries(64ebb5c0-b857-11f0-b3fb-3333a2767a21)]
   ```
   - 所有消息都在 `Save Timeseries` 节点停止
   - 没有看到 MQTT 节点相关的日志

3. **可能的原因**：
   - MQTT 节点没有正确连接到 Save Timeseries 节点的输出
   - MQTT 节点配置错误（host、port、credentials 等）
   - MQTT 节点初始化失败但没有记录错误
   - 规则链连接配置问题

---

## 检查步骤

### 1. 检查规则链配置（Web UI）

1. **登录 ThingsBoard Web UI**
   - 访问：`http://localhost:8080`
   - 使用管理员账号登录

2. **检查 Root Rule Chain**
   - 进入：`Rule Chains` → `Root Rule Chain`
   - 查看节点列表：
     - 确认是否有 MQTT 节点
     - 查看 MQTT 节点的配置

3. **检查节点连接**
   - 在规则链编辑器中，检查：
     - `Save Timeseries` 节点是否有输出连接到 MQTT 节点
     - 连接类型应该是 `Success`（绿色箭头）
   - **常见问题**：
     - 节点没有连接
     - 连接到了错误的路由（如 `Failure` 而不是 `Success`）

### 2. 检查 MQTT 节点配置

**必需的配置项**：
- **Host**: MQTT Broker 地址（如 `localhost`、`mqtt.example.com`）
- **Port**: MQTT Broker 端口（如 `1883`、`8883`）
- **Topic Pattern**: MQTT 主题模式（如 `tb/telemetry/${deviceName}`）
- **Credentials**: 认证信息（如果 MQTT Broker 需要认证）

**检查方法**：
1. 在规则链编辑器中，点击 MQTT 节点
2. 查看配置面板
3. 确认所有必需字段都已填写

### 3. 检查日志中的错误信息

**查看 MQTT 节点初始化错误**：
```bash
docker logs mytb 2>&1 | grep -i "mqtt.*node\|mqtt.*init\|mqtt.*connect\|mqtt.*broker" | tail -50
```

**查看规则链相关错误**：
```bash
docker logs mytb 2>&1 | grep -i "rule.*node.*error\|rule.*chain.*error\|external.*node" | tail -50
```

**查看连接失败错误**：
```bash
docker logs mytb 2>&1 | grep -i "failed to connect\|connection.*refused\|timeout" | tail -50
```

### 4. 测试 MQTT Broker 连接

**检查 MQTT Broker 是否可访问**：
```bash
# 如果 MQTT Broker 在本地
nc -zv localhost 1883

# 如果 MQTT Broker 在其他服务器
nc -zv mqtt.example.com 1883
```

**使用 mosquitto 客户端测试**：
```bash
# 测试连接
mosquitto_pub -h <mqtt-broker-host> -p <port> -t "test/topic" -m "test message"
```

---

## 常见问题及解决方案

### 问题 1：MQTT 节点没有连接到 Save Timeseries 节点

**症状**：
- 日志显示消息在 Save Timeseries 节点停止
- 没有 MQTT 节点处理日志

**解决方案**：
1. 在规则链编辑器中，从 `Save Timeseries` 节点拖出连接线
2. 连接到 MQTT 节点
3. 确保连接类型是 `Success`（不是 `Failure`）
4. 保存规则链

### 问题 2：MQTT Broker 连接失败

**症状**：
- 日志中可能有连接错误（如果日志级别足够详细）
- MQTT 节点初始化失败

**解决方案**：
1. **检查 MQTT Broker 地址和端口**：
   - 确认 Host 和 Port 配置正确
   - 测试网络连接性

2. **检查认证信息**：
   - 如果 MQTT Broker 需要用户名密码，确保配置正确
   - 检查 SSL/TLS 配置（如果需要）

3. **检查防火墙**：
   - 确保 ThingsBoard 容器可以访问 MQTT Broker
   - 检查端口是否开放

### 问题 3：MQTT 节点配置错误

**症状**：
- Topic Pattern 配置错误
- 消息格式不正确

**解决方案**：
1. **检查 Topic Pattern**：
   - 使用正确的占位符（如 `${deviceName}`, `${deviceType}`）
   - 示例：`tb/telemetry/${deviceName}`

2. **检查消息格式**：
   - 确认 `Parse to plain text` 设置是否正确
   - 如果设置为 `true`，消息会被转换为纯文本格式

### 问题 4：日志级别不够详细

**症状**：
- 看不到 MQTT 节点的详细日志

**解决方案**：
1. **修改日志级别**：
   - 编辑 `thingsboard.conf` 或 `logback.xml`
   - 将 MQTT 相关类的日志级别设置为 `DEBUG`

2. **查看特定日志**：
   ```bash
   docker logs mytb 2>&1 | grep -i "org.thingsboard.rule.engine.mqtt" | tail -50
   ```

---

## 验证 MQTT 节点是否生效

### 方法 1：订阅 MQTT 主题

**在外部 MQTT 客户端订阅主题**：
```bash
# 订阅 MQTT 节点配置的主题
mosquitto_sub -h <mqtt-broker-host> -p <port> -t "tb/telemetry/#" -v
```

**如果收到消息**，说明 MQTT 节点正常工作。

### 方法 2：检查 MQTT Broker 日志

**如果 MQTT Broker 有日志**：
- 查看是否有来自 ThingsBoard 的连接
- 查看是否有消息发布到指定主题

### 方法 3：使用 ThingsBoard 调试功能

1. **启用规则节点调试事件**：
   - 在规则链编辑器中，点击 MQTT 节点
   - 启用 "Debug mode"
   - 保存规则链

2. **查看调试事件**：
   - 进入：`Rule Chains` → `Root Rule Chain` → `Debug events`
   - 查看 MQTT 节点的处理情况

---

## 正确配置示例

### 规则链结构

```
设备数据 
  ↓
Save Timeseries (Success) 
  ↓
MQTT Node (Success)
  ↓
结束
```

### MQTT 节点配置示例

```json
{
  "topicPattern": "tb/telemetry/${deviceName}",
  "host": "mqtt.example.com",
  "port": 1883,
  "connectTimeoutSec": 10,
  "clientId": "tb-rule-engine",
  "cleanSession": true,
  "retainedMessage": false,
  "ssl": false,
  "parseToPlainText": false,
  "protocolVersion": "MQTT_3_1_1",
  "credentials": {
    "type": "anonymous"
  }
}
```

---

## 下一步操作建议

1. **立即检查**：
   - [ ] 规则链中 MQTT 节点是否存在
   - [ ] Save Timeseries 节点是否连接到 MQTT 节点
   - [ ] MQTT 节点配置是否完整

2. **配置验证**：
   - [ ] MQTT Broker 地址和端口是否正确
   - [ ] 认证信息是否正确（如果需要）
   - [ ] Topic Pattern 是否正确

3. **测试验证**：
   - [ ] 使用外部 MQTT 客户端订阅主题
   - [ ] 发送测试数据到 ThingsBoard
   - [ ] 检查是否收到转发消息

4. **日志检查**：
   - [ ] 查看是否有连接错误
   - [ ] 查看是否有发布成功日志
   - [ ] 启用调试模式查看详细日志

---

## 总结

根据当前日志分析，**MQTT 节点很可能没有生效**，原因可能是：

1. **节点连接问题**（最可能）：Save Timeseries 节点没有连接到 MQTT 节点
2. **配置错误**：MQTT Broker 地址、端口或认证信息错误
3. **初始化失败**：MQTT 节点初始化失败但没有记录详细错误

**建议**：
1. 首先在 Web UI 中检查规则链配置和节点连接
2. 确认 MQTT 节点配置正确
3. 测试 MQTT Broker 连接
4. 如果问题仍然存在，启用调试模式查看详细日志