1. 项目概述与核心需求解析最近在折腾一块芒果派 MangoPi MQ Quad 开发板这是一款基于全志 D1s 处理器的 RISC-V 架构板子性能不错功耗也低很适合用来做一些物联网边缘端的应用。我的目标是在这块板子上搭建一个能够运行 Node.js 后端服务并集成 EMQX MQTT 消息中间件的环境为后续的智能家居数据网关或者设备管理平台打基础。对于嵌入式开发或者物联网项目来说直接在目标硬件上配置好稳定、可维护的开发环境是第一步也是最关键的一步能避免后续很多“水土不服”的问题。这个需求很明确我们需要一个灵活的 Node.js 环境来编写和运行业务逻辑同时需要一个轻量且高性能的 MQTT BrokerEMQX来处理设备与服务器、设备与设备之间的消息通信。直接在 ARM 或 RISC-V 架构的 Linux 系统上安装这些环境和我们在 x86 的云服务器上操作思路类似但细节上会遇到不少差异尤其是包管理、依赖库和编译工具链方面。接下来我就把在芒果派 MQ Quad 上从零开始部署 Node.js 和 EMQX 的完整过程、遇到的坑以及解决方案详细记录下来如果你也在类似的嵌入式 Linux 平台上做部署这份经验应该能帮你省下不少时间。2. 环境准备与系统基础配置在开始安装具体软件之前我们需要先确保芒果派 MQ Quad 的系统处于一个良好的基础状态。我使用的是官方推荐的 Tina Linux 系统基于 OpenWrt 改造或 Debian 镜像这里以 Debian 为例因为它有更完善的 apt 包管理工具后续安装会更方便。2.1 系统更新与基础依赖安装首先通过 SSH 连接到你的芒果派。建议在操作前更新一下软件源列表并升级已有的软件包这能确保我们安装的依赖是最新的减少兼容性问题。sudo apt update sudo apt upgrade -y更新完成后安装一些编译和基础运行所需的工具链。在嵌入式设备上从源码编译或安装二进制包时这些工具常常是必需的。sudo apt install -y curl wget git build-essential libssl-dev ca-certificates注意build-essential包含了 gcc、g、make 等基础编译工具。libssl-dev是 Node.js 编译和运行某些加密模块所必需的开发库。在资源受限的设备上如果镜像空间紧张可以酌情不安装build-essential前提是你确定要安装的软件都有对应架构的预编译二进制包。2.2 硬件与网络确认芒果派 MQ Quad 的 CPU 是全志 D1s这是一颗单核的 RISC-V 64 处理器。我们可以通过以下命令确认架构uname -m输出应该是riscv64。这一点非常重要因为后续我们寻找或编译软件时都必须针对riscv64或riscv架构。Node.js 官方提供了 ARM 和 x86 的预编译包但对于 RISC-V情况就复杂一些。同样EMQX 的官方 apt 源也主要面向 x86_64 和 ARM64我们需要确认是否有 RISC-V 的版本或者寻找替代的安装方式。3. Node.js 环境部署使用 NVM 进行灵活管理在开发板上直接安装特定版本的 Node.js 二进制包可能比较困难因为官方不一定提供对应架构的版本。因此我选择使用 NVM (Node Version Manager) 来管理 Node.js。NVM 的优势在于它可以通过源码编译的方式安装 Node.js这样就能适配任何支持的架构包括我们的 RISC-V。3.1 NVM 的工作原理与选型考量NVM 本质上是一个 shell 脚本它通过修改用户的环境变量主要是PATH来切换当前 shell 会话中使用的 Node.js 版本。它会将不同版本的 Node.js 安装在用户家目录下的独立文件夹中例如~/.nvm/versions/node/互不干扰。为什么选择 NVM 而不是直接apt install nodejs版本控制自由Debian 系统源里的 Node.js 版本往往比较旧。而物联网项目可能依赖较新的 Node.js 特性或者需要与云端服务保持版本一致NVM 可以安装任意官方发布的版本。多版本共存同一个板子上可能运行多个不同的 Node.js 应用它们要求的 Node.js 版本可能不同。NVM 可以让你为每个项目甚至每个终端会话快速切换版本。规避系统污染将 Node.js 安装在用户目录下不需要sudo权限避免了因误操作影响系统稳定性卸载也更为干净。3.2 使用国内源安装 NVMNVM 的官方安装脚本托管在 GitHub从国内访问可能速度慢或不稳定。幸运的是有国内开发者维护了镜像和安装脚本。我们采用一个修改后的脚本来加速安装过程。首先下载国内社区维护的安装脚本curl -fsSL https://gitee.com/RubyKids/nvm-cn/raw/main/install.sh -o install.sh下载后不要直接运行。我们需要先检查并修改脚本确保它从国内的 Gitee 镜像仓库克隆 NVM 源码而不是 GitHub。用vim或nano打开install.sh文件nano install.sh找到脚本中克隆仓库的部分通常在靠前的位置例如原脚本的34-40行附近。我们需要将git clone的源地址从 GitHub 改为 Gitee 的镜像地址。修改后的关键片段应如下所示export NVM_DIR$HOME/.nvm ( echo Git clone nvm git clone https://gitee.com/mirrors/nvm.git $NVM_DIR cd $NVM_DIR git checkout git describe --abbrev0 --tags --match v[0-9]* $(git rev-list --tags --max-count1) ) . $NVM_DIR/nvm.sh这里将仓库地址改为了https://gitee.com/mirrors/nvm.git这是 NVM 的一个国内镜像下载速度会快很多。修改保存后执行安装bash install.sh安装脚本会自动克隆 NVM 仓库到~/.nvm目录并将初始化命令添加到你的 shell 配置文件如~/.bashrc或~/.zshrc中。安装最后脚本可能会提示你输入密码以尝试将nvm-update脚本安装到/usr/local/bin/。在嵌入式设备上这一步通常可以跳过。直接按Ctrl C终止即可这不会影响 NVM 的核心功能。我们后续更新 NVM 本身完全可以在用户目录下进行。安装完成后需要重新加载 shell 配置或者新开一个终端窗口以使nvm命令生效source ~/.bashrc # 或者如果你用的是 zsh: source ~/.zshrc现在可以验证 NVM 是否安装成功nvm --version如果输出版本号如0.39.7说明安装成功。3.3 在 RISC-V 架构上安装 Node.js这是最关键也最容易出问题的一步。直接运行nvm install --lts或nvm install nodeNVM 会尝试下载对应架构的预编译二进制包。但 Node.js 官方不提供riscv64的预编译包因此下载会失败。NVM 的 fallback 机制是如果找不到预编译二进制包它会尝试从源码编译。编译 Node.js 对设备的内存和 CPU 有一定要求好在芒果派 MQ Quad 的 512MB 内存勉强够用但编译过程会非常漫长可能需要数小时。操作步骤与核心命令指定从源码编译我们可以通过-s参数明确告诉 NVM 从源码安装。nvm install -s 18.19.0这里我选择了 18.19.0 这个 LTS 版本相对稳定且生态兼容性好。你可以替换成任何你需要的版本号。漫长的编译过程执行上述命令后NVM 会开始下载 Node.js 源码包并运行./configure、make、make install。屏幕上会滚动大量的编译信息。在这个过程中请保持 SSH 连接稳定避免中断。如果编译因网络或内存不足失败可以尝试交换分区swap来缓解。启用交换文件可选但强烈建议编译 Node.js 可能耗尽内存。我们可以临时创建一个交换文件来充当虚拟内存。# 创建一个 1GB 的交换文件 sudo fallocate -l 1G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile编译完成后可以关闭并删除交换文件以释放存储空间sudo swapoff /swapfile sudo rm /swapfile验证安装编译安装完成后使用以下命令查看已安装的版本并设置为默认。nvm list nvm alias default 18.19.0 node --version npm --versionnvm list会列出所有安装的版本当前使用的版本前会有一个箭头-。nvm alias default可以设置默认版本这样新开的终端也会自动使用这个版本。实操心得与避坑指南耐心是关键在单核 RISC-V 上编译 Node.js 可能长达 3-5 小时。建议在晚上或不需要使用板子的时候进行。确保依赖完整如果编译失败仔细查看错误日志。常见的失败原因是缺少某些开发库。你可能需要额外安装python3、pkg-config等。根据错误提示使用apt安装对应的-dev包。版本选择不建议安装太新的奇数版本如 19.x, 21.x优先选择 LTS长期支持版本如 18.x 或 20.x它们在嵌入式环境下的稳定性和社区支持更好。NPM 源优化安装好 Node.js 后建议立即将 NPM 的注册表源换成国内镜像加速后续安装包的速度。npm config set registry https://registry.npmmirror.com/4. EMQX MQTT Broker 部署与配置Node.js 环境就绪后我们需要部署 MQTT 消息服务器。EMQX 是一个开源的高性能 MQTT 5.0 Broker用 Erlang/OTP 语言编写非常适合物联网场景支持海量并发连接。幸运的是EMQX 官方为多种架构提供了预编译的安装包其中就包括arm64和riscv64。4.1 通过官方 Apt 源安装 EMQX这是最推荐的方式便于后续管理和升级。导入 EMQX Apt 仓库的 GPG 密钥并添加源# 安装必要的工具以处理 apt 仓库 sudo apt install -y gnupg curl # 添加 GPG 密钥 curl -s https://packages.emqx.io/gpg.pub | sudo apt-key add - # 添加 EMQX Apt 源 echo deb [archriscv64] https://packages.emqx.io/emqx-ce/deb/debian/ ./ | sudo tee /etc/apt/sources.list.d/emqx.list注意[archriscv64]这个部分它明确指定了这个源用于riscv64架构的包。这是成功的关键。更新本地包索引并安装 EMQXsudo apt update sudo apt install emqxapt update会从新添加的 EMQX 源拉取软件包信息。如果一切顺利apt install emqx就会下载并安装针对 RISC-V 64 架构编译好的 EMQX 软件包及其所有依赖。4.2 管理 EMQX 服务EMQX 安装后会作为一个系统服务systemd service运行。启动与启用开机自启sudo systemctl start emqx # 立即启动服务 sudo systemctl enable emqx # 设置开机自动启动检查服务状态sudo systemctl status emqx如果状态显示为active (running)则说明 EMQX 已成功启动。使用 EMQX CLI 工具验证 EMQX 提供了一个命令行工具来检查 Broker 状态。emqx ctl broker这个命令会输出 EMQX 的版本、运行时间、集群状态等概要信息。看到类似Node ‘emqx127.0.0.1’ started的输出就证明 Broker 核心运行正常。4.3 访问 Web 管理控制台并进行基础安全配置EMQX 默认开启了基于 Web 的管理控制台这对于监控和配置来说非常方便。确定访问地址首先获取芒果派的 IP 地址。ip addr show找到eth0有线网卡或wlan0无线网卡对应的inet地址。登录控制台在同一局域网内的电脑浏览器中输入http://你的芒果派IP:18083。例如http://192.168.50.60:18083。默认用户名admin默认密码public重要首次登录后务必立即修改默认密码在控制台的Management-Users页面可以修改 admin 用户的密码。基础配置检查监听端口在Management-Listeners页面确认默认的 MQTT TCP 监听器端口 1883和 WebSocket 监听器端口 8083是否处于运行状态。这是客户端连接所使用的端口。系统监控在Monitoring页面可以查看连接数、消息吞吐量、系统资源CPU、内存使用情况。对于内存只有 512MB 的 MQ Quad需要密切关注内存使用。注意事项防火墙如果无法从外部访问 18083管理台或 1883MQTT请检查芒果派系统的防火墙设置如ufw是否放行了这些端口。性能考量EMQX 默认配置是为服务器设计的。在资源受限的嵌入式设备上可能需要调整 Erlang VM 参数以限制内存使用。配置文件位于/etc/emqx/emqx.conf。一个简单的优化是减少最大连接数和会话数例如修改node.max_connections和zone.external.max_connections为一个较小的值如 1000。数据持久化默认配置下消息和会话数据存储在内存中。板子断电会丢失。如果需要对消息进行持久化需要配置 EMQX 使用外部数据库如 PostgreSQL或内置的 Mnesia 数据库持久化但这会显著增加存储 I/O 和内存开销需根据项目需求权衡。5. 环境整合验证与示例应用部署好 Node.js 和 EMQX 后我们需要验证它们是否能协同工作。一个经典的测试是编写一个简单的 Node.js 脚本使用 MQTT 客户端库连接到本地的 EMQX Broker进行消息的发布和订阅。5.1 创建测试项目并安装 MQTT 客户端库在家目录下创建一个测试目录并初始化一个 Node.js 项目。mkdir ~/mqtt-test cd ~/mqtt-test npm init -y安装一个流行的 MQTT 客户端库例如mqtt。npm install mqtt5.2 编写测试脚本创建一个名为test.js的文件内容如下const mqtt require(mqtt); // 连接到本地 EMQX Broker默认端口 1883 const client mqtt.connect(mqtt://localhost:1883); client.on(connect, function () { console.log(✅ 已连接到 MQTT Broker); // 订阅一个测试主题 client.subscribe(mangopi/test, function (err) { if (!err) { console.log( 已订阅主题: mangopi/test); // 订阅成功后向该主题发布一条消息 client.publish(mangopi/test, Hello from MangoPi MQ Quad!); } }); }); // 接收消息的回调 client.on(message, function (topic, message) { // message 是 Buffer需要转成字符串 console.log( 收到消息 [${topic}]: ${message.toString()}); // 收到消息后断开连接仅用于测试 client.end(); }); client.on(error, function (error) { console.error(❌ 连接错误:, error); });这个脚本做了三件事连接到本机 EMQX。连接成功后订阅主题mangopi/test。订阅成功后立即向同一个主题发布一条消息。当收到自己发布的消息时打印出来并断开连接。5.3 运行测试并观察结果在终端运行脚本node test.js预期输出✅ 已连接到 MQTT Broker 已订阅主题: mangopi/test 收到消息 [mangopi/test]: Hello from MangoPi MQ Quad!如果看到以上输出恭喜你这证明Node.js 环境工作正常可以执行 JavaScript 代码并加载第三方模块。EMQX Broker 工作正常成功接受了 TCP 连接、处理了订阅和发布请求。整个消息通路发布 - Broker - 订阅是畅通的。你还可以打开 EMQX 的 Web 控制台在Monitoring-Clients和Monitoring-Topics页面实时看到这个测试客户端的连接和消息流转情况。6. 常见问题排查与性能优化实录在实际部署和运行中你可能会遇到以下问题。这里记录了我遇到的情况和解决方法。6.1 NVM 及 Node.js 相关问题问题1nvm install -s编译失败提示g: internal compiler error: Killed (program cc1plus)原因这通常是编译过程中内存耗尽系统杀掉了编译进程。RISC-V 架构编译 Node.js 非常消耗内存。解决增加交换空间如前文所述创建并启用一个足够大的交换文件如 2GB。并行编译限制通过环境变量限制make使用的 job 数量减少瞬时内存压力。在运行nvm install前执行export MAKE_JOBS1 nvm install -s 18.19.0使用更轻量的版本尝试安装稍旧一点的 LTS 版本如 Node.js 16.x其源码可能对内存需求略低。问题2使用npm install安装某些原生模块如sqlite3,bcrypt失败原因这些模块包含需要针对本机架构编译的 C 代码。编译它们同样需要开发工具和库且可能依赖特定版本的 Node.js 头文件。解决确保已安装build-essential,python3,make,g。尝试使用npm config set跳过可选依赖或指定 Python 路径。最根本的优先寻找纯 JavaScript 实现的替代包例如用better-sqlite3替代sqlite3用bcryptjs替代bcrypt它们无需编译在异构架构上兼容性极佳。6.2 EMQX 相关问题问题3无法通过浏览器访问http://ip:18083排查步骤确认服务运行sudo systemctl status emqx查看状态。确认监听端口sudo netstat -tlnp | grep 18083。如果看不到监听可能是 EMQX 启动失败查看日志sudo journalctl -u emqx -f。检查防火墙Debian 可能默认安装了ufw。运行sudo ufw status。如果状态是active需要放行端口sudo ufw allow 18083/tcp和sudo ufw allow 1883/tcp。检查网络确保你的电脑和芒果派在同一个局域网子网内。问题4EMQX 运行一段时间后板子内存占用过高响应变慢分析与优化监控通过 Web 控制台或emqx ctl broker命令查看当前连接数和会话数。嵌入式场景下连接数应控制在数百以内。调整配置编辑/etc/emqx/emqx.conf限制最大连接数node.max_connections 1000根据实际情况调小减少会话过期时间session.max_lifetime 2h默认是永不过期关闭非必需功能如将log.level从info改为warning减少日志量评估是否需要开启规则引擎 (rule_engine) 或数据桥接 (bridges)如果不用可以关闭相关配置。重启服务修改配置后运行sudo systemctl restart emqx生效。问题5Node.js 应用作为 MQTT 客户端频繁断线重连可能原因网络不稳定。客户端代码没有正确处理keepalive和重连逻辑。EMQX 侧配置的keepalive时间太短。解决在客户端代码中实现稳健的重连机制监听close和error事件。适当增加客户端的keepalive间隔例如 60 秒和 EMQX 的zone.external.keepalive配置。检查是否有其他进程占用了大量 CPU导致客户端心跳响应不及时。6.3 系统层面优化建议对于芒果派 MQ Quad 这类资源有限的设备一些系统级的优化能提升整体稳定性禁用不必要的系统服务使用sudo systemctl list-unit-files --typeservice查看禁用如bluetooth,avahi-daemon等可能用不到的服务。使用轻量级进程监控考虑用htop替代top或者使用glances进行更全面的监控。日志管理定期清理/var/log目录下的旧日志防止占满存储。可以配置logrotate或使用journalctl的清理命令。整个部署过程最耗时的部分就是在 RISC-V 上编译 Node.js这需要极大的耐心。一旦基础环境搭建完成后续的应用开发和部署就会顺畅很多。这套组合Node.js EMQX为在芒果派这类边缘设备上构建实时、双向通信的物联网应用提供了一个非常坚实且灵活的基础。