树莓派5部署Node.js与MongoDB：从零搭建全栈开发环境-尧图网站建设

📅 发布时间：2026/7/29 6:08:38

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 pi@raspberrypi-node.local

如果.local域名解析失败（在某些网络环境下可能发生），你需要先找到树莓派的IP地址。可以通过路由器管理界面查看，或者使用网络扫描工具。然后用IP地址连接：

ssh 你的用户名@树莓派的IP地址

首次连接会提示主机密钥认证，输入yes，然后输入你设置的密码，即可登录。

登录后，第一件事是更新系统软件包列表并升级现有软件。这是保持系统安全稳定的好习惯。

sudo apt update sudo apt upgrade -y

upgrade过程可能会比较长，取决于网络速度和需要更新的包数量。完成后，建议重启一次：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.x）：

nvm install --lts

或者安装一个特定版本：

nvm install 20.11.1

安装完成后，将其设置为默认版本：

nvm alias default 20.11.1

这样，每次新开终端，都会自动使用这个版本。

验证Node.js和npm是否安装成功：

node -v npm -v

3.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版本后期开始，停止为ARMv7（32位）架构提供预编译的社区版二进制包。树莓派4之前的型号大多是ARMv7。而树莓派4/5虽然是ARMv8（64位）架构，但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.tgz

4.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

保存退出（Ctrl+X，然后按Y，再按回车）。让配置生效：

source ~/.bashrc

验证MongoDB Shell是否可以运行：

mongosh --version

如果看到版本信息，说明安装成功。注意，新版本MongoDB的命令行工具是mongosh，旧版的mongo已逐渐被取代。

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或按Ctrl+D退出Shell。

4.5 配置系统服务（Systemd）实现开机自启

手动启动毕竟不方便。我们需要配置一个systemd服务，让MongoDB可以像其他系统服务一样被管理（启动、停止、重启、开机自启）。

创建服务单元文件：

sudo nano /etc/systemd/system/mongodb.service

写入以下内容（注意ExecStart路径和User要与你实际情况匹配）：

[Unit] Description=MongoDB Database Server Documentation=https://docs.mongodb.org/manual After=network.target [Service] User=pi # 替换为运行MongoDB的用户，这里用了pi Group=pi # 替换为对应用户组 ExecStart=/opt/mongodb/bin/mongod --config /etc/mongodb/mongod.conf ExecStop=/opt/mongodb/bin/mongod --config /etc/mongodb/mongod.conf --shutdown Restart=on-failure RestartSec=10 StandardOutput=syslog StandardError=syslog SyslogIdentifier=mongodb [Install] WantedBy=multi-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驱动mongodb：

npm install mongodb

5.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 enable

6.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，那将是另一种更简洁、更隔离的管理方式。

树莓派5部署Node.js与MongoDB：从零搭建全栈开发环境