1. 项目概述与核心价值最近在捣鼓一块叫芒果派MangoPi MQ Quad的开发板这玩意儿基于全志D1s芯片RISC-V架构价格亲民功耗极低拿来跑一些轻量级的物联网服务或者边缘计算节点再合适不过了。拿到手之后我琢磨着得给它装点“灵魂”让它能干点实事。对于物联网场景Node.js的异步高并发特性和EMQX这款强大的MQTT消息服务器简直是绝配。前者能轻松处理大量设备连接和业务逻辑后者则负责设备间稳定、高效的通信。所以这次的目标很明确在这块小小的RISC-V板子上从零开始搭建一个稳定可用的Node.js运行环境和EMQX消息中间件环境。这个过程听起来简单但实际操作起来尤其是在RISC-V这种相对小众的架构上会遇到不少在x86或ARM上遇不到的“坑”。比如官方的Node.js二进制包可能不提供RISC-V版本EMQX的官方安装脚本也可能对架构支持不完善。这篇文章我就把我从系统准备、依赖安装、源码编译、配置优化到最终验证的完整过程以及中间踩过的所有坑和解决方案详细记录下来。无论你是物联网开发者、嵌入式爱好者还是单纯想体验在RISC-V上部署服务的乐趣这份“避坑指南”都能帮你节省大量摸索时间。2. 硬件准备与系统环境搭建2.1 芒果派MangoPi MQ Quad硬件初识芒果派MangoPi MQ Quad是一款非常小巧的RISC-V单板计算机。其核心是全志的D1s SoC集成了一个平头哥玄铁C906 RISC-V CPU核心主频最高1GHz配备了64MB的DDR2内存。接口方面它有一个USB Type-C口用于供电和调试一个MicroSD卡槽用于存储系统以及一些GPIO引脚可供扩展。其超低的功耗通常低于1W和极小的体积使其非常适合作为物联网网关、数据采集节点或轻量级服务器。在开始软件部署前我们需要为它准备一个操作系统。官方推荐使用Tina Linux这是全志基于OpenWrt定制的嵌入式Linux系统。我们需要从芒果派的官方Wiki或社区获取最新的Tina Linux系统镜像。注意务必确认下载的镜像版本与你的硬件版本匹配。不同批次的板子在设备树或驱动上可能有细微差别。2.2 系统烧录与基础配置将下载的.img格式的系统镜像使用工具如balenaEtcher或Raspberry Pi Imager烧录到一张至少8GB的MicroSD卡中。完成后将SD卡插入芒果派连接USB Type-C电源启动。首次启动后我们需要通过网络连接到板子。最方便的方式是使用串口调试。你需要一个USB转TTL串口模块将其RX、TX、GND分别连接到芒果派的UART0引脚通常是PA2/TX, PA3/RX。在电脑上使用串口终端工具如PuTTY、MobaXterm或screen命令连接波特率设置为115200。登录系统后默认用户名root可能无密码第一件事是配置网络。如果板子有有线网口直接插上网线系统通常会通过DHCP自动获取IP。如果没有你可能需要配置Wi-Fi。Tina Linux通常使用wifimanager或直接修改/etc/config/wireless文件来配置Wi-Fi。# 查看网络接口 ifconfig # 如果使用wifi可以尝试扫描具体命令可能因系统版本而异 wifi scan wifi connect -s Your_SSID -p Your_Password配置好网络后建议更新软件源并安装一些基础工具为后续编译做准备。# 更新opkg软件列表 opkg update # 安装常用工具 opkg install vim git wget curl ca-certificates3. Node.js环境部署从源码编译到优化3.1 编译环境与依赖准备在RISC-V架构上我们很难直接找到预编译的Node.js二进制包因此从源码编译是唯一可靠的选择。编译Node.js需要比较多的依赖和足够的内存。芒果派MQ Quad的64MB内存是最大的挑战直接在板子上编译几乎肯定会因内存不足而失败。因此我们需要采用交叉编译的方式。交叉编译是指在性能强大的宿主机比如你的x86_64电脑上为目标平台这里是RISC-V生成可执行程序。我们需要在宿主机上搭建RISC-V的交叉编译工具链。方案选择使用Docker简化交叉编译环境手动配置交叉编译工具链比较繁琐我推荐使用Docker。有一个非常优秀的项目叫dockcross它提供了大量预配置好的交叉编译环境镜像。# 在宿主机你的电脑上操作 # 拉取针对linux riscv64的交叉编译镜像 docker pull dockcross/linux-riscv64 # 运行一个交互式容器并将当前目录挂载到容器内的/work目录 docker run --rm -it -v $(pwd):/work dockcross/linux-riscv64 bash进入容器后你会发现环境已经配置好了CC,CXX,AR等工具都指向了RISC-V的交叉编译版本。编译的输出文件可以直接在芒果派上运行。接下来我们需要获取Node.js源码。建议选择一个稳定的LTS版本比如18.x或20.x兼容性和社区支持更好。# 在容器的/work目录下操作 wget https://nodejs.org/dist/v20.15.0/node-v20.15.0.tar.gz tar -xzf node-v20.15.0.tar.gz cd node-v20.15.03.2 配置与编译参数详解Node.js的编译配置通过configure脚本完成。针对嵌入式环境我们需要关闭一些非必需的功能来减小二进制体积和依赖。# 关键配置参数解析 ./configure \ --prefix/usr/local/node \ # 指定安装路径 --cross-compiling \ # 声明交叉编译 --dest-cpuriscv64 \ # 目标CPU架构 --dest-oslinux \ # 目标操作系统 --with-mips-float-abisoft \ # RISC-V通常使用soft-float但需根据工具链调整 --without-npm \ # 暂时不编译npm可单独安装更小版本 --without-intl \ # 移除国际化支持减小体积 ---without-inspector \ # 移除V8调试器支持 --shared-openssl \ # 使用系统共享的OpenSSL库需目标系统存在 --shared-zlib \ # 使用系统共享的zlib库 --shared-cares \ # 使用系统共享的c-ares库 --shared-libuv \ # 使用系统共享的libuv库实操心得--without-npm是一个重要的减负选项。Node.js自带的npm包管理器很大我们可以后续安装一个精简版的pnpm或yarn或者直接从宿主机拷贝一个小版本的npm。另外--shared-*选项可以显著减少最终二进制文件的大小但前提是目标板子上已经安装了这些库的开发版.so文件。如果板子上没有编译时会链接失败此时需要去掉这些选项改为静态编译会增加体积。配置完成后开始编译。这个过程在性能不错的宿主机上可能需要10-30分钟。make -j$(nproc) # 使用所有CPU核心并行编译编译成功后在out/Release/目录下会生成node可执行文件。我们还需要将其和必要的库文件打包。3.3 部署到芒果派与验证编译产物不能直接在宿主机运行。我们需要将其拷贝到芒果派上。# 在宿主机上退出docker容器后操作 # 假设编译产物在 ./node-v20.15.0/out/Release/node # 创建一个部署目录 mkdir -p mango-pi-nodejs cp node-v20.15.0/out/Release/node mango-pi-nodejs/ # 使用交叉编译工具链中的 ldd 查看依赖在dockcross容器内进行 # 首先找到容器内交叉编译工具链的 ldd # 通常路径类似 /usr/bin/riscv64-linux-gnu-ldd docker run --rm -v $(pwd):/work dockcross/linux-riscv64 bash -c /usr/bin/riscv64-linux-gnu-ldd /work/node-v20.15.0/out/Release/nodeldd命令会列出node二进制文件依赖的所有动态库。你需要将这些库文件从交叉编译工具链的sysroot中或者确保它们在芒果派的/lib目录下存在。最简单的方法是将缺失的.so文件拷贝到部署目录并设置运行时的库路径。将整个mango-pi-nodejs目录通过scp或SD卡拷贝到芒果派的/opt目录下。# 在芒果派上操作 cd /opt/mango-pi-nodejs # 为node二进制文件添加可执行权限 chmod x node # 创建软链接到全局可访问路径 ln -sf /opt/mango-pi-nodejs/node /usr/local/bin/node # 临时设置库路径并测试 LD_LIBRARY_PATH/opt/mango-pi-nodejs/lib:$LD_LIBRARY_PATH ./node -v如果成功输出版本号如v20.15.0恭喜你Node.js环境部署成功为了永久生效可以将库路径添加到系统环境变量。echo export PATH/opt/mango-pi-nodejs:$PATH /etc/profile echo export LD_LIBRARY_PATH/opt/mango-pi-nodejs/lib:$LD_LIBRARY_PATH /etc/profile source /etc/profile4. EMQX消息服务器部署适配RISC-V架构4.1 EMQX部署方案评估EMQX是一款高性能的分布式MQTT消息服务器。官方提供了多种安装方式二进制包、Docker容器、源码编译。对于RISC-V架构官方通常不提供预编译的二进制包Docker镜像也可能缺少RISC-V版本。因此源码编译再次成为最可行的路径。EMQX基于Erlang/OTP语言平台这意味着我们需要先在芒果派上搭建Erlang运行环境然后再编译EMQX。这比Node.js的交叉编译更复杂因为Erlang虚拟机BEAM对架构和系统依赖更敏感。一个更可行的方案是在同类架构但性能更强的设备如VisionFive 2等拥有更大内存的RISC-V开发板或服务器上完成编译然后将整个打包好的运行时环境迁移到芒果派上。考虑到芒果派资源有限64MB内存我们也不应该部署完整的EMQX企业版而是选择更轻量级的EMQX开源版并且需要针对嵌入式环境进行配置优化。4.2 Erlang/OTP环境搭建EMQX 5.x需要Erlang/OTP 24或25版本。我们需要在RISC-V环境可以是另一台资源更丰富的RISC-V设备或者使用QEMU用户态模拟下编译Erlang。步骤一获取Erlang源码在目标编译机器上假设是一台内存大于1GB的RISC-V设备进行操作。# 安装编译依赖 opkg update opkg install git gcc g make libncurses-dev libssl-dev libsctp-dev linux-headers # 下载Erlang/OTP 25源码 git clone -b maint-25 https://github.com/erlang/otp.git cd otp步骤二配置与编译ErlangErlang的configure脚本提供了许多配置项嵌入式环境需要精简。./otp_build autoconf ./configure \ --prefix/usr/local/erlang-25 \ # 指定安装路径 --without-javac \ # 移除Java接口 --without-wx \ # 移除wxWidgets GUI支持 --without-debugger \ # 移除调试器 --without-megaco \ # 移除Megaco协议支持 --without-odbc \ # 移除ODBC支持 --enable-builtin-zlib \ # 使用内置zlib --disable-hipe \ # 禁用HIPE本地代码编译器减少复杂度 --disable-sctp # 禁用SCTP协议支持 make -j$(nproc) make install编译过程非常耗时在RISC-V设备上可能需要数小时。编译完成后将/usr/local/erlang-25整个目录打包。4.3 EMQX源码编译与精简在同样的RISC-V编译环境中设置好Erlang环境变量然后编译EMQX。# 设置Erlang环境变量 export PATH/usr/local/erlang-25/bin:$PATH export ERL_HOME/usr/local/erlang-25 # 下载EMQX开源版源码以5.4.x为例 git clone -b v5.4.3 https://github.com/emqx/emqx.git cd emqx # EMQX使用rebar3进行构建。首次运行会下载依赖请确保网络通畅。 makemake命令会完成所有编译和打包工作最终在_build/emqx/rel/emqx目录下生成一个独立的发布包。这个包包含了Erlang运行时、EMQX所有核心和插件是自包含的。嵌入式环境精简策略删除不必要的插件进入_build/emqx/rel/emqx/lib目录删除如emqx_enterprise*企业版插件、emqx_bridge_mqtt如果你不用桥接、emqx_rule_engine如果规则简单等插件目录。务必谨慎可以先备份。调整配置文件修改_build/emqx/rel/emqx/etc/emqx.conf降低资源消耗。# 限制并发连接数默认是100万对于嵌入式设备不现实 node.max_connections 1000 # 调整Erlang虚拟机进程和端口数量限制 node.process_limit 1024 node.max_ports 1024 # 关闭集群发现单节点部署 cluster.discovery static # 减少日志级别和输出 log.level warning log.file_handlers.default.level warning4.4 部署到芒果派并启动将精简后的整个emqx发布包即_build/emqx/rel/emqx目录拷贝到芒果派的/opt目录下。# 在芒果派上操作 cd /opt/emqx # 启动EMQX前台运行方便查看日志 ./bin/emqx start # 查看运行状态 ./bin/emqx_ctl status如果状态显示running说明EMQX启动成功。默认的MQTT TCP监听端口是1883Web管理界面端口是18083如果安装了emqx_dashboard插件。你可以使用ifconfig查看芒果派的IP地址然后在同一局域网内的电脑上使用MQTT客户端如MQTTX连接mqtt://芒果派IP:1883进行测试。重要注意事项芒果派64MB内存非常紧张。EMQX启动后使用free -m命令查看内存使用。如果内存占用过高90%可能会导致系统不稳定甚至EMQX进程被OOM Killer终止。此时需要进一步精简EMQX或者考虑使用更轻量的MQTT Broker如 Mosquitto 它的资源消耗要小得多。5. 环境集成与基础应用测试5.1 编写一个简单的Node.js MQTT客户端环境部署好了我们来写一个简单的测试脚本用Node.js连接本地的EMQX实现消息的发布和订阅。首先在芒果派上为Node.js安装MQTT客户端库。由于我们编译时没有npm需要手动安装一个轻量级包管理器或直接下载库文件。这里我们使用npm的替代品pnpm的独立脚本安装方式或者直接从其他机器拷贝已安装的node_modules。这里我们采用一个更直接的方法使用npm的离线安装模式在宿主机安装好再拷贝过来。在宿主机x86电脑上准备模块mkdir mqtt-test cd mqtt-test echo { name: mqtt-test, type: module } package.json # 安装mqtt库注意选择兼容你Node.js版本的版本 npm install mqtt5这会在当前目录生成node_modules文件夹。编写测试脚本test_mqtt.mjs(使用ES Module)import mqtt from mqtt const clientId mqtt_${Math.random().toString(16).slice(3)} const connectUrl mqtt://localhost:1883 const client mqtt.connect(connectUrl, { clientId, clean: true, connectTimeout: 4000, reconnectPeriod: 1000, }) client.on(connect, () { console.log(Connected to EMQX!) // 订阅一个主题 client.subscribe(mango-pi/test, (err) { if (!err) { console.log(Subscribed to topic: mango-pi/test) // 发布一条消息 client.publish(mango-pi/test, Hello from MangoPi Node.js!) } }) }) client.on(message, (topic, message) { console.log(Received message on [${topic}]: ${message.toString()}) // 收到消息后断开连接 client.end() }) client.on(error, (err) { console.error(Connection error: , err) client.end() })将整个mqtt-test目录拷贝到芒果派例如放到/root下。在芒果派上运行测试cd /root/mqtt-test # 设置NODE_PATH让Node.js能找到模块 export NODE_PATH/root/mqtt-test/node_modules node test_mqtt.mjs如果看到“Connected to EMQX!”和“Received message...”的输出说明Node.js和EMQX协同工作正常。5.2 系统服务化与开机自启为了让Node.js应用和EMQX在板子启动时自动运行我们需要将其配置为系统服务。配置EMQX为系统服务EMQX的发布包中已经提供了systemd服务文件模板。我们可以稍作修改后使用。# 拷贝服务文件到系统目录 cp /opt/emqx/bin/emqx.service /etc/systemd/system/ # 编辑服务文件确保ExecStart路径正确 vim /etc/systemd/system/emqx.service # 主要检查这一行 # ExecStart/opt/emqx/bin/emqx start # 如果你的路径不同请修改。 # 重新加载systemd配置 systemctl daemon-reload # 启用并启动服务 systemctl enable emqx systemctl start emqx # 查看服务状态 systemctl status emqx配置Node.js应用为系统服务为我们的测试应用创建一个简单的服务文件。cat /etc/systemd/system/mqtt-test.service EOF [Unit] DescriptionSimple MQTT Test Service Afternetwork.target emqx.service [Service] Typesimple Userroot WorkingDirectory/root/mqtt-test EnvironmentNODE_PATH/root/mqtt-test/node_modules ExecStart/usr/local/bin/node /root/mqtt-test/test_mqtt.mjs Restarton-failure RestartSec10 [Install] WantedBymulti-user.target EOF systemctl daemon-reload systemctl enable mqtt-test systemctl start mqtt-test6. 性能调优、问题排查与资源监控6.1 针对低内存设备的优化策略芒果派MQ Quad的64MB内存是最大的限制。在同时运行Node.js和EMQX时必须进行严格的内存控制。EMQX优化连接数限制在emqx.conf中将node.max_connections设置为一个保守的值如50或100。会话与消息限制减少会话过期时间、关闭持久化会话、限制消息队列长度。# 会话过期时间秒 session.expiry_interval 300 # 最大消息队列长度 mqtt.max_mqueue_len 10关闭非核心功能确保不需要的插件如数据库桥接、规则引擎已彻底移除。Node.js优化调整V8内存参数通过NODE_OPTIONS环境变量限制Node.js的内存使用。export NODE_OPTIONS--max-old-space-size20这将堆内存限制在20MB以内。避免内存泄漏在代码中注意及时清除定时器、解绑事件监听器、避免全局变量缓存大量数据。系统级优化使用交换分区Swap在SD卡上创建一个交换文件作为内存的延伸。注意这会增加SD卡磨损。# 创建256MB的交换文件 dd if/dev/zero of/swapfile bs1M count256 mkswap /swapfile swapon /swapfile # 为了开机生效将以下行添加到 /etc/fstab # /swapfile swap swap defaults 0 0调整内核内存管理参数通过sysctl调整vm.swappiness降低到10-20减少换出和vm.vfs_cache_pressure增加到100以上让内核更快回收目录项和inode缓存。6.2 常见问题与排查实录问题一编译Node.js时出现Illegal instruction错误。原因这通常是因为编译时指定的CPU架构特性如扩展指令集与目标板子的实际CPU不支持。全志D1s的C906核心可能不支持某些高级RISC-V扩展。解决在configure时明确指定更保守的架构和ABI。尝试移除--with-mips-float-abi这个参数是给MIPS的对于RISC-V重点是通过CFLAGS和CXXFLAGS环境变量传递-marchrv64gc -mabilp64d如果支持或更基础的-marchrv64imafdc -mabilp64d。最稳妥的方法是使用板子原系统提供的gcc默认配置。问题二EMQX启动失败日志显示erl: not found。原因系统找不到Erlang可执行文件。虽然你将Erlang打包了过来但可能没有正确设置PATH环境变量或者服务文件中的路径不对。解决检查/usr/local/erlang-25/bin是否在PATH中echo $PATH。检查EMQX启动脚本/opt/emqx/bin/emqx中是否硬编码了Erlang路径。通常脚本会使用#!/usr/bin/env bash和erts_dir变量来定位。你需要确保这个变量指向你Erlang的安装路径或者修改脚本开头的环境变量设置。问题三Node.js应用运行一段时间后进程消失。原因极有可能是被Linux内核的OOM Killer内存溢出杀手终止了。排查# 查看系统日志寻找OOM相关记录 dmesg | grep -i killed process # 或 cat /var/log/messages | grep -i oom解决按照6.1节的优化策略大幅降低内存使用。优先考虑减少EMQX的连接数和Node.js的内存上限。监控内存使用情况# 动态查看内存和交换分区使用 watch -n 2 free -m # 查看具体进程内存占用 top -o %MEM问题四MQTT客户端无法连接到EMQX。排查步骤检查EMQX是否运行systemctl status emqx。检查端口监听netstat -tlnp | grep 1883。确认EMQX正在监听0.0.0.0:1883或:::1883。检查防火墙Tina Linux可能默认有防火墙规则。检查iptables -L或fw3命令。检查客户端连接地址确保Node.js脚本中的connectUrl是mqtt://localhost:1883本地或正确的芒果派IP地址远程。6.3 简易资源监控脚本为了长期运行可以写一个简单的Shell脚本监控服务状态和资源。#!/bin/bash # monitor.sh - 简易服务监控 LOG_FILE/var/log/service_monitor.log # 检查EMQX if ! systemctl is-active --quiet emqx; then echo $(date): EMQX is down, attempting restart... $LOG_FILE systemctl restart emqx fi # 检查Node.js测试服务如果设置了 if systemctl list-unit-files | grep -q mqtt-test.service; then if ! systemctl is-active --quiet mqtt-test.service; then echo $(date): MQTT Test Service is down, restarting... $LOG_FILE systemctl restart mqtt-test.service fi fi # 记录内存使用可选 MEM_USED$(free -m | awk NR2{print $3}) MEM_TOTAL$(free -m | awk NR2{print $2}) if [ $MEM_USED -gt $((MEM_TOTAL * 80 / 100)) ]; then echo $(date): WARNING: Memory usage high: ${MEM_USED}M/${MEM_TOTAL}M $LOG_FILE fi将脚本加入cron定时任务每5分钟执行一次crontab -e # 添加一行 */5 * * * * /bin/bash /path/to/monitor.sh经过以上步骤你应该已经在芒果派MangoPi MQ Quad这块小巧的RISC-V板子上成功部署了Node.js运行环境和EMQX消息服务器并让它们协同工作。这个过程充满了挑战尤其是内存限制和架构适配但最终的成功运行证明了在资源受限的边缘设备上运行现代消息中间件和应用栈是完全可行的。这套环境可以作为物联网项目的一个坚实起点后续你可以在此基础上开发更复杂的设备接入、数据处理和云端同步逻辑。