Node-RED 保姆级部署教程：低代码事件驱动编程，浏览器拖拽搭建自动化流程

一、项目介绍

Node-RED 是一款低代码、事件驱动的编程工具（官方 README 副标题："Low-code programming for event-driven applications"），由 Nick O'Leary 等人开发，现为 OpenJS Foundation 基金会项目。它在浏览器中提供可视化编辑器，用户通过拖拽节点、连线的方式，即可把硬件设备、本地服务与在线 API 编排成自动化流程（Flow），广泛应用于物联网、家居自动化、数据采集与 API 聚合等场景。

项目在 GitHub（node-red/node-red）长期活跃维护，官方提供完整的文档站、节点库与 Docker 镜像（nodered/node-red）。

二、功能拆解

按官方 README 与官方站点，核心能力如下：

功能	说明
可视化流式编程	浏览器编辑器内拖拽节点、连线编排事件驱动流程
内置节点调色板	注入（Inject）、调试（Debug）、HTTP、MQTT、WebSocket、定时、函数（Function）等常用节点
社区节点库	flows.nodered.org 提供大量自定义节点（Custom Nodes & Integrations）与共享流程（Shared Flows）
事件驱动	由消息触发，支持多种输入/输出协议
单文件流程	流程保存在 flows.json，易于备份与迁移
凭据加密	流程凭据使用 credentialSecret 加密存储

三、官方/GitHub 链接

GitHub 仓库：https://github.com/node-red/node-red
官方网站：https://nodered.org/
官方文档：https://nodered.org/docs/
快速上手：https://nodered.org/docs/getting-started/
节点库（flows.nodered.org）：https://flows.nodered.org/
Docker 镜像：https://hub.docker.com/r/nodered/node-red
官方论坛：https://discourse.nodered.org ｜ Slack：https://nodered.org/slack

四、环境要求

官方提供两种原生部署方式（本教程两种都按官方原文给出）：

方式 A：npm 全局安装（官方 README Quick Start）。需要安装了 Node.js 与 npm 的环境，执行命令需要 sudo 权限。
方式 B：Docker 容器（官方 Docker 文档）。只需要 Docker；容器内含 Node.js 运行时。
端口：默认 1880（Web 编辑器）。官方 Docker 文档注明"browse to http://{host-ip}:1880"。
数据目录：Docker 方式下用户数据目录为容器内 /data（官方日志输出 User directory : /data），须挂载卷持久化。
硬件：官方文档未给出最低硬件指标。

五、部署步骤

方式 A：npm 全局安装（官方 README Quick Start）

步骤 1：全局安装 node-red

sudo npm install -g --unsafe-perm node-red

逐段解释：sudo 以管理员权限执行；npm install -g 全局安装 npm 包；--unsafe-perm 允许以 root 身份运行安装脚本（官方原命令自带该参数）；node-red 是包名。

预期输出参考： npm 安装进度条，结束时输出 added N packages in Xs 与全局安装路径。

步骤 2：启动

node-red

逐段解释：直接运行全局安装的 node-red 命令，前台启动服务。

预期输出参考（官方 Docker 文档给出了相同形态的启动日志）：

Welcome to Node-RED
===================
... [info] Node-RED version: vX.Y.Z
... [info] Node.js  version: vXX.X.X
... [info] Settings file  : /home/user/.node-red/settings.js
... [info] User directory : /home/user/.node-red
... [info] Flows file     : /home/user/.node-red/flows.json
... [info] Starting flows
... [info] Started flows
... [info] Server now running at http://127.0.0.1:1880/

步骤 3：打开编辑器

浏览器访问 http://localhost:1880（官方 README 第 3 步原文）。

方式 B：Docker 部署（官方 Docker 文档 Quick Start）

步骤 1：启动容器（官方原命令）

docker run -it -p 1880:1880 -v node_red_data:/data --name mynodered nodered/node-red

逐段解释：docker run 运行容器；-it 附加终端会话以便观察输出；-p 1880:1880 将本机 1880 端口连接到容器暴露的 1880 端口；-v node_red_data:/data 挂载一个名为 node_red_data 的 Docker 命名卷到容器 /data 目录，使流程变更持久化；--name mynodered 给容器起友好名字；nodered/node-red 是官方镜像。

预期输出参考（官方文档原文）：

Welcome to Node-RED
===================
10 Oct 12:57:10 - [info] Node-RED version: v1.2.0
10 Oct 12:57:10 - [info] Node.js version: v10.22.1
10 Oct 12:57:10 - [info] Linux 4.19.76-linuxkit x64 LE
10 Oct 12:57:11 - [info] Loading palette nodes
10 Oct 12:57:16 - [info] Settings file : /data/settings.js
10 Oct 12:57:16 - [info] Context store : 'default' [module=memory]
10 Oct 12:57:16 - [info] User directory : /data
10 Oct 12:57:16 - [info] Flows file : /data/flows.json
10 Oct 12:57:16 - [info] Creating new flow file
10 Oct 12:57:17 - [info] Starting flows
10 Oct 12:57:17 - [info] Started flows
10 Oct 12:57:17 - [info] Server now running at http://127.0.0.1:1880/

步骤 2：验证并转入后台运行

官方文档："You can then browse to http://{host-ip}:1880 to get the familiar Node-RED desktop." 确认界面可用后，按 Ctrl-p Ctrl-q 脱离终端（容器继续后台运行）。

步骤 3：后台（headless）启动方式（官方原命令）

如果一开始就想后台运行，官方文档说明把 -it 换成 -d 即可：

docker run -d -p 1880:1880 -v node_red_data:/data --name mynodered nodered/node-red

逐段解释：-d（detached）后台运行，不占用终端。

步骤 4（可选）：使用宿主目录持久化（官方 Bind Mount 方式）

docker run -it -p 1880:1880 -v /home/pi/.node-red:/data --name mynodered nodered/node-red

逐段解释：将宿主目录 /home/pi/.node-red 绑定到容器 /data。官方文档特别注明：容器内 Node-RED 用户默认 uid=1000，宿主目录属主必须同为 1000，否则权限报错；从 0.20 迁移到 1.0 的用户需执行 sudo chown -R 1000:1000 path/to/your/node-red/data。

六、配置参数详解

1. 配置文件与目录（官方文档）： 用户数据目录为 /data（Docker）或 ~/.node-red（npm 方式）；设置文件为 settings.js，流程文件为 flows.json（默认）。

2. Docker 环境变量（官方 Docker 文档「Startup」一节）：

变量	说明（官方原文要点）
FLOWS	流程文件名，默认 `flows.json`；设 `-e FLOWS=my_flows.json` 可改；设空则回落到 settings.js 的 flowFile 属性
NODE_RED_CREDENTIAL_SECRET	凭据加密密钥，settings.js 中写 `credentialSecret: process.env.NODE_RED_CREDENTIAL_SECRET` 后由 `-e "NODE_RED_CREDENTIAL_SECRET=..."` 传入
NODE_RED_ENABLE_SAFE_MODE	设为 true 时以安全模式启动（不运行流程）
NODE_RED_ENABLE_PROJECTS	设为 true 时启用 Projects 功能
NODE_OPTIONS	透传 Node.js 运行时参数，如 `-e NODE_OPTIONS="--max_old_space_size=128"`
TZ	时区，如 `-e TZ=America/New_York`（官方示例）

官方命令示例：

docker run -it -p 1880:1880 -v node_red_data:/data -e FLOWS=my_flows.json nodered/node-red

3. 编辑器认证 adminAuth（官方安全文档）： 在 settings.js 中启用用户名密码认证，示例：

adminAuth: {
type: "credentials",
users: [
{ username: "admin", password: "$2a$08$zZWtXTja0fB1pzD4sHCMyOCMYz2Z6dNbM6tl8sJogENOMcxWV9DN.", permissions: "*" }
] }

逐段解释：type: "credentials" 使用账号密码认证；users 数组定义用户，password 为 bcrypt 哈希（官方文档注明该示例哈希对应的明文密码为 password）；permissions: "*" 表示全部权限（只读为 "read"）。

4. 生成密码哈希（官方命令）：

node-red admin hash-pw

逐段解释：官方安全文档说明（Node-RED 1.1.0 及以上）执行该命令后输入密码，返回 bcrypt 哈希，将其粘贴进 settings.js 的 users 数组。预期输出参考： 交互式提示输入密码两遍，输出 $2b$08$... 形式的哈希字符串。

七、启动与运维

前台/后台： 前台 docker run -it ...；后台 docker run -d ...（官方 headless 一节）。
停止/启动/重连： 官方 Docker 文档：docker stop mynodered、docker start mynodered（如重启 Docker 守护进程后恢复容器）、docker attach mynodered（重新附加终端看日志）。
开机自启： 官方 Docker 文档未提供 Node-RED 专用自启配置；如需容器随 Docker 守护进程启动，可使用 Docker 平台通用的 --restart 参数创建容器（属 Docker 原生能力，非 Node-RED 官方文档内容）。
修改端口： 官方「Multiple Instances」一节展示了仅指定 -p 1880 时由 Docker 随机分配宿主端口，docker ps 查看映射（如 0.0.0.0:32768->1880/tcp）。固定端口同理，把 -p 1880:1880 改成 -p 你的端口:1880 即可。
容器内安装节点： 官方「Container Shell」一节：

docker exec -it mynodered /bin/bash
bash-4.4$ npm install node-red-dashboard
bash-4.4$ exit
docker stop mynodered && docker start mynodered

逐段解释：docker exec -it mynodered /bin/bash 进入容器 shell；在容器内 npm install node-red-dashboard 安装社区节点（官方示例）；退出后重启容器，刷新浏览器即可在调色板看到新节点。

数据备份： 官方文档提供 docker cp mynodered:/data /your/backup/directory 备份 /data 目录。

八、实操验证

浏览器访问 http://localhost:1880（官方："browse to http://{host-ip}:1880 to get the familiar Node-RED desktop"）。
左侧调色板拖入 inject（注入）与 debug（调试）节点到画布，用连线连接，点击右上角 Deploy 部署。
点击注入节点左侧按钮触发一次，右侧 debug 面板输出一条消息（时间戳或负载），流程即验证成功。
验证持久化：官方启动日志显示首次运行会 Creating new flow file（生成 /data/flows.json）；执行 docker stop mynodered && docker start mynodered 后刷新页面，刚才的流程仍在。

登录与安全（重要）

官方默认登录状态：默认无登录。 官方安全文档明确：默认情况下 Node-RED 编辑器不启用认证，任何人都可访问编辑流程——公网部署必须启用认证。
启用认证： 按官方安全文档在 settings.js 中启用 adminAuth（见第六节示例）。官方文档示例账号为 admin，示例哈希对应明文密码为 password——该密码仅用于文档演示，正式启用时必须用 node-red admin hash-pw 生成自己的哈希并设置强密码。
登录地址： 启用 adminAuth 后，访问 http://localhost:1880 会要求登录（OAuth 策略下回调地址格式为 http://localhost:1880/auth/strategy/callback，官方文档原文）。
修改密码： 重新执行 node-red admin hash-pw 生成新哈希，替换 settings.js 中该用户的 password 字段，重启 Node-RED 生效。
密码配置存放位置： settings.js 文件——Docker 方式为 /data/settings.js（宿主卷对应目录），npm 方式为 ~/.node-red/settings.js。
凭据加密密钥： 官方启动日志警告：若使用系统生成的密钥加密凭据文件，密钥丢失则凭据不可恢复；应通过 credentialSecret / NODE_RED_CREDENTIAL_SECRET 设置自己的密钥（官方原文："You should set your own key using the 'credentialSecret' option"）。
安全提醒：部署完成后必须启用认证并修改默认密码，切勿长期使用官方示例账号密码或将编辑器暴露在公网。

九、故障排查

案例 1：permission denied（官方文档「User Permission Errors」）

报错原文（常见形式）：Error: EACCES: permission denied, open '/data/flows.json' 或访问宿主设备被拒。
报错原因：官方文档说明容器内 Node-RED 用户（默认 uid=1000）与宿主数据目录属主不一致；1.0 起 /data 需要 1000:1000 属主。
分步解决：① 停止容器 docker stop mynodered；② 修正属主 sudo chown -R 1000:1000 path/to/your/node-red/data；③ 重启 docker start mynodered。官方文档同时提供以 root 用户运行的备选命令：docker run -it -p 1880:1880 -v node_red_data:/data --name mynodered -u node-red:dialout nodered/node-red（参考资料为 node-red/node-red-docker Issues #15、#8）。

案例 2：凭据文件加密密钥丢失警告

报错原文（官方启动日志）：

Your flow credentials file is encrypted using a system-generated key.
If the system-generated key is lost for any reason, your credentials file will not be recoverable...

报错原因：未设置 credentialSecret，系统生成了临时密钥。
分步解决：① 在 settings.js 中加入 credentialSecret: process.env.NODE_RED_CREDENTIAL_SECRET（官方原文）；② 创建容器时传入 -e "NODE_RED_CREDENTIAL_SECRET=你的密钥"；③ 重启容器，Node-RED 将用你的密钥重新加密凭据。

案例 3：端口被占用（bind: address already in use）

报错原文（常见形式）：Error response from daemon: driver failed programming external connectivity ... bind: address already in use
报错原因：本机 1880 端口已被其他进程或旧容器占用。
分步解决：① 换用其他宿主端口（官方多实例一节的随机端口示例即端口可自由指定的依据），如 docker run -d -p 1881:1880 -v node_red_data:/data --name mynodered nodered/node-red；② 或先释放端口：docker ps 找到占用容器后 docker stop 容器名。

案例 4：无法访问宿主串口/硬件设备

报错原因：容器默认不访问宿主设备（官方文档「Accessing Host Devices」）。
分步解决：官方命令添加设备直通 --device=/dev/ttyACM0，或加入 dialout 组 --group-add dialout（官方文档原文）。

十、升级、回滚与卸载

升级（官方 Docker 文档「Updating」一节，原文命令）：

docker pull nodered/node-red
docker stop mynodered
docker rm mynodered
docker run -it -p 1880:1880 -v node_red_data:/data --name mynodered nodered/node-red

逐段解释：docker pull 拉取新镜像；docker stop/docker rm 停止并删除旧容器；用同一数据卷重新运行。官方文档强调："As the /data is now preserved outside of the container, updating the base container image is now as simple as ..."——因为 /data 在容器外持久化，升级不丢流程与凭据。

npm 方式升级： 官方未在 README 中给出具体命令，升级说明见官方文档 https://nodered.org/docs/getting-started/upgrading （以官方文档为准，勿自行编造命令）。

回滚： 官方未提供专门回滚命令；可基于 Docker 镜像标签机制，将镜像指定为旧版本标签（如 nodered/node-red:旧版本）后按升级同款命令重新运行容器（数据卷保留）。

卸载： Docker 方式：docker stop mynodered && docker rm mynodered 删除容器；数据卷如需一并删除执行 docker volume rm node_red_data（此操作永久删除全部流程与凭据，先备份——官方提供 docker cp mynodered:/data /your/backup/directory 备份命令）。npm 方式：使用 npm 通用命令 npm uninstall -g node-red 卸载，并删除用户目录 ~/.node-red（含 flows 与设置）。

十一、商用许可合规说明

许可证：Apache License 2.0。官方 README 明确："Node-RED is a project of the OpenJS Foundation. Copyright OpenJS Foundation and other contributors ... under the Apache 2.0 license"。
Apache-2.0 允许自由使用、修改、分发与商用；分发时须保留版权声明与许可文本，修改过的文件须标注变更，并附带 NOTICE（如有）。
Node-RED 由 OpenJS Foundation 基金会治理；商用部署无需付费授权，社区节点库中的第三方节点按其各自许可证单独授权。