1. 项目缘起为什么要在树莓派上搭建这个环境最近几年我手头的树莓派设备越来越多从早期的3B到现在的5代它们已经从单纯的“玩具”变成了我日常开发、学习和部署小型服务的主力军。很多朋友问我为什么不用云服务器或者本地虚拟机非要折腾这个小板子我的回答很简单成本、能耗和场景。一台树莓派5加上电源、存储卡和外壳总成本可能还不到一台入门级云服务器一年的费用。更重要的是它功耗极低可以7x24小时开机放在家里或办公室角落几乎感觉不到它的存在。对于个人项目、IoT原型、家庭自动化中枢或者作为学习Linux、网络和服务器技术的沙盒树莓派是绝佳的选择。而Node.js MongoDB的组合是我个人非常偏爱的技术栈。Node.js的异步非阻塞特性非常适合处理高并发的I/O密集型任务比如API网关、实时聊天、数据采集代理等。MongoDB的文档模型则非常灵活对于快速迭代的原型项目或者数据结构经常变化的场景比如物联网传感器数据它比传统的关系型数据库要友好得多。把这两者部署到树莓派上就意味着你拥有了一个低成本、低功耗、可随时访问的微型全栈服务器。你可以用它来跑自己的博客后台、家庭媒体服务器的元数据管理、智能家居的控制中枢或者作为学习后端开发的实验平台。这个系列的第一篇我们就从最基础的“从零开始”讲起。很多教程会假设你已经有了一个可用的Linux系统但根据我的经验恰恰是“安装系统”和“基础环境配置”这两个环节新手最容易踩坑。网上的教程要么太老要么步骤跳跃要么忽略了树莓派这种ARM架构设备的特殊性。所以我会结合最新的树莓派5和Raspberry Pi OS基于Debian把每一步都掰开揉碎不仅告诉你“怎么做”更会解释“为什么这么做”以及我踩过的那些坑。2. 系统安装不止是“烧录镜像”那么简单拿到一块崭新的树莓派第一步就是给它安装操作系统。这听起来很简单但细节决定成败。一个稳定、源配置正确的系统是后续所有工作的基石。2.1 操作系统选择与镜像下载对于树莓派官方推荐的系统是Raspberry Pi OS。它基于Debian针对树莓派的硬件进行了深度优化驱动完善社区支持最好。对于我们的Node.js和MongoDB环境它是最稳妥的选择。注意虽然Ubuntu Server for Raspberry Pi也是一个流行的选择但对于新手和追求稳定性的场景我强烈建议从Raspberry Pi OS开始。Ubuntu的包管理、内核更新策略与官方系统略有不同可能会在驱动兼容性或软件包版本上带来不必要的麻烦。访问 Raspberry Pi 官网的下载页面你会看到几个版本Raspberry Pi OS (Legacy, 32-bit)基于Debian 10 (Buster)的旧版系统不推荐新项目使用。Raspberry Pi OS (64-bit)这是我们本次教程的选择。它基于Debian 12 (Bookworm)提供64位支持能更好地利用树莓派4/5的内存尤其是4GB及以上版本并且软件仓库更新。Raspberry Pi OS Lite (64-bit)没有图形桌面的纯命令行版本。如果你打算将树莓派作为无头服务器Headless Server即没有显示器、键盘鼠标仅通过SSH管理这个版本更轻量资源占用更少。本篇教程以Lite版本为例因为服务器环境通常不需要桌面。下载完成后你会得到一个.img.xz的压缩镜像文件。2.2 使用 Raspberry Pi Imager 进行烧录这是官方提供的工具也是目前最傻瓜化、功能最全的烧录方式。它支持Windows、macOS和Linux。下载并安装 Raspberry Pi Imager。将一张至少16GB的MicroSD卡通过读卡器插入电脑。打开Imager点击“选择操作系统”。如果你下载了镜像文件选择“使用自定义镜像”然后找到你下载的.img.xz文件。也可以直接在这里选择“Raspberry Pi OS (64-bit)”或“Raspberry Pi OS Lite (64-bit)”工具会自动下载。点击“选择存储设备”选中你的MicroSD卡。关键步骤点击右下角的齿轮图标高级选项。这里可以预先进行一些极其重要的配置实现“开箱即用”设置主机名例如raspberrypi-node方便在网络中识别。启用SSH勾选“启用SSH”。为了安全建议选择“使用密码认证”并设置一个强密码。如果你有公钥也可以选择“使用公钥认证”这是更安全的方式。配置Wi-Fi填写你的Wi-Fi SSID和密码。这样树莓派启动后就能自动连接网络无需接网线。设置地区选项正确设置时区如Asia/Shanghai和键盘布局。这一步很多人会忽略导致系统时间不对影响证书验证、日志记录等一系列操作。设置用户名和密码默认用户是pi密码是raspberry。出于安全考虑强烈建议在这里修改默认密码或者使用一个不同的用户名。点击“保存”然后点击“烧录”。等待进度条完成。使用Imager的高级选项进行预配置能省去第一次启动后接显示器、键盘进行初始设置的麻烦直接实现无头启动和远程SSH连接这是我认为目前最优雅的树莓派初始化方式。2.3 首次启动与基础配置烧录完成后将MicroSD卡插入树莓派上电启动。等待几分钟首次启动会进行文件系统扩展等操作你就可以尝试通过SSH连接了。在局域网内另一台电脑上打开终端Windows可使用PowerShell或CMD但推荐安装OpenSSH客户端macOS和Linux直接使用终端。ssh 你的用户名树莓派的主机名.local # 例如ssh piraspberrypi-node.local如果.local域名解析失败在某些网络环境下可能发生你需要先找到树莓派的IP地址。可以通过路由器管理界面查看或者使用网络扫描工具。然后用IP地址连接ssh 你的用户名树莓派的IP地址首次连接会提示主机密钥认证输入yes然后输入你设置的密码即可登录。登录后第一件事是更新系统软件包列表并升级现有软件。这是保持系统安全稳定的好习惯。sudo apt update sudo apt upgrade -yupgrade过程可能会比较长取决于网络速度和需要更新的包数量。完成后建议重启一次sudo reboot。3. Node.js环境部署避开版本管理的坑在树莓派上安装Node.js最常见的有三种方法通过系统包管理器apt、使用Node版本管理工具nvm、或从NodeSource仓库安装。每种方法各有优劣我详细分析一下。3.1 安装方案对比与选型apt安装最简单但不推荐用于开发命令sudo apt install nodejs npm优点极其简单一键安装。缺点Raspberry Pi OS仓库中的Node.js版本通常非常老旧。例如在Bookworm中可能还是v18.x甚至更早的版本。对于需要特定新版本如最新的LTS或Current版本的项目这无法满足需求。而且apt安装的Node.js全局模块路径需要sudo权限容易引发权限问题。NodeSource 仓库安装折中方案先添加NodeSource的APT仓库然后通过apt安装。优点可以安装较新的、特定的Node.js LTS版本由NodeSource团队维护相对可靠。缺点版本切换不灵活需要手动修改仓库源。在ARM架构树莓派上NodeSource提供的二进制包是跨平台兼容的但并非针对树莓派优化。nvm(Node Version Manager) 安装强烈推荐nvm是一个bash脚本允许你在用户目录下安装和管理多个独立的Node.js版本。优点版本切换灵活可以随时安装、切换、使用不同版本的Node.js非常适合同时维护多个项目。无需sudo所有文件都安装在你的家目录下通常是~/.nvm彻底避免了全局权限问题。安装最新版本可以轻松安装Node.js官网发布的最新LTS或Current版本。缺点需要多一步安装nvm本身的步骤。我的选择与理由对于个人开发和学习环境我毫无保留地推荐使用nvm。它完美解决了版本管理和权限问题。虽然多了一个工具但带来的便利性是巨大的。下面的步骤将基于nvm进行。3.2 使用 nvm 安装与管理 Node.js首先我们需要安装nvm。访问nvm的GitHub仓库查看最新的安装命令。通常是通过curl或wget下载安装脚本。# 使用官方安装脚本注意检查命令是否为最新 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # 或者使用 wget # wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash安装脚本会将nvm克隆到~/.nvm目录并尝试在你的 shell 配置文件如~/.bashrc,~/.zshrc中添加初始化代码。关键一步安装完成后关闭当前终端重新打开一个新的终端窗口或者执行source ~/.bashrc如果你用的是bash。这是为了让nvm命令生效。验证nvm是否安装成功nvm --version现在我们可以用nvm安装Node.js了。首先查看有哪些版本可以安装nvm ls-remote这个列表会很长我们通常关注LTS长期支持版本。可以过滤一下nvm ls-remote --lts假设我们想安装最新的LTS版本例如 v20.xnvm install --lts或者安装一个特定版本nvm install 20.11.1安装完成后将其设置为默认版本nvm alias default 20.11.1这样每次新开终端都会自动使用这个版本。验证Node.js和npm是否安装成功node -v npm -v3.3 配置npm与全局模块安装使用nvm安装的Node.js其全局模块路径在~/.nvm/versions/node/version/lib/node_modules用户有读写权限因此安装全局包不再需要sudo。但是默认的npm源registry在国外速度可能很慢。我们可以将其切换到国内的镜像源如淘宝NPM镜像。npm config set registry https://registry.npmmirror.com/验证配置npm config get registry现在你可以像往常一样安装全局工具了例如nodemon一个监控文件变化自动重启Node应用的开发工具npm install -g nodemon安装后你可以通过which nodemon来查看它的安装路径确认是在nvm管理的目录下。4. MongoDB数据库安装ARM架构下的特殊处理在树莓派上安装MongoDB是整个过程里最具挑战性的一环。因为MongoDB官方从4.x版本后期开始停止为ARMv732位架构提供预编译的社区版二进制包。树莓派4之前的型号大多是ARMv7。而树莓派4/5虽然是ARMv864位架构但MongoDB官方也没有为ARM64提供.deb或.rpm安装包。这意味着我们不能简单地通过apt install mongodb来安装。我们需要另辟蹊径。主要有三种方法使用Ubuntu/Debian仓库的mongodb包这个包通常版本极旧可能是2.x或3.x且已停止维护绝对不要用。使用MongoDB提供的tgz压缩包手动安装这是官方支持的方式也是我们接下来要采用的方法。它需要一些手动配置。使用Docker运行MongoDB这是一个非常优雅的解决方案可以避免环境污染和复杂的依赖问题。考虑到篇幅我们将在本系列后续文章中详细介绍Docker方案。这里我们重点讲解第二种方法手动安装MongoDB社区版。4.1 下载适用于ARM64的MongoDB压缩包前往MongoDB官网的下载中心选择“Community Server”。在版本下拉框中选择最新的稳定版如7.0。在“Platform”选择中关键就在这里你需要选择“Ubuntu 22.04 ARM64”或者“Debian 11 ARM64”。虽然我们的系统是Raspberry Pi OS (Bookworm)但其底层是Debian 12与Debian 11/Ubuntu 22.04在库依赖上足够接近MongoDB的二进制包通常可以运行。选择“Package”为tgz然后点击下载。你会得到一个类似mongodb-linux-aarch64-debian11-7.0.11.tgz的文件。在树莓派上我们可以直接用wget下载。首先找到下载链接在官网点击下载时右键复制链接地址。# 进入用户主目录创建一个临时下载目录 cd ~ mkdir temp-mongodb cd temp-mongodb # 使用 wget 下载链接地址需要替换成你从官网复制的实际地址 wget https://fastdl.mongodb.org/linux/mongodb-linux-aarch64-debian11-7.0.11.tgz4.2 解压、安装与目录规划下载完成后解压文件tar -zxvf mongodb-linux-aarch64-*.tgz解压后会得到一个mongodb-linux-aarch64-debian11-7.0.11这样的目录。我们需要将其移动到系统合适的目录。通常第三方手动安装的软件可以放在/opt或/usr/local下。我习惯放在/opt。# 将解压后的目录移动到 /opt并重命名为一个简单的名字 sudo mv mongodb-linux-aarch64-debian11-7.0.11 /opt/mongodb现在MongoDB的可执行文件就在/opt/mongodb/bin目录下。为了方便使用我们将其添加到系统的PATH环境变量中。编辑当前用户的~/.bashrc文件nano ~/.bashrc在文件末尾添加export PATH/opt/mongodb/bin:$PATH保存退出CtrlX然后按Y再按回车。让配置生效source ~/.bashrc验证MongoDB Shell是否可以运行mongosh --version如果看到版本信息说明安装成功。注意新版本MongoDB的命令行工具是mongosh旧版的mongo已逐渐被取代。4.3 创建数据目录、日志目录并配置服务MongoDB运行时需要存储数据的目录和写日志的目录。按照Linux的惯例数据可以放在/var/lib下日志放在/var/log下。# 创建数据目录和日志目录 sudo mkdir -p /var/lib/mongodb sudo mkdir -p /var/log/mongodb # 将目录的所有权赋予给一个非root用户例如你当前登录的用户假设用户名为‘pi’ sudo chown -R pi:pi /var/lib/mongodb sudo chown -R pi:pi /var/log/mongodb重要提示在生产环境中出于安全考虑应该创建一个专门的mongodb系统用户和用户组来运行MongoDB服务并将目录所有权赋予该用户。这里为了简化我们使用了当前用户。如果你打算长期运行重要服务请务必研究并设置专门的用户和权限。接下来创建一个MongoDB的配置文件。在/etc下创建一个配置文件目录和文件sudo mkdir -p /etc/mongodb sudo nano /etc/mongodb/mongod.conf写入以下基本配置systemLog: destination: file path: /var/log/mongodb/mongod.log logAppend: true storage: dbPath: /var/lib/mongodb journal: enabled: true net: bindIp: 127.0.0.1 # 默认只监听本地回环地址确保安全。如果需要远程连接可改为 0.0.0.0但务必配置认证 port: 27017 processManagement: fork: true # 以守护进程方式运行 pidFilePath: /tmp/mongod.pid保存并退出。4.4 启动MongoDB服务与测试现在我们可以使用配置文件来启动MongoDB了mongod --config /etc/mongodb/mongod.conf如果配置正确MongoDB会在后台启动。你可以检查日志文件看是否有错误tail -f /var/log/mongodb/mongod.log看到类似[initandlisten] waiting for connections on port 27017的日志说明启动成功。用mongosh连接本地服务进行测试mongosh你会进入MongoDB Shell。可以执行一些基本命令// 显示所有数据库 show dbs // 使用或创建一个测试数据库 use testdb // 插入一条文档 db.testcoll.insertOne({ name: Raspberry Pi, project: Node.js Env }) // 查询 db.testcoll.find()输入.exit或按CtrlD退出Shell。4.5 配置系统服务Systemd实现开机自启手动启动毕竟不方便。我们需要配置一个systemd服务让MongoDB可以像其他系统服务一样被管理启动、停止、重启、开机自启。创建服务单元文件sudo nano /etc/systemd/system/mongodb.service写入以下内容注意ExecStart路径和User要与你实际情况匹配[Unit] DescriptionMongoDB Database Server Documentationhttps://docs.mongodb.org/manual Afternetwork.target [Service] Userpi # 替换为运行MongoDB的用户这里用了pi Grouppi # 替换为对应用户组 ExecStart/opt/mongodb/bin/mongod --config /etc/mongodb/mongod.conf ExecStop/opt/mongodb/bin/mongod --config /etc/mongodb/mongod.conf --shutdown Restarton-failure RestartSec10 StandardOutputsyslog StandardErrorsyslog SyslogIdentifiermongodb [Install] WantedBymulti-user.target保存退出后重新加载systemd配置启用并启动服务sudo systemctl daemon-reload sudo systemctl enable mongodb.service # 启用开机自启 sudo systemctl start mongodb.service # 立即启动服务检查服务状态sudo systemctl status mongodb.service如果显示active (running)恭喜你MongoDB服务已经配置成功并且会随系统自动启动。现在你的树莓派上已经拥有了一个完全由systemd管理的、稳定运行的MongoDB数据库服务。5. 环境验证与第一个Node.js应用环境搭建好了我们来跑一个最简单的Node.js应用连接我们刚安装的MongoDB确保整个链路是通的。5.1 创建项目目录与初始化在家目录下创建一个新的项目目录cd ~ mkdir my-raspi-app cd my-raspi-app初始化一个Node.js项目创建package.json文件npm init -y安装MongoDB的Node.js驱动mongodbnpm install mongodb5.2 编写测试脚本创建一个名为app.js的文件nano app.js写入以下代码const { MongoClient } require(mongodb); // 连接字符串连接到本地默认端口的MongoDB const uri mongodb://127.0.0.1:27017; const client new MongoClient(uri); async function run() { try { // 连接到数据库 await client.connect(); console.log(成功连接到 MongoDB); // 指定数据库和集合 const database client.db(raspiTestDB); const collection database.collection(devices); // 插入一条文档 const insertResult await collection.insertOne({ name: Raspberry Pi 5, os: Raspberry Pi OS 64-bit, nodeVersion: process.version, timestamp: new Date() }); console.log(已插入文档ID为${insertResult.insertedId}); // 查询所有文档 const docs await collection.find({}).toArray(); console.log(当前集合中的文档); console.log(docs); } finally { // 确保关闭连接 await client.close(); console.log(MongoDB 连接已关闭。); } } // 运行主函数并捕获错误 run().catch(console.dir);5.3 运行测试保存文件后在终端运行node app.js如果一切配置正确你将在终端看到类似以下的输出成功连接到 MongoDB 已插入文档ID为661a1234b5678c901d234567 当前集合中的文档 [ { _id: ObjectId(661a1234b5678c901d234567), name: Raspberry Pi 5, os: Raspberry Pi OS 64-bit, nodeVersion: v20.11.1, timestamp: 2024-04-12T10:30:00.000Z } ] MongoDB 连接已关闭。这个输出意味着Node.js运行正常。Node.js的MongoDB驱动包安装正常。应用程序能够成功连接到本地运行的MongoDB服务。数据库的读写操作插入和查询都执行成功。至此我们已经完成了从裸机树莓派到Node.js MongoDB全功能开发/部署环境的完整搭建。这个环境已经具备了运行大多数基于此技术栈的Web应用、API服务或后台程序的能力。6. 后续优化与安全加固建议基础环境搭好了但离一个健壮的“生产就绪”环境还有距离。这里分享几个我认为非常重要的后续步骤你可以根据自己的需求来选择实施。6.1 更换APT软件源树莓派默认的软件源在国外更新和安装软件速度可能较慢。我们可以将其替换为国内的镜像源如清华大学TUNA或中科大的镜像。这能极大提升apt update和apt install的速度。备份原有源列表sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo cp /etc/apt/sources.list.d/raspi.list /etc/apt/sources.list.d/raspi.list.bak编辑源文件将deb.debian.org和archive.raspberrypi.org的URL替换为镜像站地址。具体替换内容请参考你选择的镜像站提供的树莓派/Debian帮助页面。这是一个需要谨慎操作的过程错误的源配置可能导致系统无法更新。6.2 为MongoDB启用身份验证我们之前的配置中MongoDB监听在127.0.0.1只能本地访问这已经是一层安全防护。但如果你的应用需要远程连接或者未来可能需要启用身份验证是必须的。首先以无认证模式启动MongoDB如果当前服务正在运行先停止它sudo systemctl stop mongodb然后以mongod --config /etc/mongodb/mongod.conf --noauth临时启动或者直接修改配置文件将bindIp改为127.0.0.1并重启。使用mongosh连接在admin数据库中创建管理员用户。use admin db.createUser({ user: adminUser, pwd: 你的强密码, // 务必使用强密码 roles: [ { role: userAdminAnyDatabase, db: admin }, readWriteAnyDatabase ] })修改MongoDB配置文件/etc/mongodb/mongod.conf在security部分启用认证security: authorization: enabled重启MongoDB服务sudo systemctl restart mongodb。现在连接时就需要指定用户名和密码了mongosh -u adminUser -p --authenticationDatabase admin或者在连接字符串中体现mongodb://adminUser:密码127.0.0.1:27017/admin。6.3 配置防火墙如果启用Raspberry Pi OS默认没有启用防火墙UFW。如果你的树莓派暴露在公网极度不推荐除非你知道你在做什么或者想加强内网安全可以安装并配置UFW。sudo apt install ufw # 默认拒绝所有入站允许所有出站 sudo ufw default deny incoming sudo ufw default allow outgoing # 允许SSH连接否则启用防火墙后会断连 sudo ufw allow ssh # 如果你需要从外部访问MongoDB再次强调风险才需要开放27017端口 # sudo ufw allow 27017 # 启用防火墙 sudo ufw enable6.4 性能与监控考量树莓派性能有限尤其是IO性能MicroSD卡。对于数据库应用IO是瓶颈。考虑使用USB 3.0 SSD如果你有树莓派4或5强烈建议将系统迁移到外接的USB 3.0 SSD硬盘上这将带来巨大的性能提升特别是对于MongoDB这类频繁读写数据库的服务。这涉及到从SSD启动系统的配置是一个相对进阶的操作。监控资源使用可以使用htop、iotop、nmon等工具监控CPU、内存、IO状态。glances也是一个不错的全能监控工具可以通过pip3 install glances安装。日志管理MongoDB和你的应用都会产生日志。定期检查/var/log/mongodb/mongod.log并考虑使用logrotate工具配置日志轮转防止日志文件撑满存储空间。搭建环境只是第一步让环境稳定、安全、高效地运行才是更长期的课题。希望这篇超过5000字的详细指南能帮你绕过我当年踩过的那些坑顺利在树莓派上开启你的全栈之旅。下一篇我们可能会探讨如何在这个基础环境上使用Docker容器化部署Node.js应用和MongoDB那将是另一种更简洁、更隔离的管理方式。
