node-red

Node-RED 流开发

此技能为 Node-RED 开发提供全面支持，包括通过 Admin API 创建、修改、验证和部署流。

何时使用此技能

在以下情况下使用此技能：

• 创建或修改 Node-RED 流（flows.json 文件）
• 构建 MQTT、HTTP API 或数据管道集成
• 调试或验证流配置
• 使用 function 节点和上下文存储
• 通过 Node-RED Admin API 部署流
• 将需求转换为 Node-RED 流实现

可用资源

脚本（scripts/）

执行这些 Python 脚本，完成常见的 Node-RED 操作：

• generate_uuid.py - 生成有效的 Node-RED 节点 ID

  python scripts/generate_uuid.py [count]
  

• validate_flow.py - 验证流 JSON 结构和连线

  python scripts/validate_flow.py <flow.json>
  

• wire_nodes.py - 以编程方式连接节点

  python scripts/wire_nodes.py <flow.json> <source_id> <target_id> [output_port]
  

• create_flow_template.py - 生成样板流

  python scripts/create_flow_template.py <mqtt|http-api|data-pipeline|error-handler> [output.json]
  

参考文档（references/）

根据需要查阅以下详细参考文档：

• node_schemas.md - 所有 Node-RED 节点类型的完整架构
• api_reference.md - Node-RED Admin API 文档及示例
• function_snippets.md - 可复用的 function 节点代码模式

资源文件（assets/）

使用以下模板和样板文件：

• templates/mqtt_flow.json - 包含错误处理的完整 MQTT 发布/订阅流
• templates/http_api_flow.json - 支持 CRUD 操作和身份验证的 REST API
• boilerplate/function_async.js - 异步 function 节点模式
• boilerplate/function_context.js - 上下文存储示例

核心工作流

创建新流

1. 确定所需的流类型（MQTT、HTTP API、数据处理等）
2. 使用 scripts/create_flow_template.py 生成模板
3. 修改模板以满足需求
4. 使用 scripts/validate_flow.py 验证流
5. 通过 Admin API 部署，或保存为 flows.json

修改现有流

1. 读取并解析 flows.json 文件
2. 按类型和 ID 识别节点
3. 修改时保留：
   • 连线（节点 ID 数组）
   • 选项卡引用（z 属性）
   • 节点坐标（x、y）
4. 保存前验证修改
5. 如有需要，使用 scripts/wire_nodes.py 连接节点

使用 function 节点

对于 function 节点，请参考：

• assets/boilerplate/function_async.js，了解异步操作
• assets/boilerplate/function_context.js，了解上下文存储
• references/function_snippets.md，了解特定模式

function 节点中可用的对象：

• msg - 消息对象
• node - 节点 API（send、done、error、warn、log、status）
• context - 节点范围的存储
• flow - 流范围的存储
• global - 全局存储
• RED - 运行时 API
• env - 环境变量

部署流

通过 Admin API 部署流：

1. 获取当前配置：

   GET /flows
   

2. 根据需要修改配置

3. 使用适当的部署类型进行部署：

   POST /flows
   Headers: Node-RED-Deployment-Type: full|nodes|flows|reload
   

4. 验证部署是否成功

常见模式

消息流结构

每条 Node-RED 消息都遵循以下模式：

• 主要数据位于 msg.payload
• 主题/类别位于 msg.topic
• 唯一 ID 位于 msg._msgid
• 根据需要添加其他属性

错误处理

通过以下方式实现错误处理：

1. 在 function 节点中使用 try-catch 块
2. 使用 Catch 节点拦截错误
3. 使用 Status 节点监控节点状态
4. 使用专用错误输出连线

环境变量

使用环境变量进行配置：

• 在节点属性中：$(ENV_VAR_NAME)
• 在 function 节点中：env.get("ENV_VAR_NAME")
• 通过 Docker：-e KEY=value

上下文存储级别

选择合适的上下文级别：

• 节点上下文：仅限单个节点
• 流上下文：在流/选项卡内共享
• 全局上下文：系统范围内共享
• 持久化：重启后仍保留（在 settings.js 中配置）

验证清单

部署流程前，请确认：

• JSON 语法有效
• 所有连线都引用了现有节点 ID
• 选项卡引用（z 属性）正确
• Function 节点的 JavaScript 语法有效
• 所需的配置节点均已存在（MQTT 代理等）
• 环境变量引用正确
• 已实现错误处理

快速命令

生成 5 个 Node-RED UUID：

python scripts/generate_uuid.py 5

创建 MQTT 流程模板：

python scripts/create_flow_template.py mqtt my-mqtt-flow.json

验证流程文件：

python scripts/validate_flow.py flows.json

连接两个节点：

python scripts/wire_nodes.py flows.json inject-node-id debug-node-id

Node-RED 配置

默认文件位置

• 流程：~/.node-red/flows_<hostname>.json
• 设置：~/.node-red/settings.js
• 自定义节点：~/.node-red/node_modules/

运行 Node-RED

• 普通模式：node-red
• 安全模式（不执行流程）：node-red --safe
• 自定义流程文件：node-red myflows.json

最佳实践

1. 使用合适的节点类型：简单转换优先使用 change 节点，而非 function 节点
2. 实现错误处理：关键路径务必包含 catch 节点
3. 记录流程说明：使用注释节点和节点描述
4. 通过选项卡整理：按逻辑功能或系统拆分流程
5. 版本控制：将 flows.json 存入 git，并使用有意义的提交信息
6. 逐步测试：频繁部署并测试小幅更改
7. 监控性能：合理使用状态节点和调试输出

故障排除

常见问题：

• JSON 无效：使用 scripts/validate_flow.py 查找语法错误
• 连线断开：检查所有已连线的节点 ID 是否存在
• 缺少配置：确保包含代理/服务器配置
• Function 错误：先单独测试 JavaScript
• API 部署失败：验证身份验证并检查修订冲突

更多资源

详细规范和示例：

• 查阅 references/node_schemas.md，了解节点属性详情
• 查看 references/api_reference.md，了解 API 操作
• 使用 references/function_snippets.md 中经过测试的代码模式
• 从 assets/templates/ 复制模板作为起点