node-red-contrib-symi-modbus 2.10.17 → 2.10.19

package/README.md

@@ -487,6 +487,18 @@ msg.payload = 1;      // 或 0
 
 ### 更新日志
 
+#### v2.10.19 (2026-06-30)
+
+- **[工程]** 提取 `lib/lru-map.js`、`lib/slave-switch-cache.js`，精简 `modbus-slave-switch` 全局缓存逻辑并限制 Mesh LED 定时器上限（5000）。
+- **[工程]** 新增 `lib/http-admin-utils.js`，14 个 HTTP Admin 路由统一权限校验（read/write）。
+- **[工程]** `modbus-master` 串口列表 API 复用 `lib/serial-utils`，消除重复实现。
+- **[测试]** 新增 `mesh-protocol`、`lightweight-protocol` 协议帧解析单元测试（`npm test`）。
+
+#### v2.10.18 (2026-06-30)
+
+- **[打包]** 修复 npm 发布包误含 `.codebase-memory/` 开发索引文件的问题，包体积从约 493KB 降至约 158KB，避免将本地知识图谱索引发布到 npm。
+- **[工程]** 在 `.npmignore` 与 `.gitignore` 中排除 `.codebase-memory/`，确保开发工具产物不会进入发布包或版本库。
+
 #### v2.10.17 (2026-02-07)
 
 - **Mesh 窗帘协议兼容性**：按照《蓝牙MESH网关（初级版）串口协议V1.0》修正 0x53 0x80 0x06 节点状态帧解析逻辑，明确区分事件类型 RESULT_EVENT_NODE_STATUS(0x06) 与 `VD_MSG_TYPE_CURT_RUN_STATUS(0x05)` / `VD_MSG_TYPE_CURT_RUN_PER_POS(0x06)`，不再误把 `subOp` 当成窗帘 msg_type 使用，严格从数据区解析 `[msg_type][param]`。

package/lib/http-admin-utils.js

@@ -0,0 +1,34 @@
+"use strict";
+
+/**
+ * Node-RED HTTP Admin 路由注册（统一权限校验）
+ */
+function needsPermission(RED, permission) {
+    if (RED.auth && typeof RED.auth.needsPermission === "function") {
+        return RED.auth.needsPermission(permission);
+    }
+    return function passThrough(req, res, next) {
+        if (typeof next === "function") {
+            next();
+        }
+    };
+}
+
+function registerGet(RED, path, permission, handler) {
+    RED.httpAdmin.get(path, needsPermission(RED, permission), handler);
+}
+
+function registerPost(RED, path, permission, handler) {
+    RED.httpAdmin.post(path, needsPermission(RED, permission), handler);
+}
+
+function registerDelete(RED, path, permission, handler) {
+    RED.httpAdmin.delete(path, needsPermission(RED, permission), handler);
+}
+
+module.exports = {
+    needsPermission,
+    registerGet,
+    registerPost,
+    registerDelete
+};

package/lib/lru-map.js

@@ -0,0 +1,36 @@
+"use strict";
+
+/**
+ * 带大小限制的 LRU Map，用于全局缓存防内存泄漏
+ */
+class LRUMap extends Map {
+    constructor(maxSize, onEvict) {
+        super();
+        this.maxSize = maxSize;
+        this.onEvict = typeof onEvict === "function" ? onEvict : null;
+    }
+
+    set(key, value) {
+        if (this.has(key)) {
+            this.delete(key);
+        } else if (this.size >= this.maxSize) {
+            const firstKey = this.keys().next().value;
+            this.delete(firstKey);
+            if (this.onEvict) {
+                this.onEvict(firstKey);
+            }
+        }
+        return super.set(key, value);
+    }
+
+    get(key) {
+        const value = super.get(key);
+        if (value !== undefined) {
+            this.delete(key);
+            super.set(key, value);
+        }
+        return value;
+    }
+}
+
+module.exports = { LRUMap };

package/lib/slave-switch-cache.js

@@ -0,0 +1,88 @@
+"use strict";
+
+const { LRUMap } = require("./lru-map");
+
+const GLOBAL_CACHE_CONFIG = {
+    maxSize: 10000,
+    cleanupInterval: 600000,
+    expireTime: 3600000,
+    meshLedTimerMaxSize: 5000
+};
+
+/**
+ * 从站开关节点全局缓存（LRU + 定期清理）
+ */
+function createSlaveSwitchCaches(RED) {
+    const onEvict = (key) => {
+        if (RED && RED.log && RED.log.debug) {
+            RED.log.debug(`LRU缓存淘汰: 删除键 ${key}`);
+        }
+    };
+
+    const globalDebounceCache = new LRUMap(GLOBAL_CACHE_CONFIG.maxSize, onEvict);
+    const meshDeviceStates = new LRUMap(GLOBAL_CACHE_CONFIG.maxSize, onEvict);
+    const meshWirelessButtons = new LRUMap(GLOBAL_CACHE_CONFIG.maxSize, onEvict);
+    const globalButtonRelayStates = new LRUMap(GLOBAL_CACHE_CONFIG.maxSize, onEvict);
+    const meshLedDebounceTimers = new Map();
+
+    function getScopedKey(node, key) {
+        const configId = (node.serialPortConfig && node.serialPortConfig.id) || node.id || "global";
+        return `${configId}:${key}`;
+    }
+
+    let cleanupTimer = null;
+
+    function startGlobalDebounceCacheCleanup() {
+        if (cleanupTimer) {
+            return;
+        }
+        cleanupTimer = setInterval(() => {
+            const now = Date.now();
+            const expireThreshold = 60 * 1000;
+            let cleanedCount = 0;
+
+            for (const [key, timestamp] of globalDebounceCache.entries()) {
+                if (now - timestamp > expireThreshold) {
+                    globalDebounceCache.delete(key);
+                    cleanedCount++;
+                }
+            }
+
+            // Mesh LED 防抖定时器：清理已失效条目并限制最大数量
+            for (const [key, timerObj] of meshLedDebounceTimers.entries()) {
+                if (!timerObj || !timerObj.timer) {
+                    meshLedDebounceTimers.delete(key);
+                    cleanedCount++;
+                }
+            }
+            while (meshLedDebounceTimers.size > GLOBAL_CACHE_CONFIG.meshLedTimerMaxSize) {
+                const firstKey = meshLedDebounceTimers.keys().next().value;
+                const timerObj = meshLedDebounceTimers.get(firstKey);
+                if (timerObj && timerObj.timer) {
+                    clearTimeout(timerObj.timer);
+                }
+                meshLedDebounceTimers.delete(firstKey);
+                cleanedCount++;
+            }
+
+            if (cleanedCount > 0 && RED && RED.log && RED.log.debug) {
+                RED.log.debug(
+                    `全局缓存清理: 删除${cleanedCount}条记录，防抖${globalDebounceCache.size}条，LED定时器${meshLedDebounceTimers.size}条`
+                );
+            }
+        }, 10 * 60 * 1000);
+    }
+
+    return {
+        GLOBAL_CACHE_CONFIG,
+        globalDebounceCache,
+        meshDeviceStates,
+        meshWirelessButtons,
+        meshLedDebounceTimers,
+        globalButtonRelayStates,
+        getScopedKey,
+        startGlobalDebounceCacheCleanup
+    };
+}
+
+module.exports = { createSlaveSwitchCaches, GLOBAL_CACHE_CONFIG };

package/nodes/custom-protocol.js

@@ -1,5 +1,6 @@
 module.exports = function(RED) {
     "use strict";
+    const httpAdmin = require("../lib/http-admin-utils");
 
     function CustomProtocolNode(config) {
         RED.nodes.createNode(this, config);
@@ -173,7 +174,7 @@ module.exports = function(RED) {
     RED.nodes.registerType("custom-protocol", CustomProtocolNode);
 
     // HTTP API：测试发送指令
-    RED.httpAdmin.post("/custom-protocol/test", function(req, res) {
+    httpAdmin.registerPost(RED, "/custom-protocol/test", "custom-protocol.write", function(req, res) {
         var serialConfigId = req.body.serialConfig;
         var hexString = req.body.hexString;
         var cmdName = req.body.cmdName;

package/nodes/homekit-bridge.js

@@ -1,6 +1,7 @@
 module.exports = function(RED) {
     "use strict";
     const { ensureRedEventsMaxListeners } = require("../lib/red-events-utils");
+    const httpAdmin = require("../lib/http-admin-utils");
     ensureRedEventsMaxListeners(RED);
     const hap = require("hap-nodejs");
     const storage = require("node-persist");
@@ -335,7 +336,7 @@ module.exports = function(RED) {
     RED.nodes.registerType("homekit-bridge", HomekitBridgeNode);
 
     // HTTP API：获取主站节点配置
-    RED.httpAdmin.get("/homekit-bridge/master-config/:id", function(req, res) {
+    httpAdmin.registerGet(RED, "/homekit-bridge/master-config/:id", "homekit-bridge.read", function(req, res) {
         var masterNodeId = req.params.id;
         var masterNode = RED.nodes.getNode(masterNodeId);
 

package/nodes/modbus-dashboard.js

@@ -1,5 +1,6 @@
 module.exports = function(RED) {
     "use strict";
+    const httpAdmin = require("../lib/http-admin-utils");
 
     // 全局状态缓存（所有dashboard节点共享）
     var globalStateCache = {};
@@ -87,7 +88,7 @@ module.exports = function(RED) {
     RED.nodes.registerType("modbus-dashboard", ModbusDashboardNode);
 
     // HTTP API：获取主站节点配置
-    RED.httpAdmin.get("/modbus-dashboard/master-config/:id", function(req, res) {
+    httpAdmin.registerGet(RED, "/modbus-dashboard/master-config/:id", "modbus-dashboard.read", function(req, res) {
         var masterNodeId = req.params.id;
         var masterNode = RED.nodes.getNode(masterNodeId);
 
@@ -105,7 +106,7 @@ module.exports = function(RED) {
     });
 
     // HTTP API：获取状态
-    RED.httpAdmin.get("/modbus-dashboard/state/:masterNodeId", function(req, res) {
+    httpAdmin.registerGet(RED, "/modbus-dashboard/state/:masterNodeId", "modbus-dashboard.read", function(req, res) {
         var masterNodeId = req.params.masterNodeId;
         var states = {};
         
@@ -123,7 +124,7 @@ module.exports = function(RED) {
     });
 
     // HTTP API：刷新状态（从主站重新获取真实状态）
-    RED.httpAdmin.post("/modbus-dashboard/refresh/:masterNodeId", function(req, res) {
+    httpAdmin.registerPost(RED, "/modbus-dashboard/refresh/:masterNodeId", "modbus-dashboard.write", function(req, res) {
         var masterNodeId = req.params.masterNodeId;
         var masterNode = RED.nodes.getNode(masterNodeId);
 
@@ -170,7 +171,7 @@ module.exports = function(RED) {
     });
 
     // HTTP API：发送控制命令
-    RED.httpAdmin.post("/modbus-dashboard/control", function(req, res) {
+    httpAdmin.registerPost(RED, "/modbus-dashboard/control", "modbus-dashboard.write", function(req, res) {
         var slave = parseInt(req.body.slave);
         var coil = parseInt(req.body.coil);
         var value = Boolean(req.body.value);

package/nodes/modbus-master.js

@@ -4,85 +4,19 @@ module.exports = function(RED) {
     const mqtt = require("mqtt");
     const protocol = require("./lightweight-protocol");
     const mqttHelper = require("./mqtt-helper");
+    const serialUtils = require("../lib/serial-utils");
+    const httpAdmin = require("../lib/http-admin-utils");
 
     // 全局主站实例注册表（用于多主站独立运行，避免互相干扰）
     // 每个主站节点有独立的Modbus客户端实例，互不影响
     const masterInstances = new Map();
 
-    // 串口列表API - 支持Windows、Linux、macOS所有串口设备
-    RED.httpAdmin.get("/modbus-master/serialports", async function(req, res) {
+    // 串口列表API - 使用公共串口工具模块
+    httpAdmin.registerGet(RED, "/modbus-master/serialports", "modbus-master.read", async function(req, res) {
         try {
-            // 尝试从多个可能的位置获取serialport模块
-            let SerialPort;
-            try {
-                // 优先尝试使用node_modules中的serialport
-                SerialPort = require("serialport");
-            } catch (e) {
-                try {
-                    // 如果失败，尝试从modbus-serial的依赖中获取
-                    const ModbusRTU = require("modbus-serial");
-                    SerialPort = ModbusRTU.SerialPort || require("serialport");
-                } catch (e2) {
-                    // 两种方式都失败，返回特殊错误标记
-                    RED.log.warn("串口模块未找到，可能需要额外安装 serialport 模块");
-                    return res.json([{
-                        comName: "未检测到串口",
-                        manufacturer: "Docker环境需要映射设备：--device=/dev/ttyUSB0 或 --privileged",
-                        isError: true
-                    }]);
-                }
-            }
-            
-            // serialport v10+ (使用SerialPort.SerialPort.list)
-            if (SerialPort && SerialPort.SerialPort && SerialPort.SerialPort.list) {
-                const ports = await SerialPort.SerialPort.list();
-                if (ports.length === 0) {
-                    // 没有发现串口，返回提示信息
-                    return res.json([{
-                        comName: "未检测到串口",
-                        manufacturer: "Docker环境需要映射设备：--device=/dev/ttyUSB0 或 --privileged",
-                        isError: true
-                    }]);
-                }
-                const portList = ports.map(port => ({
-                    comName: port.path || port.comName,
-                    manufacturer: port.manufacturer || "未知设备",
-                    vendorId: port.vendorId || "",
-                    productId: port.productId || "",
-                    isError: false
-                }));
-                return res.json(portList);
-            }
-            
-            // serialport v9 (使用SerialPort.list)
-            if (SerialPort && SerialPort.list) {
-                const ports = await SerialPort.list();
-                if (ports.length === 0) {
-                    // 没有发现串口，返回提示信息
-                    return res.json([{
-                        comName: "未检测到串口",
-                        manufacturer: "Docker环境需要映射设备：--device=/dev/ttyUSB0 或 --privileged",
-                        isError: true
-                    }]);
-                }
-                const portList = ports.map(port => ({
-                    comName: port.path || port.comName,
-                    manufacturer: port.manufacturer || "未知设备",
-                    vendorId: port.vendorId || "",
-                    productId: port.productId || "",
-                    isError: false
-                }));
-                return res.json(portList);
-            }
-            
-            // 如果以上方法都不可用，返回提示信息
-            res.json([{
-                comName: "串口功能不可用",
-                manufacturer: "请手动输入串口路径，如：/dev/ttyUSB0",
-                isError: true
-            }]);
+            const ports = await serialUtils.getSerialPortListWithTips(RED);
+            res.json(ports);
         } catch (err) {
-            // 发生错误时记录日志并返回错误信息
             RED.log.warn(`串口列表获取失败: ${err.message}`);
             res.json([{
                 comName: "串口搜索失败",

package/nodes/modbus-slave-switch.js

@@ -9,95 +9,20 @@ module.exports = function(RED) {
     const path = require("path");
     const os = require("os");
     const serialUtils = require("../lib/serial-utils");
+    const httpAdmin = require("../lib/http-admin-utils");
+    const { createSlaveSwitchCaches } = require("../lib/slave-switch-cache");
+
+    const {
+        globalDebounceCache,
+        meshDeviceStates,
+        meshWirelessButtons,
+        meshLedDebounceTimers,
+        globalButtonRelayStates,
+        getScopedKey,
+        startGlobalDebounceCacheCleanup
+    } = createSlaveSwitchCaches(RED);
 
-    // 全局缓存配置
-    const GLOBAL_CACHE_CONFIG = {
-        maxSize: 10000,           // 最大缓存条目数
-        cleanupInterval: 600000,  // 清理间隔：10分钟
-        expireTime: 3600000       // 过期时间：1小时
-    };
-
-    // LRU Map 实现（带大小限制）
-    class LRUMap extends Map {
-        constructor(maxSize) {
-            super();
-            this.maxSize = maxSize;
-        }
-
-        set(key, value) {
-            // 如果 key 已存在，先删除再添加（保持最新访问顺序）
-            if (this.has(key)) {
-                this.delete(key);
-            }
-            // 如果超过最大大小，删除最旧的条目
-            else if (this.size >= this.maxSize) {
-                const firstKey = this.keys().next().value;
-                this.delete(firstKey);
-                RED.log.debug(`LRU缓存淘汰: 删除键 ${firstKey}`);
-            }
-            return super.set(key, value);
-        }
-
-        get(key) {
-            const value = super.get(key);
-            if (value !== undefined) {
-                // 移动到最新位置（LRU策略）
-                this.delete(key);
-                super.set(key, value);
-            }
-            return value;
-        }
-    }
-
-    // 全局防抖缓存：防止多个节点重复处理同一个按键事件
-    // key: "serialPortConfigId:switchId-buttonNumber", value: timestamp
-    const globalDebounceCache = new LRUMap(GLOBAL_CACHE_CONFIG.maxSize);
-
-    // 全局Mesh设备状态缓存（按短地址索引）
-    // key: "serialPortConfigId:meshShortAddress", value: [state1, state2, ...]
-    const meshDeviceStates = new LRUMap(GLOBAL_CACHE_CONFIG.maxSize);
-
-    // 全局Mesh无线模式按键标记（按短地址索引）
-    // key: "serialPortConfigId:meshShortAddress", value: Set([buttonNumber1, buttonNumber2, ...])
-    const meshWirelessButtons = new LRUMap(GLOBAL_CACHE_CONFIG.maxSize);
-
-    // 全局Mesh设备LED反馈防抖定时器（按短地址索引）
-    // key: "serialPortConfigId:meshShortAddress", value: {timer, nodeId, serialPortConfig}
-    const meshLedDebounceTimers = new Map();  // 定时器需要精确控制，不使用LRU
-
-    // 全局按钮关联继电器状态表（用于多对一控制时的LED状态聚合）
-    // key: "serialPortConfigId:switchId:buttonNumber", value: Map<nodeId, boolean>
-    const globalButtonRelayStates = new LRUMap(GLOBAL_CACHE_CONFIG.maxSize);
-
-    // 辅助函数：获取带作用域的键名
-    // 确保configId始终有效，避免返回"default"前缀导致不同配置下的节点共用防抖键
-    function getScopedKey(node, key) {
-        // 优先使用serialPortConfig.id，如果不存在则使用node.id作为fallback，最后使用 "global"
-        const configId = (node.serialPortConfig && node.serialPortConfig.id) || node.id || "global";
-        return `${configId}:${key}`;
-    }
-    
-    // 全局防抖缓存定期清理（每10分钟清理超过1分钟未使用的条目，防止内存泄漏）
-    let globalDebounceCacheCleanupTimer = null;
-    function startGlobalDebounceCacheCleanup() {
-        if (globalDebounceCacheCleanupTimer) {return;}
-        globalDebounceCacheCleanupTimer = setInterval(() => {
-            const now = Date.now();
-            const expireThreshold = 60 * 1000;  // 1分钟未使用的条目将被清理
-            let cleanedCount = 0;
-            for (const [key, timestamp] of globalDebounceCache.entries()) {
-                if (now - timestamp > expireThreshold) {
-                    globalDebounceCache.delete(key);
-                    cleanedCount++;
-                }
-            }
-            if (cleanedCount > 0) {
-                RED.log.debug(`全局防抖缓存清理: 删除${cleanedCount}条过期记录，剩余${globalDebounceCache.size}条`);
-            }
-        }, 10 * 60 * 1000);  // 每10分钟执行一次
-    }
     startGlobalDebounceCacheCleanup();
-    
     // 初始化Mesh设备持久化存储
     const meshPersistDir = path.join(RED.settings.userDir || os.homedir() + "/.node-red", "mesh-devices-persist");
     
@@ -127,7 +52,7 @@ module.exports = function(RED) {
     }
 
     // Mesh设备发现API（使用共享连接）
-    RED.httpAdmin.post("/symi-mesh/discover", async function(req, res) {
+    httpAdmin.registerPost(RED, "/symi-mesh/discover", "modbus-slave-switch.write", async function(req, res) {
         try {
             const serialPortConfigId = req.body.serialPortConfig;
             RED.log.info(`[Mesh设备发现] 收到请求，连接配置ID: ${serialPortConfigId}`);
@@ -320,7 +245,7 @@ module.exports = function(RED) {
     });
 
     // 获取已保存的Mesh设备列表API
-    RED.httpAdmin.get("/symi-mesh/devices", async function(req, res) {
+    httpAdmin.registerGet(RED, "/symi-mesh/devices", "modbus-slave-switch.read", async function(req, res) {
         try {
             await initMeshStorage();
             const deviceMap = await storage.getItem("meshDeviceMap") || {};
@@ -343,7 +268,7 @@ module.exports = function(RED) {
     });
 
     // 串口列表API - 使用公共串口工具模块
-    RED.httpAdmin.get("/modbus-slave-switch/serialports", async function(req, res) {
+    httpAdmin.registerGet(RED, "/modbus-slave-switch/serialports", "modbus-slave-switch.read", async function(req, res) {
         try {
             const ports = await serialUtils.getSerialPortList(RED);
             // 转换为旧版格式以保持兼容性

package/nodes/serial-port-config.js

@@ -10,6 +10,7 @@ module.exports = function(RED) {
     const storage = require("node-persist");
     const meshProtocol = require("./mesh-protocol")(RED);
     const serialUtils = require("../lib/serial-utils");
+    const httpAdmin = require("../lib/http-admin-utils");
 
     const { SerialPort } = require("serialport");
     const net = require("net");
@@ -1134,7 +1135,7 @@ module.exports = function(RED) {
     RED.nodes.registerType("serial-port-config", SerialPortConfigNode);
 
     // 提供串口搜索API - 使用公共串口工具模块
-    RED.httpAdmin.get("/serial-ports", async (_req, res) => {
+    httpAdmin.registerGet(RED, "/serial-ports", "serial-port-config.read", async (_req, res) => {
         try {
             const ports = await serialUtils.getSerialPortList(RED);
             res.json(ports);
@@ -1144,7 +1145,7 @@ module.exports = function(RED) {
     });
 
     // 提供Mesh实体列表API (用于透明节点选择)
-    RED.httpAdmin.get("/symi-mesh/entities", (req, res) => {
+    httpAdmin.registerGet(RED, "/symi-mesh/entities", "serial-port-config.read", (req, res) => {
         try {
             const configId = req.query.configId;
             if (!configId) {
@@ -1199,7 +1200,7 @@ module.exports = function(RED) {
     });
 
     // 删除Mesh实体API
-    RED.httpAdmin.delete("/symi-mesh/entity/:configId/:shortAddr", RED.auth.needsPermission("serial-port-config.write"), async (req, res) => {
+    httpAdmin.registerDelete(RED, "/symi-mesh/entity/:configId/:shortAddr", "serial-port-config.write", async (req, res) => {
         try {
             const configId = req.params.configId;
             const shortAddr = req.params.shortAddr;

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "node-red-contrib-symi-modbus",
-  "version": "2.10.17",
+  "version": "2.10.19",
   "description": "Node-RED Modbus节点，支持TCP/串口通信、多主站独立运行、串口自动搜索、多设备轮询、可选MQTT集成（支持纯本地模式和MQTT模式）、Home Assistant自动发现、HomeKit网桥、可视化控制看板、自定义协议转换和物理开关面板双向同步（支持Symi/Clowire品牌），工控机长期稳定运行",
   "main": "nodes/modbus-master.js",
   "scripts": {
     "lint": "eslint nodes/*.js lib/*.js --ext .js",
     "lint:fix": "eslint nodes/*.js lib/*.js --ext .js --fix",
-    "test": "echo \"Error: no test specified\" && exit 0"
+    "test": "node --test test/*.test.js"
   },
   "keywords": [
     "node-red",