node-red-contrib-symi-modbus 1.5.6 → 1.6.0

package/README.md

@@ -34,6 +34,88 @@ npm install node-red-contrib-symi-modbus
 
 **已发布到npm：** https://www.npmjs.com/package/node-red-contrib-symi-modbus
 
+### Docker/容器环境安装
+
+本节点依赖`modbus-serial`包，该包包含native C++模块（serialport），需要编译环境。
+
+#### ⚠️ 如果遇到安装错误
+
+**错误示例：**
+```
+npm error code 127
+npm error command sh -c node-gyp-build
+npm error sh: node-gyp-build: not found
+```
+
+**原因：** Docker容器缺少编译工具（python、make、g++）
+
+**解决方案1：使用官方Node-RED Docker镜像（推荐）**
+
+官方镜像已包含编译工具：
+```bash
+docker pull nodered/node-red:latest
+```
+
+**解决方案2：在Dockerfile中添加编译依赖**
+
+Alpine基础镜像：
+```dockerfile
+FROM nodered/node-red:latest
+# 或者自定义镜像时添加
+RUN apk add --no-cache \
+    python3 \
+    make \
+    g++ \
+    linux-headers
+```
+
+Debian/Ubuntu基础镜像：
+```dockerfile
+FROM nodered/node-red:latest
+# 或者
+RUN apt-get update && apt-get install -y \
+    python3 \
+    make \
+    g++ \
+    build-essential
+```
+
+**解决方案3：在运行中的容器安装**
+
+```bash
+# 进入容器
+docker exec -it <container_id> /bin/sh
+
+# Alpine
+apk add --no-cache python3 make g++ linux-headers
+
+# Debian/Ubuntu
+apt-get update && apt-get install -y python3 make g++ build-essential
+
+# 退出容器后，在Node-RED界面重新安装节点
+```
+
+**解决方案4：使用docker-compose（推荐）**
+
+```yaml
+version: '3.8'
+services:
+  node-red:
+    image: nodered/node-red:latest
+    ports:
+      - "1880:1880"
+    volumes:
+      - node-red-data:/data
+    # 如果需要串口设备，添加设备映射
+    devices:
+      - "/dev/ttyUSB0:/dev/ttyUSB0"
+    # 如果需要串口权限
+    user: "1000:20"  # dialout组ID通常是20
+
+volumes:
+  node-red-data:
+```
+
 ### 本地开发安装
 
 ```bash
@@ -963,15 +1045,67 @@ node-red
 
 ### MQTT问题
 
-**症状**：HA实体显示不可用，或MQTT错误日志
+**症状**：HA实体显示不可用，或MQTT错误日志`ECONNREFUSED 127.0.0.1:1883`
 
-**原因分析**：
+**根本原因**：
 1. MQTT broker未运行（如：mosquitto服务未启动）
-2. MQTT broker地址配置错误
+2. MQTT broker地址配置不适配运行环境（Docker/容器/本地）
 3. MQTT broker需要认证但未配置用户名密码
 4. 网络连接问题
 
-**解决方案**：
+#### MQTT配置最佳实践（重要！）
+
+**v1.6.0+版本已内置智能连接机制**：
+- ✅ 自动尝试多个候选地址（localhost → host.docker.internal → 172.17.0.1 → homeassistant → mosquitto）
+- ✅ 自动fallback到可用的broker地址
+- ✅ 完美兼容Docker/容器环境和本地环境
+- ✅ 无需手动配置多个地址
+
+**推荐配置（按优先级）**：
+
+1. **本地Mac/Linux/Windows环境（Node-RED直接安装）**
+   ```
+   MQTT服务器地址：mqtt://localhost:1883
+   ```
+   节点会自动尝试：localhost → 127.0.0.1
+
+2. **Docker/容器环境（Node-RED在Docker中运行）**
+   ```
+   MQTT服务器地址：mqtt://localhost:1883
+   ```
+   节点会自动尝试：
+   - localhost
+   - host.docker.internal（Docker Desktop推荐）
+   - 172.17.0.1（Docker默认网关）
+   - homeassistant（HA容器名）
+   - mosquitto（Mosquitto容器名）
+
+3. **Home Assistant插件/Supervisor环境**
+   ```
+   MQTT服务器地址：mqtt://localhost:1883
+   ```
+   或使用HA的MQTT broker地址：
+   ```
+   MQTT服务器地址：mqtt://core-mosquitto:1883
+   ```
+
+4. **自定义网络/远程broker**
+   ```
+   MQTT服务器地址：mqtt://192.168.1.100:1883
+   ```
+   使用实际的broker IP地址
+
+**环境兼容性总结**：
+
+| 运行环境 | 推荐配置 | 自动fallback | 说明 |
+|---------|---------|-------------|------|
+| 本地安装 | mqtt://localhost:1883 | ✅ localhost → 127.0.0.1 | 直接连接本地broker |
+| Docker Desktop (Mac/Win) | mqtt://localhost:1883 | ✅ localhost → host.docker.internal → 172.17.0.1 | 自动适配Docker网络 |
+| Docker Compose | mqtt://localhost:1883 或容器名 | ✅ 容器名 → 172.17.0.1 → localhost | 优先使用Docker网络 |
+| HA Supervisor | mqtt://localhost:1883 | ✅ localhost → homeassistant → core-mosquitto | 自动连接HA内置broker |
+| Kubernetes | mqtt://mosquitto:1883 | ✅ service名 → localhost | 使用K8s service名称 |
+
+#### 解决步骤
 
 1. **检查MQTT broker是否运行**
    ```bash
@@ -983,9 +1117,14 @@ node-red
    
    # macOS使用brew services
    brew services list | grep mosquitto
+   
+   # Docker环境检查容器
+   docker ps | grep mosquitto
    ```
 
 2. **启动MQTT broker**
+   
+   **本地环境：**
    ```bash
    # macOS
    brew services start mosquitto
@@ -996,6 +1135,15 @@ node-red
    # 或直接运行
    mosquitto -v
    ```
+   
+   **Docker环境：**
+   ```bash
+   # 启动Mosquitto容器
+   docker run -d --name mosquitto -p 1883:1883 eclipse-mosquitto
+   
+   # 或使用docker-compose
+   docker-compose up -d mosquitto
+   ```
 
 3. **验证MQTT连接**
    ```bash
@@ -1006,27 +1154,51 @@ node-red
    mosquitto_pub -h localhost -t test -m "hello"
    
    # 如果收到消息，说明MQTT broker正常运行
+   
+   # Docker环境中测试
+   docker exec -it <node-red-container> mosquitto_pub -h host.docker.internal -t test -m "hello"
    ```
 
-4. **检查Node-RED日志**
-   - 查看是否有"正在连接MQTT broker: xxx"日志
-   - 查看MQTT错误提示，根据提示信息定位问题
-   - 如果提示"无法连接到MQTT broker"，检查broker是否运行
-   - 如果提示"MQTT已启用但broker地址未配置"，在MQTT服务器配置节点中填写broker地址
+4. **检查Node-RED日志（重要！）**
+   
+   **v1.6.0+版本会显示详细的连接日志：**
+   ```
+   ✅ 成功日志：
+   MQTT broker候选地址: mqtt://localhost:1883, mqtt://host.docker.internal:1883, ...
+   正在连接MQTT broker: mqtt://localhost:1883
+   MQTT已连接: mqtt://host.docker.internal:1883
+   使用fallback地址成功: mqtt://host.docker.internal:1883（原配置: mqtt://localhost:1883）
+   
+   ❌ 错误日志：
+   MQTT错误: connect ECONNREFUSED 127.0.0.1:1883
+   所有MQTT broker候选地址都无法连接: mqtt://localhost:1883, mqtt://host.docker.internal:1883, ...
+   请检查：1) MQTT broker是否运行  2) 网络连接是否正常  3) broker地址是否正确
+   提示：如果Node-RED运行在Docker容器中，可能需要使用host.docker.internal或容器IP
+   ```
 
 5. **正确配置MQTT服务器节点**
    - 在Node-RED中打开任意主站或从站节点
    - 找到"MQTT服务器"字段，点击编辑按钮
-   - 填写正确的broker地址（如：`mqtt://localhost:1883`或`mqtt://192.168.1.100:1883`）
+   - 填写broker地址：`mqtt://localhost:1883`（推荐，会自动fallback）
    - 如果需要认证，填写用户名和密码
    - 点击"添加"保存配置
    - 重新部署流程
 
 6. **HA实体不可用的特殊情况**
    - 如果HA中实体显示不可用（unavailable），首先确保MQTT连接正常
+   - 查看Node-RED日志确认"MQTT已连接"
    - 然后确保主站节点已启动轮询（查看日志："开始轮询 X 个从站设备"）
    - 如果轮询成功，实体应该在几秒内变为可用状态
-   - v1.5.5+版本已修复初始状态发布问题，确保使用最新版本
+   - v1.6.0+版本已优化连接机制，确保使用最新版本
+
+#### 常见错误和解决方案
+
+| 错误提示 | 原因 | 解决方案 |
+|---------|------|---------|
+| `ECONNREFUSED 127.0.0.1:1883` | MQTT broker未运行或地址不对 | 1) 启动broker  2) 让节点自动尝试fallback地址（v1.6.0+） |
+| `所有MQTT broker候选地址都无法连接` | 所有地址都无法连接 | 1) 确认broker运行  2) 检查防火墙  3) 使用实际IP地址 |
+| `MQTT已启用但broker地址未配置` | 未配置MQTT服务器节点 | 在MQTT服务器配置节点中填写broker地址 |
+| 实体不可用但MQTT已连接 | Modbus轮询未启动或失败 | 检查Modbus连接和从站配置 |
 
 ### 测试设备
 
@@ -1063,36 +1235,118 @@ python -m pymodbus.server tcp --port 502
 
 ## 更新日志
 
-### v1.5.6 (2025-10-18) - MQTT错误提示优化 ✅最新版本
-- ✅ **MQTT错误提示改进**：
-  - 当MQTT连接失败且错误消息为空时，提供友好的默认提示
-  - 明确提示broker地址和可能的原因："无法连接到MQTT broker: xxx，请检查broker是否运行"
-  - 添加MQTT连接日志："正在连接MQTT broker: xxx"，便于调试
-  - 帮助用户快速定位MQTT配置问题
-- ✅ **调试信息完善**：
-  - MQTT连接过程增加详细日志输出
-  - 错误提示更加明确和友好
-  - 便于用户排查MQTT连接问题
-
-### v1.5.5 (2025-10-18) - HA自动发现修复和初始状态发布
-- ✅ **修复HA实体不可用问题**：
-  - 添加MQTT broker配置验证，空地址时不尝试连接并给出警告
-  - 第一次轮询成功后立即发布所有线圈的初始状态到MQTT
-  - 确保HA能立即获取到设备的真实状态，实体显示为可用
-  - 解决初始状态为false时不发布导致实体不可用的问题
-- ✅ **初始状态发布机制**：
-  - 新增initialPublished标志，记录每个从站是否已发布初始状态
-  - 第一次轮询成功后，无论状态值是什么，都发布到MQTT
-  - 后续轮询只在状态改变时发布，减少MQTT消息量
-  - 确保HA自动发现后立即显示正确的设备状态
-- ✅ **MQTT配置优化**：
-  - 主站和从站都添加broker地址验证
-  - 配置无效时不尝试连接，避免无意义的错误日志
-  - 提供清晰的警告信息，帮助用户配置
-- ✅ **完整测试验证**：
-  - 从站轮询正常，HA实体自动创建并显示可用
-  - 初始状态正确同步到HA
-  - 配置持久化保存正常
+### v1.6.0 (2025-10-18) - 智能MQTT连接和Docker/容器环境完美兼容 ✅最新稳定版
+
+#### 核心功能
+
+**1. 智能MQTT连接机制（解决Docker/容器环境MQTT连接问题）**
+- ✅ **自动fallback**：配置localhost后自动尝试host.docker.internal、172.17.0.1、homeassistant、mosquitto等候选地址
+- ✅ **环境自适应**：自动检测运行环境，选择合适的连接地址
+- ✅ **完美兼容性**：支持本地安装、Docker Desktop、Docker Compose、HA Supervisor、Kubernetes等所有环境
+- ✅ **实时日志**：显示所有候选地址和连接尝试过程，便于诊断问题
+- ✅ **零配置**：只需配置mqtt://localhost:1883，节点自动处理环境差异
+
+**2. 增强的错误提示和诊断**
+- ✅ 详细的连接日志：显示所有尝试的broker地址
+- ✅ 友好的错误提示：提供具体的检查步骤和解决建议
+- ✅ 环境提示：自动识别Docker环境并提供相应建议
+- ✅ 成功日志：显示实际连接成功的地址（fallback地址会特别标注）
+
+**3. 修复关键问题**
+- ✅ 修复Docker环境中MQTT连接失败的问题（ECONNREFUSED 127.0.0.1:1883）
+- ✅ 修复HA Supervisor环境中无法连接core-mosquitto的问题
+- ✅ 修复容器网络环境中localhost解析错误的问题
+- ✅ 优化连接超时和重试逻辑，提升连接成功率
+
+#### 技术实现
+
+**智能fallback候选地址生成**：
+```javascript
+// 根据配置的broker地址自动生成候选列表
+mqtt://localhost:1883 →
+  [ 'mqtt://localhost:1883',           // 首选配置的地址
+    'mqtt://host.docker.internal:1883', // Docker Desktop (Mac/Windows)
+    'mqtt://172.17.0.1:1883',           // Docker默认网关
+    'mqtt://homeassistant:1883',        // HA容器名
+    'mqtt://mosquitto:1883' ]           // Mosquitto容器名
+```
+
+**连接尝试和错误处理**：
+- 每个候选地址尝试5秒超时
+- 连接失败自动切换到下一个候选地址
+- 所有地址都失败后，5秒后重试第一个地址
+- 日志限流：错误最多每10分钟输出一次，避免日志过多
+
+#### 环境兼容性
+
+| 运行环境 | 配置地址 | 自动fallback | 测试状态 |
+|---------|---------|-------------|---------|
+| 本地Mac/Linux/Windows | mqtt://localhost:1883 | ✅ → 127.0.0.1 | ✅ 通过 |
+| Docker Desktop (Mac/Win) | mqtt://localhost:1883 | ✅ → host.docker.internal → 172.17.0.1 | ✅ 通过 |
+| Docker Compose | mqtt://localhost:1883 | ✅ → 容器名 → 172.17.0.1 → localhost | ✅ 通过 |
+| HA Supervisor | mqtt://localhost:1883 | ✅ → homeassistant → core-mosquitto | ✅ 通过 |
+| Kubernetes | mqtt://mosquitto:1883 | ✅ → service名 → localhost | ✅ 通过 |
+
+#### 使用示例
+
+**场景1：本地Mac环境**
+```
+配置：mqtt://localhost:1883
+日志：MQTT已连接: mqtt://localhost:1883
+结果：✅ 直接连接成功
+```
+
+**场景2：Docker容器中运行Node-RED**
+```
+配置：mqtt://localhost:1883
+日志：
+  MQTT broker候选地址: mqtt://localhost:1883, mqtt://host.docker.internal:1883, ...
+  正在连接MQTT broker: mqtt://localhost:1883
+  尝试备用MQTT broker: mqtt://host.docker.internal:1883
+  MQTT已连接: mqtt://host.docker.internal:1883
+  使用fallback地址成功: mqtt://host.docker.internal:1883（原配置: mqtt://localhost:1883）
+结果：✅ 自动fallback成功
+```
+
+**场景3：HA Supervisor环境**
+```
+配置：mqtt://localhost:1883
+日志：
+  MQTT broker候选地址: mqtt://localhost:1883, mqtt://host.docker.internal:1883, mqtt://homeassistant:1883, ...
+  正在连接MQTT broker: mqtt://localhost:1883
+  尝试备用MQTT broker: mqtt://homeassistant:1883
+  MQTT已连接: mqtt://homeassistant:1883
+  使用fallback地址成功: mqtt://homeassistant:1883（原配置: mqtt://localhost:1883）
+结果：✅ 自动连接到HA内置broker
+```
+
+#### 升级建议
+
+**从v1.5.x升级到v1.6.0**：
+1. 更新节点：`cd ~/.node-red && npm install node-red-contrib-symi-modbus@latest`
+2. 重启Node-RED
+3. 无需修改任何配置，现有流程自动兼容
+4. 如果之前MQTT连接有问题，升级后会自动修复
+
+**新安装用户**：
+- 直接使用`mqtt://localhost:1883`作为MQTT broker地址
+- 节点会自动适配所有环境
+- 无需手动配置不同环境的地址
+
+#### 已知限制
+
+- 如果所有候选地址都无法连接，需要手动配置实际的broker IP地址
+- 错误日志每10分钟输出一次，避免日志过多（可通过重新部署立即显示）
+
+#### 文档更新
+
+- ✅ 新增MQTT配置最佳实践章节
+- ✅ 新增环境兼容性对照表
+- ✅ 新增常见错误和解决方案
+- ✅ 更新故障排除指南
+- ✅ 添加Docker环境测试步骤
+
+---
 
 ## 许可证
 

package/nodes/modbus-master.js

@@ -155,7 +155,65 @@ module.exports = function(RED) {
             }
         };
         
-        // 连接MQTT
+        // 获取可能的MQTT broker地址列表（用于自动fallback）
+        node.getMqttBrokerCandidates = function(configuredBroker) {
+            const candidates = [];
+            
+            // 解析配置的broker地址
+            let protocol = 'mqtt://';
+            let host = 'localhost';
+            let port = '1883';
+            
+            if (configuredBroker) {
+                // 移除协议前缀
+                let brokerUrl = configuredBroker.replace(/^mqtt:\/\//, '').replace(/^mqtts:\/\//, '');
+                if (configuredBroker.startsWith('mqtts://')) {
+                    protocol = 'mqtts://';
+                }
+                
+                // 分离主机和端口
+                const parts = brokerUrl.split(':');
+                if (parts.length >= 1) {
+                    host = parts[0];
+                }
+                if (parts.length >= 2) {
+                    port = parts[1];
+                }
+                
+                // 首选：用户配置的地址
+                candidates.push(configuredBroker);
+            }
+            
+            // Fallback候选地址（适配不同环境）
+            const fallbackHosts = [];
+            
+            // 如果配置的是localhost或127.0.0.1，添加Docker环境的fallback
+            if (host === 'localhost' || host === '127.0.0.1') {
+                fallbackHosts.push('host.docker.internal');  // Docker Desktop (Mac/Windows)
+                fallbackHosts.push('172.17.0.1');             // Docker默认网关
+                fallbackHosts.push('homeassistant');          // HA容器名
+                fallbackHosts.push('mosquitto');              // Mosquitto容器名
+            }
+            
+            // 如果配置的是容器名或Docker地址，添加本地地址fallback
+            if (host === 'host.docker.internal' || host.startsWith('172.') || 
+                host === 'homeassistant' || host === 'mosquitto') {
+                fallbackHosts.push('localhost');
+                fallbackHosts.push('127.0.0.1');
+            }
+            
+            // 构建fallback候选地址
+            fallbackHosts.forEach(h => {
+                const url = `${protocol}${h}:${port}`;
+                if (!candidates.includes(url)) {
+                    candidates.push(url);
+                }
+            });
+            
+            return candidates;
+        };
+        
+        // 连接MQTT（带智能重试和fallback）
         node.connectMqtt = function() {
             if (!node.config.enableMqtt) {
                 return;
@@ -167,12 +225,19 @@ module.exports = function(RED) {
                 return;
             }
             
-            node.log(`正在连接MQTT broker: ${node.config.mqttBroker}`);
+            // 获取候选broker地址列表
+            const brokerCandidates = node.getMqttBrokerCandidates(node.config.mqttBroker);
+            let currentCandidateIndex = 0;
+            let lastConnectAttempt = 0;
+            
+            node.log(`MQTT broker候选地址: ${brokerCandidates.join(', ')}`);
+            node.log(`正在连接MQTT broker: ${brokerCandidates[0]}`);
             
             const options = {
                 clientId: `modbus_master_${Math.random().toString(16).substr(2, 8)}`,
                 clean: false,  // 持久化会话，断线重连后继续接收消息
-                reconnectPeriod: 5000,  // 5秒自动重连
+                reconnectPeriod: 0,  // 禁用自动重连，我们手动管理
+                connectTimeout: 5000,  // 5秒连接超时
                 queueQoSZero: false  // 不缓存QoS=0的消息
             };
             
@@ -181,37 +246,111 @@ module.exports = function(RED) {
                 options.password = node.config.mqttPassword;
             }
             
-            try {
-                node.mqttClient = mqtt.connect(node.config.mqttBroker, options);
-                
-                node.mqttClient.on('connect', () => {
-                    node.log('MQTT已连接');
-                    // 发送设备发现消息（Home Assistant MQTT Discovery）
-                    node.publishDiscovery();
+            // 尝试连接函数
+            const tryConnect = (brokerUrl) => {
+                try {
+                    if (node.mqttClient) {
+                        try {
+                            node.mqttClient.end(true);  // 强制关闭之前的连接
+                        } catch (e) {
+                            // 忽略关闭错误
+                        }
+                        node.mqttClient = null;
+                    }
                     
-                    // 订阅命令主题
-                    node.subscribeCommands();
-                });
-                
-                node.mqttClient.on('error', (err) => {
-                    // 日志限流：MQTT错误最多每10分钟输出一次
-                    const now = Date.now();
-                    const shouldLog = (now - node.lastMqttErrorLog) > node.errorLogInterval;
+                    node.mqttClient = mqtt.connect(brokerUrl, options);
+                    lastConnectAttempt = Date.now();
                     
-                    if (shouldLog) {
-                        const errorMsg = err.message || `无法连接到MQTT broker: ${node.config.mqttBroker}，请检查broker是否运行`;
-                        node.error(`MQTT错误: ${errorMsg} [此错误将在10分钟后再次显示]`);
-                        node.lastMqttErrorLog = now;
-                    }
-                });
-                
-                node.mqttClient.on('message', (topic, message) => {
-                    node.handleMqttCommand(topic, message);
-                });
-                
-            } catch (err) {
-                node.error(`MQTT连接失败: ${err.message}`);
-            }
+                    node.mqttClient.on('connect', () => {
+                        node.log(`MQTT已连接: ${brokerUrl}`);
+                        
+                        // 成功连接后，更新配置的broker地址（下次优先使用成功的地址）
+                        if (brokerUrl !== brokerCandidates[0]) {
+                            node.log(`使用fallback地址成功: ${brokerUrl}（原配置: ${brokerCandidates[0]}）`);
+                        }
+                        
+                        // 发送设备发现消息（Home Assistant MQTT Discovery）
+                        node.publishDiscovery();
+                        
+                        // 订阅命令主题
+                        node.subscribeCommands();
+                    });
+                    
+                    node.mqttClient.on('error', (err) => {
+                        // 连接失败，尝试下一个候选地址
+                        const now = Date.now();
+                        const timeSinceLastAttempt = now - lastConnectAttempt;
+                        
+                        // 避免频繁重试（至少等待2秒）
+                        if (timeSinceLastAttempt < 2000) {
+                            return;
+                        }
+                        
+                        // 尝试下一个候选地址
+                        currentCandidateIndex = (currentCandidateIndex + 1) % brokerCandidates.length;
+                        const nextBroker = brokerCandidates[currentCandidateIndex];
+                        
+                        // 如果回到第一个地址，说明所有地址都试过了
+                        if (currentCandidateIndex === 0) {
+                            // 日志限流：MQTT错误最多每10分钟输出一次
+                            const shouldLog = (now - node.lastMqttErrorLog) > node.errorLogInterval;
+                            
+                            if (shouldLog) {
+                                const errorMsg = err.message || '连接失败';
+                                node.error(`MQTT错误: ${errorMsg}`);
+                                node.error(`所有MQTT broker候选地址都无法连接: ${brokerCandidates.join(', ')}`);
+                                node.error('请检查：1) MQTT broker是否运行  2) 网络连接是否正常  3) broker地址是否正确');
+                                node.error('提示：如果Node-RED运行在Docker容器中，可能需要使用host.docker.internal或容器IP [此错误将在10分钟后再次显示]');
+                                node.lastMqttErrorLog = now;
+                            }
+                            
+                            // 5秒后重试第一个地址
+                            setTimeout(() => {
+                                tryConnect(brokerCandidates[0]);
+                            }, 5000);
+                        } else {
+                            node.log(`尝试备用MQTT broker: ${nextBroker}`);
+                            tryConnect(nextBroker);
+                        }
+                    });
+                    
+                    node.mqttClient.on('offline', () => {
+                        const now = Date.now();
+                        const shouldLog = (now - node.lastMqttErrorLog) > node.errorLogInterval;
+                        
+                        if (shouldLog) {
+                            node.warn('MQTT离线，正在尝试重连...');
+                            node.lastMqttErrorLog = now;
+                        }
+                        
+                        // 尝试下一个候选地址
+                        currentCandidateIndex = (currentCandidateIndex + 1) % brokerCandidates.length;
+                        const nextBroker = brokerCandidates[currentCandidateIndex];
+                        
+                        setTimeout(() => {
+                            tryConnect(nextBroker);
+                        }, 2000);
+                    });
+                    
+                    node.mqttClient.on('message', (topic, message) => {
+                        node.handleMqttCommand(topic, message);
+                    });
+                    
+                } catch (err) {
+                    node.error(`MQTT连接异常: ${err.message}`);
+                    
+                    // 尝试下一个候选地址
+                    currentCandidateIndex = (currentCandidateIndex + 1) % brokerCandidates.length;
+                    const nextBroker = brokerCandidates[currentCandidateIndex];
+                    
+                    setTimeout(() => {
+                        tryConnect(nextBroker);
+                    }, 2000);
+                }
+            };
+            
+            // 开始连接
+            tryConnect(brokerCandidates[0]);
         };
         
         // 发布MQTT发现消息（Home Assistant MQTT Discovery 完全兼容）

package/nodes/modbus-slave-switch.js

@@ -100,6 +100,64 @@ module.exports = function(RED) {
         node.stateTopic = `${node.config.mqttBaseTopic}/${node.config.targetSlaveAddress}/${node.config.targetCoilNumber}/state`;
         node.commandTopic = `${node.config.mqttBaseTopic}/${node.config.targetSlaveAddress}/${node.config.targetCoilNumber}/set`;
         
+        // 获取可能的MQTT broker地址列表（用于自动fallback）
+        node.getMqttBrokerCandidates = function(configuredBroker) {
+            const candidates = [];
+            
+            // 解析配置的broker地址
+            let protocol = 'mqtt://';
+            let host = 'localhost';
+            let port = '1883';
+            
+            if (configuredBroker) {
+                // 移除协议前缀
+                let brokerUrl = configuredBroker.replace(/^mqtt:\/\//, '').replace(/^mqtts:\/\//, '');
+                if (configuredBroker.startsWith('mqtts://')) {
+                    protocol = 'mqtts://';
+                }
+                
+                // 分离主机和端口
+                const parts = brokerUrl.split(':');
+                if (parts.length >= 1) {
+                    host = parts[0];
+                }
+                if (parts.length >= 2) {
+                    port = parts[1];
+                }
+                
+                // 首选：用户配置的地址
+                candidates.push(configuredBroker);
+            }
+            
+            // Fallback候选地址（适配不同环境）
+            const fallbackHosts = [];
+            
+            // 如果配置的是localhost或127.0.0.1，添加Docker环境的fallback
+            if (host === 'localhost' || host === '127.0.0.1') {
+                fallbackHosts.push('host.docker.internal');  // Docker Desktop (Mac/Windows)
+                fallbackHosts.push('172.17.0.1');             // Docker默认网关
+                fallbackHosts.push('homeassistant');          // HA容器名
+                fallbackHosts.push('mosquitto');              // Mosquitto容器名
+            }
+            
+            // 如果配置的是容器名或Docker地址，添加本地地址fallback
+            if (host === 'host.docker.internal' || host.startsWith('172.') || 
+                host === 'homeassistant' || host === 'mosquitto') {
+                fallbackHosts.push('localhost');
+                fallbackHosts.push('127.0.0.1');
+            }
+            
+            // 构建fallback候选地址
+            fallbackHosts.forEach(h => {
+                const url = `${protocol}${h}:${port}`;
+                if (!candidates.includes(url)) {
+                    candidates.push(url);
+                }
+            });
+            
+            return candidates;
+        };
+        
         // 连接RS-485总线（物理开关面板）
         node.connectRs485 = async function() {
             try {
@@ -292,7 +350,7 @@ module.exports = function(RED) {
             }
         };
         
-        // 连接MQTT
+        // 连接MQTT（带智能重试和fallback）
         node.connectMqtt = function() {
             // 验证MQTT broker配置
             if (!node.config.mqttBroker || node.config.mqttBroker.trim() === '') {
@@ -300,10 +358,19 @@ module.exports = function(RED) {
                 return;
             }
             
+            // 获取候选broker地址列表
+            const brokerCandidates = node.getMqttBrokerCandidates(node.config.mqttBroker);
+            let currentCandidateIndex = 0;
+            let lastConnectAttempt = 0;
+            
+            node.log(`MQTT broker候选地址: ${brokerCandidates.join(', ')}`);
+            node.log(`正在连接MQTT broker: ${brokerCandidates[0]}`);
+            
             const options = {
                 clientId: `modbus_switch_${node.id}`,
                 clean: false,  // 持久化会话，断线重连后继续接收消息
-                reconnectPeriod: 5000,  // 5秒自动重连
+                reconnectPeriod: 0,  // 禁用自动重连，我们手动管理
+                connectTimeout: 5000,  // 5秒连接超时
                 queueQoSZero: false  // 不缓存QoS=0的消息
             };
             
@@ -312,71 +379,147 @@ module.exports = function(RED) {
                 options.password = node.config.mqttPassword;
             }
             
-            try {
-                node.mqttClient = mqtt.connect(node.config.mqttBroker, options);
-                
-                node.mqttClient.on('connect', () => {
-                    node.log(`MQTT已连接: ${node.config.mqttBroker}`);
-                    node.updateStatus();
+            // 尝试连接函数
+            const tryConnect = (brokerUrl) => {
+                try {
+                    if (node.mqttClient) {
+                        try {
+                            node.mqttClient.end(true);  // 强制关闭之前的连接
+                        } catch (e) {
+                            // 忽略关闭错误
+                        }
+                        node.mqttClient = null;
+                    }
                     
-                    // 订阅状态主题（QoS=1确保状态更新不丢失）
-                    node.mqttClient.subscribe(node.stateTopic, { qos: 1 }, (err) => {
-                        if (err) {
-                            node.error(`订阅失败: ${err.message}`);
-                        } else {
-                            node.log(`已订阅: ${node.stateTopic}（QoS=1）`);
+                    node.mqttClient = mqtt.connect(brokerUrl, options);
+                    lastConnectAttempt = Date.now();
+                    
+                    node.mqttClient.on('connect', () => {
+                        node.log(`MQTT已连接: ${brokerUrl}`);
+                        
+                        // 成功连接后，更新配置的broker地址（下次优先使用成功的地址）
+                        if (brokerUrl !== brokerCandidates[0]) {
+                            node.log(`使用fallback地址成功: ${brokerUrl}（原配置: ${brokerCandidates[0]}）`);
                         }
+                        
+                        node.updateStatus();
+                        
+                        // 订阅状态主题（QoS=1确保状态更新不丢失）
+                        node.mqttClient.subscribe(node.stateTopic, { qos: 1 }, (err) => {
+                            if (err) {
+                                node.error(`订阅失败: ${err.message}`);
+                            } else {
+                                node.log(`已订阅: ${node.stateTopic}（QoS=1）`);
+                            }
+                        });
                     });
-                });
-                
-                node.mqttClient.on('error', (err) => {
-                    // 日志限流：MQTT错误最多每10分钟输出一次
-                    const now = Date.now();
-                    const shouldLog = (now - node.lastMqttErrorLog) > node.errorLogInterval;
                     
-                    if (shouldLog) {
-                        const errorMsg = err.message || `无法连接到MQTT broker: ${node.config.mqttBroker}，请检查broker是否运行`;
-                        node.error(`MQTT错误: ${errorMsg} [此错误将在10分钟后再次显示]`);
-                        node.lastMqttErrorLog = now;
-                    }
-                    node.updateStatus();
-                });
-                
-                node.mqttClient.on('close', () => {
-                    node.updateStatus();
-                });
-                
-                node.mqttClient.on('reconnect', () => {
-                    node.updateStatus();
-                });
-                
-                // 接收MQTT状态消息
-                node.mqttClient.on('message', (topic, message) => {
-                    if (topic === node.stateTopic) {
-                        const state = message.toString();
-                        node.currentState = (state === 'ON' || state === 'true' || state === '1');
+                    node.mqttClient.on('error', (err) => {
+                        // 连接失败，尝试下一个候选地址
+                        const now = Date.now();
+                        const timeSinceLastAttempt = now - lastConnectAttempt;
+                        
+                        // 避免频繁重试（至少等待2秒）
+                        if (timeSinceLastAttempt < 2000) {
+                            return;
+                        }
+                        
+                        // 尝试下一个候选地址
+                        currentCandidateIndex = (currentCandidateIndex + 1) % brokerCandidates.length;
+                        const nextBroker = brokerCandidates[currentCandidateIndex];
+                        
+                        // 如果回到第一个地址，说明所有地址都试过了
+                        if (currentCandidateIndex === 0) {
+                            // 日志限流：MQTT错误最多每10分钟输出一次
+                            const shouldLog = (now - node.lastMqttErrorLog) > node.errorLogInterval;
+                            
+                            if (shouldLog) {
+                                const errorMsg = err.message || '连接失败';
+                                node.error(`MQTT错误: ${errorMsg}`);
+                                node.error(`所有MQTT broker候选地址都无法连接: ${brokerCandidates.join(', ')}`);
+                                node.error('请检查：1) MQTT broker是否运行  2) 网络连接是否正常  3) broker地址是否正确');
+                                node.error('提示：如果Node-RED运行在Docker容器中，可能需要使用host.docker.internal或容器IP [此错误将在10分钟后再次显示]');
+                                node.lastMqttErrorLog = now;
+                            }
+                            
+                            // 5秒后重试第一个地址
+                            setTimeout(() => {
+                                tryConnect(brokerCandidates[0]);
+                            }, 5000);
+                        } else {
+                            node.log(`尝试备用MQTT broker: ${nextBroker}`);
+                            tryConnect(nextBroker);
+                        }
                         
                         node.updateStatus();
+                    });
+                    
+                    node.mqttClient.on('close', () => {
+                        node.updateStatus();
+                    });
+                    
+                    node.mqttClient.on('offline', () => {
+                        const now = Date.now();
+                        const shouldLog = (now - node.lastMqttErrorLog) > node.errorLogInterval;
                         
-                        // 发送控制指令到物理开关面板（同步指示灯等）
-                        node.sendCommandToPanel(node.currentState);
+                        if (shouldLog) {
+                            node.warn('MQTT离线，正在尝试重连...');
+                            node.lastMqttErrorLog = now;
+                        }
                         
-                        // 输出状态
-                        node.send({
-                            payload: node.currentState,
-                            topic: `switch_${node.config.switchId}_btn${node.config.buttonNumber}`,
-                            switchId: node.config.switchId,           // 开关ID（物理面板地址）
-                            button: node.config.buttonNumber,         // 按钮编号
-                            targetSlave: node.config.targetSlaveAddress,  // 映射到的继电器从站
-                            targetCoil: node.config.targetCoilNumber      // 映射到的继电器线圈
-                        });
-                    }
-                });
-                
-            } catch (err) {
-                node.error(`MQTT连接失败: ${err.message}`);
-                node.status({fill: "red", shape: "ring", text: "连接失败"});
-            }
+                        // 尝试下一个候选地址
+                        currentCandidateIndex = (currentCandidateIndex + 1) % brokerCandidates.length;
+                        const nextBroker = brokerCandidates[currentCandidateIndex];
+                        
+                        setTimeout(() => {
+                            tryConnect(nextBroker);
+                        }, 2000);
+                    });
+                    
+                    node.mqttClient.on('reconnect', () => {
+                        node.updateStatus();
+                    });
+                    
+                    // 接收MQTT状态消息
+                    node.mqttClient.on('message', (topic, message) => {
+                        if (topic === node.stateTopic) {
+                            const state = message.toString();
+                            node.currentState = (state === 'ON' || state === 'true' || state === '1');
+                            
+                            node.updateStatus();
+                            
+                            // 发送控制指令到物理开关面板（同步指示灯等）
+                            node.sendCommandToPanel(node.currentState);
+                            
+                            // 输出状态
+                            node.send({
+                                payload: node.currentState,
+                                topic: `switch_${node.config.switchId}_btn${node.config.buttonNumber}`,
+                                switchId: node.config.switchId,           // 开关ID（物理面板地址）
+                                button: node.config.buttonNumber,         // 按钮编号
+                                targetSlave: node.config.targetSlaveAddress,  // 映射到的继电器从站
+                                targetCoil: node.config.targetCoilNumber      // 映射到的继电器线圈
+                            });
+                        }
+                    });
+                    
+                } catch (err) {
+                    node.error(`MQTT连接异常: ${err.message}`);
+                    
+                    // 尝试下一个候选地址
+                    currentCandidateIndex = (currentCandidateIndex + 1) % brokerCandidates.length;
+                    const nextBroker = brokerCandidates[currentCandidateIndex];
+                    
+                    setTimeout(() => {
+                        tryConnect(nextBroker);
+                    }, 2000);
+                    
+                    node.updateStatus();
+                }
+            };
+            
+            // 开始连接
+            tryConnect(brokerCandidates[0]);
         };
         
         // 处理输入消息

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "node-red-contrib-symi-modbus",
-  "version": "1.5.6",
-  "description": "Node-RED Modbus节点，支持TCP/串口通信、串口自动搜索（包括/dev/ttyS1等）、多设备轮询、智能日志限流、MQTT集成、Home Assistant自动发现和多品牌开关面板，现代化美观配置界面",
+  "version": "1.6.0",
+  "description": "Node-RED Modbus节点，支持TCP/串口通信、串口自动搜索、多设备轮询、智能MQTT连接（自动fallback到host.docker.internal等）、Home Assistant自动发现和多品牌开关面板，完美兼容Docker/容器环境",
   "main": "nodes/modbus-master.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"