node-red

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Node-RED Flow Development

Node-RED流程开发

This skill provides comprehensive support for Node-RED development, including flow creation, modification, validation, and deployment through the Admin API.

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

When to Use This Skill

何时使用此技能

Use this skill when:

Creating or modifying Node-RED flows (flows.json files)
Building MQTT, HTTP API, or data pipeline integrations
Debugging or validating flow configurations
Working with function nodes and context storage
Deploying flows via the Node-RED Admin API
Converting requirements into Node-RED flow implementations

在以下场景使用此技能：

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

Available Resources

可用资源

Scripts (scripts/)

脚本（scripts/）

Execute these Python scripts for common Node-RED operations:

generate_uuid.py - Generate valid Node-RED node IDs
bash
```
python scripts/generate_uuid.py [count]
```
validate_flow.py - Validate flow JSON structure and wire connections
bash
```
python scripts/validate_flow.py <flow.json>
```

wire_nodes.py - Connect nodes programmatically

bash

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

create_flow_template.py - Generate boilerplate flows

bash

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

执行以下Python脚本以完成常见的Node-RED操作：

generate_uuid.py - 生成有效的Node-RED节点ID
bash
```
python scripts/generate_uuid.py [count]
```
validate_flow.py - 验证流程JSON结构和连线
bash
```
python scripts/validate_flow.py <flow.json>
```

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

bash

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

create_flow_template.py - 生成样板流程

bash

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

References (references/)

参考资料（references/）

Consult these detailed references as needed:

node_schemas.md - Complete schemas for all Node-RED node types
api_reference.md - Node-RED Admin API documentation with examples
function_snippets.md - Reusable function node code patterns

根据需要查阅以下详细参考资料：

node_schemas.md - 所有Node-RED节点类型的完整 schema
api_reference.md - 带示例的Node-RED Admin API文档
function_snippets.md - 可复用的函数节点代码模式

Assets (assets/)

资源文件（assets/）

Use these templates and boilerplate files:

templates/mqtt_flow.json - Complete MQTT pub/sub flow with error handling
templates/http_api_flow.json - REST API with CRUD operations and authentication
boilerplate/function_async.js - Async function node patterns
boilerplate/function_context.js - Context storage examples

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

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

Core Workflow

核心工作流

Creating a New Flow

创建新流程

Determine the flow type needed (MQTT, HTTP API, data processing, etc.)
Generate a template using
```
scripts/create_flow_template.py
```
Modify the template to match requirements
Validate the flow using
```
scripts/validate_flow.py
```
Deploy via Admin API or save as flows.json

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

Modifying Existing Flows

修改现有流程

Read and parse the flows.json file
Identify nodes by type and ID
Make modifications while preserving:
- Wire connections (arrays of node IDs)
- Tab references (
```
z
```
  property)
- Node coordinates (
```
x
```
  ,
```
y
```
  )
Validate changes before saving
Use
```
scripts/wire_nodes.py
```
to connect nodes if needed

读取并解析flows.json文件
按类型和ID识别节点
在修改时保留以下内容：
- 连线（节点ID数组）
- 标签页引用（
```
z
```
  属性）
- 节点坐标（
```
x
```
  ,
```
y
```
  ）
保存前验证更改
如有需要，使用
```
scripts/wire_nodes.py
```
连接节点

Working with Function Nodes

使用函数节点

For function nodes, reference:

```
assets/boilerplate/function_async.js
```
for async operations
```
assets/boilerplate/function_context.js
```
for context storage
```
references/function_snippets.md
```
for specific patterns

Available objects in function nodes:

```
msg
```
- Message object
```
node
```
- Node API (send, done, error, warn, log, status)
```
context
```
- Node-scoped storage
```
flow
```
- Flow-scoped storage
```
global
```
- Global storage
```
RED
```
- Runtime API
```
env
```
- Environment variables

使用函数节点时，请参考：

```
assets/boilerplate/function_async.js
```
用于异步操作
```
assets/boilerplate/function_context.js
```
用于上下文存储
```
references/function_snippets.md
```
用于特定模式

函数节点中的可用对象：

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

Deploying Flows

部署流程

To deploy flows via the Admin API:

Retrieve current configuration:
bash
```
GET /flows
```
Modify the configuration as needed

Deploy with appropriate deployment type:

bash

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

Verify deployment success

通过Admin API部署流程：

获取当前配置：
bash
```
GET /flows
```
根据需要修改配置

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

bash

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

验证部署是否成功

Common Patterns

常见模式

Message Flow Structure

消息流程结构

Every Node-RED message follows this pattern:

Primary data in
```
msg.payload
```
Topic/category in
```
msg.topic
```
Unique ID in
```
msg._msgid
```
Additional properties as needed

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

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

Error Handling

错误处理

Implement error handling using:

Try-catch blocks in function nodes
Catch nodes to intercept errors
Status nodes to monitor node states
Dedicated error output wires

使用以下方式实现错误处理：

函数节点中的try-catch块
Catch节点拦截错误
Status节点监控节点状态
专用的错误输出连线

Environment Variables

环境变量

Use environment variables for configuration:

In node properties:
```
$(ENV_VAR_NAME)
```
In function nodes:
```
env.get("ENV_VAR_NAME")
```
Via Docker:
```
-e KEY=value
```

使用环境变量进行配置：

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

Context Storage Levels

上下文存储级别

Choose appropriate context level:

Node context: Local to single node
Flow context: Shared within flow/tab
Global context: System-wide sharing
Persistent: Survives restarts (configure in settings.js)

选择合适的上下文级别：

节点上下文：仅单个节点可用
流程上下文：在流程/标签页内共享
全局上下文：系统级共享
持久化：重启后保留（在settings.js中配置）

Validation Checklist

验证检查清单

Before deploying flows, verify:

JSON syntax is valid
All wire connections reference existing node IDs
Tab references (
```
z
```
property) are correct
Function node JavaScript is syntactically valid
Required configuration nodes exist (MQTT brokers, etc.)
Environment variables are properly referenced
Error handling is implemented

部署流程前，请验证：

JSON语法有效
所有连线引用的节点ID均存在
标签页引用（
```
z
```
属性）正确
函数节点的JavaScript语法有效
所需的配置节点存在（如MQTT代理等）
环境变量引用正确
已实现错误处理

Quick Commands

快速命令

Generate five Node-RED UUIDs:

bash

python scripts/generate_uuid.py 5

Create an MQTT flow template:

bash

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

Validate a flow file:

bash

python scripts/validate_flow.py flows.json

Wire two nodes together:

bash

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

生成5个Node-RED UUID：

bash

python scripts/generate_uuid.py 5

创建MQTT流程模板：

bash

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

验证流程文件：

bash

python scripts/validate_flow.py flows.json

连接两个节点：

bash

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

Node-RED Configuration

Node-RED配置

Default File Locations

默认文件位置

Flows:
```
~/.node-red/flows_<hostname>.json
```
Settings:
```
~/.node-red/settings.js
```
Custom nodes:
```
~/.node-red/node_modules/
```

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

Running Node-RED

运行Node-RED

Normal mode:
```
node-red
```
Safe mode (no flow execution):
```
node-red --safe
```
Custom flow file:
```
node-red myflows.json
```

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

Best Practices

最佳实践

Use appropriate node types: Prefer change nodes over function nodes for simple transformations
Implement error handling: Always include catch nodes for critical paths
Document flows: Use comment nodes and node descriptions
Organize with tabs: Separate flows by logical function or system
Version control: Store flows.json in git with meaningful commit messages
Test incrementally: Deploy and test small changes frequently
Monitor performance: Use status nodes and debug output wisely

使用合适的节点类型：对于简单转换，优先使用变更节点而非函数节点
实现错误处理：关键路径始终包含Catch节点
为流程添加文档：使用注释节点和节点描述
用标签页组织：按逻辑功能或系统拆分流程
版本控制：将flows.json存储在git中，并使用有意义的提交信息
增量测试：频繁部署并测试小范围更改
监控性能：合理使用状态节点和调试输出

Troubleshooting

故障排除

For common issues:

Invalid JSON: Use
```
scripts/validate_flow.py
```
to find syntax errors
Broken wires: Check that all wired node IDs exist
Missing configurations: Ensure broker/server configs are included
Function errors: Test JavaScript in isolation first
API deployment fails: Verify authentication and check revision conflicts

针对常见问题：

无效JSON：使用
```
scripts/validate_flow.py
```
查找语法错误
连线断裂：检查所有连线的节点ID是否存在
缺少配置：确保包含代理/服务器配置
函数错误：先在隔离环境中测试JavaScript
API部署失败：验证身份认证并检查版本冲突

Additional Resources

额外资源

For detailed specifications and examples:

Consult
```
references/node_schemas.md
```
for node property details
Review
```
references/api_reference.md
```
for API operations
Use
```
references/function_snippets.md
```
for tested code patterns
Copy templates from
```
assets/templates/
```
as starting points

如需详细规范和示例：

查阅
```
references/node_schemas.md
```
获取节点属性详情
查看
```
references/api_reference.md
```
获取API操作说明
使用
```
references/function_snippets.md
```
获取经测试的代码模式
从
```
assets/templates/
```
复制模板作为起点