智能灌溉系统通讯与控制节点部署详细指南

📘 文档版本: v2.0 详细版
📝 适用场景: RK3588 主控板 + 宝塔面板 + Docker 容器化部署
🎯 目标: 部署 MQTT 消息中间件(EMQX) + 可视化控制台(Node-RED)
⏱️ 预计耗时: 30-45 分钟（首次部署）

---

📋 目录

1. 部署环境概述
2. 宝塔面板防火墙配置
3. EMQX (MQTT 消息中间件) 部署
4. Node-RED (可视化控制台) 部署
5. 系统联调与验证
6. 故障排查指南
7. 附录与参考资料

---

一、部署环境概述

1.1 硬件平台详解

组件	规格说明	作用
核心控制板	RK3588 架构（ARM64）	系统主控，运行 Linux 系统和各项服务
存储	eMMC/SD 卡（建议 ≥32GB）	系统盘及数据持久化存储
网络接口	以太网 / WiFi	局域网内通讯及外部访问
USB 接口	USB 3.0 × 2	连接 MCGS 触摸屏、4G 模块等外设

RK3588 简介:
RK3588 是瑞芯微推出的高性能 ARM 处理器，采用 8nm 工艺，集成 4×Cortex-A76 + 4×Cortex-A55 核心，具备强大的边缘计算能力，非常适合作为物联网网关或工业控制器使用。

1.2 软件环境

软件	版本要求	用途
操作系统	Linux (Armbian/Ubuntu/Debian)	基础运行环境
宝塔面板	最新版	Web 端服务器管理工具
Docker	20.10+	容器化部署环境
Docker Compose	可选	多容器编排（进阶使用）

1.3 网络拓扑说明

┌─────────────────────────────────────────────────────────────┐
│                         局域网 (192.168.137.0/24)            │
│  ┌─────────────┐        ┌─────────────┐        ┌─────────┐  │
│  │   PC 电脑    │◄──────►│  RK3588 主板  │◄──────►│ 路由器   │  │
│  │  (开发/监控) │  :1880 │  (本系统)    │  :1883 │ (网关)   │  │
│  │             │  :18083 │             │        │         │  │
│  └─────────────┘        └──────┬──────┘        └────┬────┘  │
│                                │                    │       │
│                         :1883  │                    │       │
│                         ┌──────┴──────┐             │       │
│                         │ MCGS 触摸屏  │             │       │
│                         │ (下位机)     │             │       │
│                         └─────────────┘             │       │
│                                                      │       │
└──────────────────────────────────────────────────────┼───────┘
                                                       │
                                               ┌───────┴─────┐
                                               │   互联网     │
                                               │  (远程访问)  │
                                               └─────────────┘

本机 IP 地址: 192.168.137.238（请根据实际网络环境修改）

---

二、宝塔面板防火墙配置（关键前提）

2.1 为什么必须配置防火墙？

宝塔面板内置了系统防火墙管理功能。在 Linux 系统中，默认情况下会启用 iptables/nftables 防火墙，阻挡外部连接。如果不放行特定端口，PC 端将无法访问主板上的服务。

2.2 端口功能详解

端口	协议/服务	用途说明	来源方向
1883	MQTT TCP	设备端 MQTT 通讯（MCGS、传感器等）	设备 → 主板
8883	MQTTS TCP	MQTT over TLS（加密通讯）	设备 → 主板
8083	MQTT WS	MQTT over WebSocket	Web 端 → 主板
8084	MQTT WSS	MQTT over WebSocket Secure	Web 端 → 主板
18083	HTTP	EMQX Dashboard 管理后台	PC 浏览器 → 主板
1880	HTTP	Node-RED 编辑器 + Dashboard UI	PC 浏览器 → 主板

2.3 详细配置步骤

步骤 1: 登录宝塔面板

1. 在浏览器中输入宝塔面板地址：

   http://192.168.137.238:8888
   

   注：宝塔默认端口为 8888，如已修改请使用实际端口

2. 输入用户名和密码登录

步骤 2: 进入防火墙管理

1. 点击左侧菜单栏的 “安全” 选项
2. 在右侧选择 “防火墙” 标签页
3. 确保系统防火墙状态为 “已开启”

步骤 3: 添加端口规则

依次添加以下端口放行规则：

操作	端口	协议	说明
添加	1883	TCP	MQTT 设备通讯
添加	8883	TCP	MQTT 加密通讯
添加	8083	TCP	MQTT WebSocket
添加	8084	TCP	MQTT WebSocket SSL
添加	18083	TCP	EMQX 管理后台
添加	1880	TCP	Node-RED 服务

具体操作:
1. 点击 “添加端口规则” 按钮
2. 在弹窗中填写：
– 端口: 填入上述端口号
– 协议: TCP
– 放行对象: 0.0.0.0/0（允许所有 IP）或指定局域网段
– 备注: 填写用途说明
3. 点击 “提交”

步骤 4: 验证放行状态

• 确认所有端口状态显示为 “正常” 或 “已放行”
• 如有误添加的规则，可点击 “删除” 移除

2.4 额外检查：系统级防火墙

有时宝塔面板防火墙与系统 iptables 规则可能冲突，建议额外检查：

# 查看当前防火墙规则
sudo iptables -L -n | grep -E "1883|1880|18083"

# 如使用 UFW（Ubuntu）
sudo ufw status

# 临时关闭防火墙测试（仅用于排查问题，测试后请开启）
sudo systemctl stop firewalld  # CentOS
sudo ufw disable              # Ubuntu

---

三、EMQX (MQTT 消息中间件) 部署与访问

3.1 什么是 MQTT 和 EMQX？

MQTT 协议简介

MQTT（Message Queuing Telemetry Transport）是一种基于发布/订阅模式的轻量级物联网通讯协议，特点：

• 轻量级: 报文头部最小仅 2 字节，适合带宽受限网络
• 发布/订阅模式: 设备不直接通讯，通过 Broker 中转
• QoS 等级: 支持 0（最多一次）、1（至少一次）、2（恰好一次）三种消息可靠性级别
• 遗嘱消息: 设备异常断开时可通知其他客户端
• 保留消息: 新订阅者立即收到最后一条消息

EMQX 简介

EMQX 是目前最流行的开源 MQTT Broker 之一：

• 高性能: 单机可支持百万级并发连接
• 企业级特性: 内置规则引擎、数据持久化、多协议网关
• 可视化: 提供 Dashboard 实时监控
• 云原生: 原生支持 Docker/Kubernetes 部署

3.2 部署方案对比

方案	优点	缺点	适用场景
Docker 容器	部署简单、环境隔离、易于迁移	需要 Docker 基础	开发测试、中小型项目
宝塔软件商店	图形化安装、一键配置	版本可能滞后	初学者、快速原型
原生安装	性能最优、完全可控	配置复杂、依赖管理	生产环境、大规模部署

本文采用 Docker 容器化部署 方案。

3.3 Docker 容器部署详解

步骤 1: 检查 Docker 环境

# 检查 Docker 是否安装
docker --version
# 预期输出：Docker version 20.10.x 或更高

# 检查 Docker 服务状态
sudo systemctl status docker
# 确认状态为 active (running)

如未安装 Docker，可在宝塔面板的 “软件商店” 中搜索并安装。

步骤 2: 拉取并运行 EMQX 容器

# 执行以下命令（可复制到宝塔终端执行）
docker run -d --name emqx \
  -p 1883:1883 \
  -p 8083:8083 \
  -p 8084:8084 \
  -p 8883:8883 \
  -p 18083:18083 \
  emqx/emqx:latest

命令参数详解:

参数	说明
-d	后台运行（守护进程模式）
--name emqx	容器命名为 “emqx”，便于后续管理
-p 1883:1883	端口映射：主机端口:容器端口
emqx/emqx:latest	镜像名称:标签（latest 表示最新版）

步骤 3: 验证容器运行状态

# 查看容器列表
docker ps

# 预期输出示例：
# CONTAINER ID   IMAGE              STATUS          PORTS
# xxxxxxxx       emqx/emqx:latest   Up 2 minutes    0.0.0.0:1883->1883/tcp, ...

# 查看容器日志（排查启动问题）
docker logs emqx

# 查看 EMQX 进程状态
docker exec -it emqx emqx_ctl status
# 预期输出：Node 'emqx@127.0.0.1' 5.8.x is started

3.4 EMQX Dashboard 访问与配置

步骤 1: 访问管理后台

在 PC 浏览器中输入：

http://192.168.137.238:18083

步骤 2: 登录与密码修改

首次登录凭据:
– 用户名: admin
– 密码: public

强制修改密码:
首次登录后系统会强制要求修改密码，请：
1. 输入新密码（建议 8 位以上，包含大小写+数字）
2. 确认新密码
3. 点击 “修改密码”
4. 使用新密码重新登录

⚠️ 重要: 请妥善保存新密码，忘记密码需要进入容器重置。

步骤 3: Dashboard 功能导览

菜单项	功能说明
监控 → 概览	实时连接数、消息吞吐量、订阅数统计
连接管理	查看在线客户端列表、断开连接
主题监控	查看活跃的消息主题（Topic）
规则	配置消息路由规则（转发到数据库、HTTP 等）
插件	启用/禁用扩展功能
系统 → 设置	修改监听端口、认证方式等

步骤 4: WebSocket 客户端测试

用于在没有物理设备的情况下测试 MQTT 通讯：

1. 点击左侧菜单 “诊断” → “WebSocket 客户端”
2. 点击 “连接” 按钮
3. 在 发布 区域：
   • 主题: test/topic
   • 消息内容: {"status": "hello"}
4. 点击 “发布”
5. 在另一个浏览器标签页打开相同的 WebSocket 客户端：
   • 订阅主题: test/topic
   • 点击 “订阅”
6. 应能收到刚才发布的消息

3.5 MQTT 连接参数（供 MCGS 配置使用）

参数	值	说明
Broker 地址	192.168.137.238	EMQX 所在服务器 IP
端口	1883	标准 MQTT TCP 端口
Client ID	自定义（如 mcgs_001）	设备唯一标识
用户名	可选	如启用认证需填写
密码	可选	如启用认证需填写
Keep Alive	60 秒	心跳保持间隔
QoS	0 或 1	消息质量等级

---

四、Node-RED (可视化控制逻辑与 UI) 部署与访问

4.1 什么是 Node-RED？

Node-RED 是 IBM 开源的基于浏览器的可视化编程工具，特点：

• 流式编程: 通过拖拽节点、连接连线构建应用逻辑
• 低代码: 无需编写大量代码即可实现复杂功能
• 丰富的节点库: 3000+ 社区节点覆盖各类协议和服务
• 内置 Dashboard: 一键生成 Web 控制界面
• JavaScript 扩展: 需要时可编写函数节点实现自定义逻辑

4.2 典型应用场景

┌─────────────┐    MQTT    ┌─────────────┐    HTTP    ┌─────────────┐
│  MCGS/传感器 │ ────────► │  Node-RED   │ ────────► │  数据库/云端  │
│  (发布数据)  │           │  (数据处理)  │           │  (存储/分析)  │
└─────────────┘           └──────┬──────┘            └─────────────┘
                                 │
                                 │ Dashboard
                                 ▼
                          ┌─────────────┐
                          │  Web UI     │
                          │  (可视化界面) │
                          │  - 开关按钮   │
                          │  - 数据仪表   │
                          │  - 状态指示   │
                          └─────────────┘

4.3 数据持久化方案选择

Node-RED 默认将配置存储在容器内部，容器删除后数据丢失。持久化方案对比：

方案	命令	优点	缺点
Docker Volume	-v nodered_data:/data	简单、Docker 管理、权限兼容	备份需导出 volume
主机挂载	-v /opt/nodered:/data	直接访问文件、易备份	需处理 UID/GID 权限
绑定挂载	-v $(pwd)/data:/data	灵活、开发友好	同主机挂载，权限问题

推荐: 使用 Docker Volume 方案，避免权限问题。

4.4 Docker 容器部署详解

步骤 1: 创建并运行容器

docker run -d -p 1880:1880 \
  --name mynodered \
  -v nodered_data:/data \
  nodered/node-red:latest

为什么使用 --name mynodered 而不是默认名？
– 便于识别和管理多个 Node-RED 实例
– 后续命令可通过名称引用容器

步骤 2: 验证运行状态

# 查看容器状态
docker ps | grep mynodered

# 预期输出：
# CONTAINER ID   IMAGE                      STATUS          PORTS
# xxxxxxxx       nodered/node-red:latest    Up 3 minutes    0.0.0.0:1880->1880/tcp

# 查看启动日志
docker logs mynodered

# 预期输出包含：
# [info] Server now running at http://127.0.0.1:1880/
# [info] Starting flows

步骤 3: 访问编辑器

在 PC 浏览器中输入：

http://192.168.137.238:1880

界面布局说明：
– 左侧: 节点面板（可拖拽到工作区）
– 中间: 工作区（流编辑器）
– 右侧: 信息面板/调试输出/帮助文档
– 顶部: 部署按钮、菜单

4.5 Dashboard UI 插件安装

为什么需要 Dashboard？

Dashboard 插件为 Node-RED 提供了一套 UI 控件节点，可以快速构建 Web 控制界面，无需编写前端代码。

安装步骤

1. 点击右上角的 菜单图标（三条横线 ☰）
2. 选择 “节点管理”（Manage palette）
3. 切换到 “安装”（Install）标签页
4. 在搜索框输入: node-red-dashboard
5. 点击搜索结果右侧的 “安装” 按钮
6. 等待安装完成（约 30-60 秒）
7. 安装完成后会提示 “节点已添加”

验证安装

• 在左侧节点面板底部，新增 “dashboard” 分组
• 展开后可看到 UI 控件：Button、Switch、Slider、Numeric、Text input、Form、Gauge、Chart、Notification、UI Template 等

4.6 Dashboard 访问地址

配置并部署流后，可通过以下地址访问生成的控制界面：

http://192.168.137.238:1880/ui

界面特点:
– 自适应移动端布局
– 支持多页面/标签页
– 主题可自定义（颜色、布局）

---

五、系统联调与验证

5.1 完整系统架构图

┌─────────────────────────────────────────────────────────────────────┐
│                          PC 端（上位机）                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────┐  │
│  │ EMQX Dashboard  │  │ Node-RED Editor │  │ Node-RED Dashboard  │  │
│  │ :18083          │  │ :1880           │  │ :1880/ui            │  │
│  │ (监控管理)       │  │ (逻辑编程)       │  │ (操作界面)           │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ HTTP/MQTT
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      RK3588 主板 (192.168.137.238)                   │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │                      Docker 容器环境                          │  │
│  │  ┌──────────────────┐           ┌──────────────────┐         │  │
│  │  │   EMQX 容器       │◄─────────►│  Node-RED 容器    │         │  │
│  │  │   - 1883 MQTT    │  MQTT     │  - 1880 HTTP     │         │  │
│  │  │   - 18083 HTTP   │  数据流   │  - Dashboard UI  │         │  │
│  │  └────────┬─────────┘           └──────────────────┘         │  │
│  └───────────┼───────────────────────────────────────────────────┘  │
│              │                                                      │
│              │ MQTT                                                 │
└──────────────┼──────────────────────────────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                          设备层（下位机）                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────┐  │
│  │   MCGS 触摸屏    │  │   传感器模块     │  │   执行器/电磁阀     │  │
│  │   (数据采集)     │  │   (温度/湿度)    │  │   (灌溉控制)        │  │
│  │   发布: sensors/ │  │                  │  │   订阅: controls/   │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

5.2 端到端测试流程

测试 1: MQTT 基础通讯

1. 设备端模拟（使用 MCGS 或 MQTT.fx 工具）
   • 连接到 192.168.137.238:1883
   • Client ID: test_device_001
   • 发布消息到主题: irrigation/sensor1
   • 消息内容: {"temperature": 25.5, "humidity": 60}
2. EMQX 验证
   • 打开 Dashboard → 监控 → 连接
   • 确认 test_device_001 在线
   • 查看消息收发统计
3. Node-RED 接收验证
   • 添加 mqtt in 节点
   • 配置服务器: 192.168.137.238:1883
   • 订阅主题: irrigation/#（# 为通配符）
   • 连接 debug 节点
   • 部署并查看调试面板输出

测试 2: Dashboard 控制下发

1. Node-RED 配置
   • 添加 button 节点（Dashboard 分组）
   • 添加 mqtt out 节点
   • 配置发布主题: irrigation/control/pump1
   • 消息内容: ON 或 OFF
   • 连线: button → mqtt out
2. 执行端模拟
   • 使用 MQTT.fx 订阅 irrigation/control/pump1
   • 或查看 EMQX Dashboard → 监控 → 主题
3. 操作测试
   • 访问 `http://192.168.137.238:1880/ui`
   • 点击按钮
   • 验证 MQTT 消息是否下发

5.3 常用 Topic 设计建议

# 传感器数据上报
irrigation/sensors/temperature    # 温度数据
irrigation/sensors/humidity       # 湿度数据
irrigation/sensors/soil_moisture  # 土壤湿度
irrigation/sensors/flow_meter     # 流量计数据

# 控制命令下发
irrigation/control/pump1          # 水泵 1 开关
irrigation/control/valve1         # 电磁阀 1
irrigation/control/mode           # 工作模式(auto/manual)

# 系统状态
irrigation/status/connection      # 设备在线状态
irrigation/status/alarm           # 告警信息
irrigation/status/battery         # 电池电量

# 配置参数
irrigation/config/schedule        # 灌溉计划
irrigation/config/threshold       # 阈值设置

---

六、故障排查指南

6.1 连接问题排查

症状: 无法访问 EMQX Dashboard (18083)

排查步骤:

1. 检查容器状态

   docker ps | grep emqx
   # 如无输出，容器未运行
   docker logs emqx  # 查看启动错误
   

2. 检查端口监听

   sudo netstat -tlnp | grep 18083
   # 或
   sudo ss -tlnp | grep 18083
   

3. 检查防火墙

   sudo iptables -L -n | grep 18083
   # 确认端口已放行
   

4. 本地测试

   curl http://localhost:18083
   # 本地应能访问
   

5. 网络连通性

   # 在 PC 端执行
   ping 192.168.137.238
   telnet 192.168.137.238 18083
   

症状: MCGS 无法连接 MQTT (1883)

常见原因:
– IP 地址配置错误
– 端口未放行
– Client ID 冲突（多个设备使用相同 ID）
– 网络不通（防火墙/路由器隔离）

排查命令:

# 在 RK3588 上检查 MQTT 端口
docker exec emqx netstat -tlnp | grep 1883

# 查看 EMQX 连接日志
docker logs emqx | grep -i "connection\|client"

# 检查是否有连接数限制
docker exec emqx emqx_ctl conn stats

6.2 数据流问题排查

症状: Node-RED 收不到 MQTT 消息

排查步骤:

1. 检查 MQTT 节点配置
   • 服务器地址是否正确: 192.168.137.238
   • 端口: 1883
   • 订阅主题是否正确（注意大小写）
2. 使用 EMQX WebSocket 客户端测试
   • Dashboard → 诊断 → WebSocket 客户端
   • 订阅相同主题
   • 验证消息是否到达 EMQX
3. 检查 Node-RED 调试输出
   • 添加 debug 节点
   • 查看右侧调试面板
4. 检查 EMQX ACL（访问控制）

   docker exec emqx cat /opt/emqx/etc/acl.conf
   # 确认没有限制订阅权限
   

6.3 Node-RED 问题排查

症状: 节点安装失败

解决方法:

# 进入容器内部
docker exec -it mynodered /bin/bash

# 手动安装节点
cd /data
npm install node-red-dashboard

# 退出并重启容器
exit
docker restart mynodered

症状: 部署后流不执行

检查清单:
– [ ] 点击了右上角的 “部署” 按钮
– [ ] 没有红色虚线边框（表示节点配置错误）
– [ ] 查看调试面板是否有错误信息
– [ ] 检查节点状态（鼠标悬停查看）

6.4 日志查看指南

服务	查看日志命令
EMQX	docker logs emqx -f
Node-RED	docker logs mynodered -f
系统日志	sudo journalctl -xe
宝塔面板	面板 → 安全 → 系统日志

参数说明:
– -f: 实时跟踪（类似 tail -f）
– --tail 100: 只显示最后 100 行
– --since 10m: 显示最近 10 分钟的日志

---

七、附录与参考资料

7.1 常用 Docker 命令速查

# 容器管理
docker ps                    # 查看运行中的容器
docker ps -a                 # 查看所有容器（含已停止）
docker start emqx            # 启动容器
docker stop emqx             # 停止容器
docker restart emqx          # 重启容器
docker rm emqx               # 删除容器（需先停止）

# 镜像管理
docker images                # 查看本地镜像
docker pull emqx/emqx:latest # 拉取最新镜像
docker rmi emqx/emqx:latest  # 删除镜像

# 进入容器
docker exec -it emqx /bin/sh      # 进入 EMQX 容器
docker exec -it mynodered /bin/sh # 进入 Node-RED 容器

# 数据持久化
docker volume ls             # 查看数据卷
docker volume inspect nodered_data  # 查看数据卷详情
docker cp mynodered:/data /backup   # 备份数据

# 资源监控
docker stats                 # 查看容器资源使用
docker system df             # 查看磁盘使用

7.2 配置文件路径

服务	容器内路径	说明
EMQX	/opt/emqx/etc/emqx.conf	主配置文件
EMQX	/opt/emqx/etc/acl.conf	访问控制配置
EMQX	/opt/emqx/data/	数据存储
Node-RED	/data/settings.js	节点配置
Node-RED	/data/flows.json	流定义文件
Node-RED	/data/package.json	节点依赖

7.3 默认登录凭据汇总

服务	地址	用户名	默认密码	备注
宝塔面板	:8888	安装时设置	安装时设置	首次安装生成
EMQX	:18083	admin	public	首次登录必须修改
Node-RED	:1880	无	无	默认无认证

⚠️ 安全提示: 生产环境建议为 Node-RED 启用认证，编辑 settings.js 中的 adminAuth 配置。

7.4 推荐学习资源

• EMQX 官方文档: https://www.emqx.io/docs/
• Node-RED 官方文档: https://nodered.org/docs/
• MQTT 协议规范: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/
• Node-RED 流程示例: https://flows.nodered.org/

7.5 版本信息记录

建议记录实际部署版本，便于后续维护：

组件	部署版本	部署日期
EMQX	_____	_____
Node-RED	_____	_____
Docker	_____	_____
主板系统	_____	_____

---

文档结束

如有问题，请根据第六章节进行排查，或查阅各组件官方文档。