用1Panel部署Node+MongoDB+Nginx项目完整指南

说实话，在自己服务器上捣鼓一套 Node + MongoDB + Nginx 的项目，过去真是件磨人的事。装 Node 要手动配环境变量，MongoDB 装完不配认证就裸奔，Nginx 的 location 里多写少写一个斜杠，都能让你排查到半夜。后来我在一个实际项目里开始用 1Panel 做部署管理，整条链路才算是真正顺畅起来。这篇东西就是把我用 1Panel 部署 Node + MongoDB + Nginx 项目的完整过程，连同踩过的坑、查过的报错、最后怎么解决的一起整理出来。适合所有想把前后端项目快速跑在云服务器上的开发者，尤其是第一次接触 Linux 面板、不想在生产环境里裸敲一堆命令的人。

1. 部署方案设计与环境准备：为什么这次选 1Panel

1.1 1Panel 到底解决了什么问题

1Panel 是一款开源、免费的 Linux 服务器运维管理面板，底层用 Go 开发，界面是全中文的。它跟宝塔这类面板定位不太一样，更强调容器化、安全性和应用商店的可控性。对我这种常年跟 Node 项目的后端开发来说，最实在的价值有三个：

第一，应用商店里已经把 Nginx、MongoDB、MySQL、Node.js 这类基础组件封装好了，点两下就能装，不用自己记一堆安装命令。第二，文件管理、终端、日志查看都在浏览器里完成，省了反复 SSH 登录的时间。第三，它默认启用了 fail2ban 防暴力破解、SSH 安全配置检查这些安全能力，对部署完就不太想管服务器的个人开发者来说，相当于多了一道保险。

当然，不是说没有 1Panel 就部署不了，而是有了它之后，整个流程从“一个晚上可能搞不完”缩短到“一杯咖啡的时间”。尤其是 MongoDB 和 Nginx 这种东西，默认配置其实离生产可用还有距离，面板给了你一个可视化的操作入口，后面再手动补安全设置和调优也方便很多。

1.2 部署前的服务器准备与面板安装

我这次用的是一台 2核4G 的云服务器，系统是 Ubuntu 22.04。做 Node 项目的部署，这个配置算比较标准的起步档，再低的话 npm 安装依赖、MongoDB 跑索引构建都会明显吃力。服务器硬盘建议至少 40G，因为 MongoDB 的数据文件和日志增长起来比想象中快。

安装 1Panel 前，建议先确认服务器能正常访问外网，因为安装脚本需要拉取依赖包和 Docker 镜像。官方一键安装命令大概是这样的（以官网最新命令为准）：

bash复制curl -sSL https://resource.fit2cloud.com/1panel/package/quick_start.sh -o quick_start.sh
sudo bash quick_start.sh

脚本执行过程中会提示设置面板端口、用户名和密码。这里有个很重要的建议：面板端口不要用默认的 8090，改成 29120 这种非常规端口，能少挨很多扫描器的打。安装完成后，脚本会输出一个面板访问地址，类似 http://服务器IP:端口，用浏览器打开就能进后台。

同时在云服务器的安全组或者防火墙里，需要提前放行 80、443、面板端口，以及项目要用的业务端口。这一步看起来基础，但往往就是“部署完了外网访问不了”的头号原因。如果你用的是阿里云、腾讯云这类平台，记得去控制台的安全组规则里加，单纯的 Linux 防火墙放行是不够的。

1.3 面板装好后，有 3 件事必须提前做

第一件，设置服务器地址。很多人第一次在面板里安装应用时会看到一行提示：“1panel 当前未设置服务器地址，请先在面板设置中设置!”。这东西不设置好，应用商店的同步、镜像拉取都会出问题。操作路径是：面板设置 → 系统 → 服务器地址，填入服务器绑定的域名或 IP 地址。如果是 IP 访问，填 IP 就行；如果有备案域名，建议直接填域名，后面给网站配 SSL 证书时也会省事不少。

第二件，切换镜像源。1Panel 的应用商店默认从官方源拉取应用定义，Docker 镜像也有默认仓库。国内服务器不换源的话，安装 MongoDB 这类大镜像很容易超时失败。在面板的“设置 → 镜像加速”里，填上可用的国内镜像加速地址，比如 Docker 官方中国镜像、一些大厂提供的加速器地址，具体以面板支持的列表为准。

第三件，开启面板的防火墙并限制访问来源。生产环境建议只允许自己的办公网 IP 访问面板端口，防止面板本身成为攻击入口。1Panel 自带的防火墙功能可以按 IP 段放行，比直接在系统层配 iptables 直观得多。这三件事做完，后面安装应用和服务的过程会顺利一大截。

2. Node.js 环境安装：版本和源是两大坎

2.1 应用商店安装和 nvm 手动安装怎么选

1Panel 的应用商店里确实有 Node.js，点一下就能部署一个容器化的 Node 环境。但我个人的实际建议是：部署生产项目，Node 环境最好装在宿主机上，或者至少用 nvm 做版本管理，而不是直接丢在容器里让面板托管。

原因很简单。第一，Node 项目经常要装全局命令行工具，比如 pm2、pnpm，容器里装完，重启容器就没了，还得重新进容器配置。第二，项目调试时你经常要改文件、看日志、重启进程，宿主机上操作显然比进容器方便。第三，Node 版本迭代太快，面板商店里的版本往往滞后，而 nvm 随时可以安装官方最新 LTS 版本。

所以我的方案是：Node 用 nvm 管理，MongoDB、Nginx 这类稳定服务用面板的应用商店或容器方式装，各取所长。

2.2 nvm 安装与 Node 版本切换实操

nvm（Node Version Manager）是我在所有 Linux 服务器上装 Node 的第一选择。它解决的问题很直接：一台机器上可能需要多个 Node 版本，今天跑老项目要 v16，明天新项目要 v22，用 nvm 切换就是一条命令的事。

安装 nvm 的步骤其实很简单，先拉取脚本：

bash复制curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

安装完成后，重新登录终端，执行 nvm --version 看是否生效。如果提示找不到命令，检查一下 ~/.bashrc 或 ~/.profile 里有没有加载 nvm 的初始化语句，手动 source 一下即可。

接着安装 Node。我这次部署的项目用的是 Node 22，属于当前活跃 LTS 版本，直接执行：

bash复制nvm install 22.19.0
nvm use 22.19.0
nvm alias default 22.19.0

nvm alias default 这步别省略，否则服务器重启后 Node 可能不在 PATH 里，导致 pm2 守护的进程无法自动拉起。装完后验证：

bash复制node -v
npm -v

npm 默认源在海外，国内服务器的安装速度很感人。必须要设置国内镜像，我用的是 npmmirror：

bash复制npm config set registry https://registry.npmmirror.com

然后全局装 pm2，后面用它来守护 Node 进程：

bash复制npm install -g pm2

装完 pm2 后，建议直接用 pm2 启动项目：

bash复制pm2 start app.js --name my-api
pm2 save
pm2 startup

pm2 startup 会生成一个开机自启脚本，保证服务器重启后进程能自动跑起来。这一步很多人会漏掉，结果服务器一重启，网站直接挂掉。

2.3 内网环境没有外网，Node 怎么离线装

有的项目部署在纯内网环境，服务器无法访问外网，nvm 和 npm 这条路就走不通了。这时候需要提前在能联网的机器上准备好离线安装包。

以 Node v22.19.0 为例，去 Node 官网下载对应的 Linux 二进制包，文件名类似 node-v22.19.0-linux-x64.tar.xz。然后通过 ftp、scp、U盘拷贝等方式传到内网服务器上，解压：

bash复制tar -xf node-v22.19.0-linux-x64.tar.xz -C /usr/local/
mv /usr/local/node-v22.19.0-linux-x64 /usr/local/node

再把 Node 的 bin 目录加入 PATH。编辑 /etc/profile，在末尾加一行：

bash复制export PATH=/usr/local/node/bin:$PATH

执行 source /etc/profile 让配置生效，然后验证 node -v。离线环境如果要装 npm 依赖包，同样需要提前在有网的机器上把依赖下载成 node_modules 目录或打成 tar 包，再传到内网解压。这个流程看起来繁琐，但确实是最靠谱的离线方案，我踩过一次“下载了个源码包结果编译半天失败”的坑之后，就老老实实改用二进制包了。

2.4 搜热词时发现的两个高频 Node 报错

部署完 Node 环境后，本机和服务器上经常遇到两类报错。第一种是 Windows 本地上运行 npm 时报的：

code复制npm : 无法加载文件 D:\node\npm.ps1，因为在此系统上禁止运行脚本。

这个问题的根源是 PowerShell 的执行策略默认禁止运行脚本，跟你 Node 装没装好没关系。解决方法是管理员身份打开 PowerShell，执行：

powershell复制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

然后再开一个新的 PowerShell 窗口，npm 命令就正常了。

第二种是启动项目时报模块导入错误：

code复制SyntaxError: The requested module 'node:util' does not provide an export named ...

这类报错基本可以断定是 Node 版本太旧。node: 前缀是 Node 16 之后引入的模块标识方式，某些内置模块的导出还依赖更新的运行时。解决办法就是把 Node 升到 v18 以上的 LTS 版本，如果项目里用了较新的 ESM 语法和 API，直接上 v20 或 v22 更省心。我在升级之前也试过在项目里折腾 type: module 和导入方式，最后发现升级 Node 才是正解。

3. MongoDB 部署：装完先做安全配置再谈查询优化

3.1 应用商店安装 MongoDB 与安装失败排查

在 1Panel 后台，左侧菜单找到“应用商店”，搜索 MongoDB，选择一个稳定的版本安装。我在生产环境选的是 4.4.30，这个版本在性能和稳定性之间比较平衡，社区资料也多。如果你是全新项目、没有历史包袱，选 5.x 或 6.x 当然也没问题，但对个人服务器来说，4.4 系列的低资源占用确实更友好。

应用商店里创建 MongoDB 时，会要求设置 root 用户密码、数据目录、宿主机端口映射等参数。这里有个细节：MongoDB 容器默认监听 27017，面板会把它映射到宿主机的某个端口。如果你不想让数据库直接暴露到公网，可以在“高级设置”里把端口映射去掉，或者改成只监听 127.0.0.1，这样只有本机上的应用能访问，外界扫不到你的数据库。

安装失败的常见原因，第一是镜像拉取超时，这个用 1.3 节里说的国内镜像加速基本能解决。第二是端口冲突，如果你之前已经装过 MongoDB，新实例端口被占，配置里换一个宿主机映射端口就行。第三是磁盘空间不足，MongoDB 容器镜像加数据卷初始化会有几个 GB 的占用，检查一下 df -h 看剩余空间。

如果安装到一半失败，先在 1Panel 的“容器 → 日志”里看一下具体报错，不要直接重装。我遇到过容器一直重启的情况，点开日志才发现是数据目录权限问题，处理完权限后容器很快就稳定了。

3.2 必做的安全配置：开启认证，防止未授权访问

MongoDB 有个老生常谈的安全问题：未授权访问漏洞。默认安装的 MongoDB 如果没开启认证，任何人都能通过 27017 端口连接你的数据库，把数据删光打包带走都行。我在早期部署时有一次没配认证，第二天发现数据库被清空，对方还留了勒索信息，从此之后再也不敢裸奔了。

在 1Panel 安装 MongoDB 时，即便设置了 root 密码，也建议手动确认认证机制是否启用。进入 MongoDB 容器终端，用 mongosh 连接：

bash复制mongosh --port 27017 -u root -p '你的密码' --authenticationDatabase admin

连接成功后，查看当前用户列表：

javascript复制db.system.users.find()

确认 root 用户存在之后，还要检查 MongoDB 配置文件里是否开启了授权。在容器内查看配置文件（通常位于 /etc/mongod.conf 或 /etc/mongodb.conf），确认其中包含：

yaml复制security:
  authorization: enabled

如果没开启，修改后重启容器。对生产环境，我的建议是再创建一个专用业务账号，只给某个数据库的读写权限，连接字符串用这个账号，而不是直接用 root：

bash复制mongosh -u root -p '密码' --authenticationDatabase admin
use myproject
db.createUser({
  user: "myapp",
  pwd: "复杂密码",
  roles: [{ role: "readWrite", db: "myproject" }]
})

这样即使业务账号泄露，攻击者也拿不到整个 MongoDB 实例的权限。

3.3 数据查询性能的关键：索引是必答题

数据库装好、连上了，紧接着要面对的就是查询性能问题。MongoDB 的索引有多重要，很多大厂案例都能说明白：早期滴滴的订单轨迹、摩拜的单车位置信息，这些高频写入、高频查询的数据都是放在 MongoDB 里的。数据量一旦上去，没有索引的查询就是全表扫描，可能从毫秒级直接退化到几十秒级，接口直接超时。

部署完数据库后，我总是第一时间给业务高频查询字段建索引。比如项目里的文章列表接口，经常按状态和创建时间过滤，就需要建一个复合索引：

bash复制db.articles.createIndex({ status: 1, createdAt: -1 })

建索引前，用 explain 看一下查询计划，确认是否走了期望的索引：

bash复制db.articles.find({ status: "published" }).sort({ createdAt: -1 }).explain("executionStats")

如果 totalDocsExamined 远大于 totalKeysExamined，说明索引没建对，或者正在全表扫描。通过 1Panel 的 MongoDB 管理界面，也能看到集合的索引列表和查询耗时，对排查慢查询很有帮助。索引不是越多越好，每个索引都会拖慢写入和占用磁盘，只给真正高频的查询路径建索引就对了。

3.4 MongoDB 基础操作与 Compass 工具

部署好 MongoDB 之后，日常用得最多的还是 mongosh 命令行和 MongoDB Compass 图形工具。基础操作其实就几个：看数据库、看集合、增删改查。

bash复制# 查看数据库列表
show dbs
# 切换到指定数据库
use myproject
# 查看集合
show collections
# 查询
db.users.find().pretty()
# 插入
db.users.insertOne({ name: "张三", age: 30 })

MongoDB Compass 是官方出的桌面客户端，可视化程度很高，适合不习惯命令行的同学。连接时填服务器地址、端口、认证库和账号密码就能连上。我在本地环境调试时常用 Compass 看数据形态、跑聚合管道，比在终端里看 JSON 直观得多。但要注意，生产服务器的 MongoDB 一般不建议直接开公网端口给 Compass 连接，更安全的做法是用 SSH 隧道转发到本机，再在本机用 Compass 连 localhost:27017。

类似地，如果只是在 1Panel 服务器本机调试，可以直接用面板里的“终端”功能登录服务器，执行 mongosh 连本机数据库，这样连 SSH 端口映射都省了。

4. Nginx 反向代理：多个项目共存的正确姿势

4.1 1Panel 里添加反向代理网站

Nginx 在 1Panel 里的定位是“网站”功能模块。面板默认会在应用商店里安装好 Nginx，然后在“网站”页面点击“创建网站”，选择“反向代理”类型，填上域名、后端地址和端口，面板就会自动生成一份 Nginx 配置。

对于 Node 项目，后端地址通常指向本机的某个端口，比如 http://127.0.0.1:3000。这里有几个关键点：

• 域名：如果还没有域名，先用 IP 加端口访问，等备案或解析完成后再换成域名。
• HTTPS：如果域名已经解析到服务器，建议直接在 1Panel 里申请 SSL 证书（面板支持 Let‘s Encrypt 自动签发和续期），启用 HTTPS。搜索引擎和浏览器现在对 HTTP 站点越来越不友好，能上 HTTPS 就尽快上。
• 静态文件目录：如果前端是纯静态文件，可以在“网站”里再创建一个静态网站类型，把前端构建产物上传到指定目录。

1Panel 会自动管理 Nginx 配置文件的生成和重载，不需要自己去啃 /etc/nginx/nginx.conf 的原始文件。不过，稍复杂的配置还是需要手动改写，下面详细说。

4.2 一个项目拆成前后端的 Nginx 配置详解

很多前后端分离项目，前端是 Vue/React 构建的静态文件，后端是一个 Node API 服务。Nginx 要做两件事：一是托管前端静态文件，二是把 /api 路径的请求反向代理到 Node 进程。

一份典型的 Nginx server 配置长这样：

nginx复制server {
    listen 80;
    server_name example.com;

    # 前端静态文件
    root /opt/www/example/dist;
    index index.html;

    # 后端 API 反向代理
    location /api/ {
        proxy_pass http://127.0.0.1:3000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # 前端路由 history 模式需要
    location / {
        try_files $uri $uri/ /index.html;
    }
}

这里最需要注意的就是 proxy_pass 后面的斜杠。http://127.0.0.1:3000/ 末尾带了 /，表示转发时去掉 /api 前缀。也就是说，请求 /api/users 会转发到后端的 /users。如果后端路由本身就带 /api 前缀，那 proxy_pass 就不能加斜杠。这个细节不知道坑了多少人，我用一句话总结：斜杠决定了 Nginx 是否保留 location 中的前缀部分。

另外，如果是单页应用（SPA），前端路由用的是 history 模式，刷新某个子路由时会出现 404。解决办法就是上面配置文件里的最后一段 try_files $uri $uri/ /index.html;，把所有路径都兜底到 index.html。

在 1Panel 里，你可以点开网站的“配置文件”标签直接修改这份 Nginx 配置，改完保存后执行 Nginx 重载。面板的 Nginx 配置编辑体验虽然比不上本地编辑器，但语法高亮和错误提示是有的，基本够用。

4.3 多个 Web 项目共用一个服务器的配置思路

现实场景里，一台 2核4G 的服务器往往要同时跑几个项目：一个公司官网、一个后台管理、一个 API 服务。Nginx 处理多个项目有两种主流方式：按域名区分和按路径区分。

按域名区分最简单，每个域名一个 server 块：

nginx复制server {
    listen 80;
    server_name a.com;
    root /opt/www/a;
    location / {
        try_files $uri $uri/ /index.html;
    }
}

server {
    listen 80;
    server_name b.com;
    root /opt/www/b;
    location / {
        try_files $uri $uri/ /index.html;
    }
}

按路径区分适合一个域名下挂多个应用，比如同一个 example.com 下 /blog 是博客，/admin 是后台。

nginx复制server {
    listen 80;
    server_name example.com;

    location /blog/ {
        alias /opt/www/blog/;
        index index.html;
    }

    location /admin/ {
        alias /opt/www/admin/;
        index index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:3000/api/;
    }
}

多个 Node 服务可能同时跑，需要给每个服务分配不同端口，比如后台 API 跑 3000，官网 API 跑 3001。如果后端要做负载均衡，Nginx 还能用 upstream 配置多个后端节点：

nginx复制upstream node_backend {
    server 127.0.0.1:3001 weight=2;
    server 127.0.0.1:3002 weight=1;
}

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://node_backend;
        proxy_set_header Host $host;
    }
}

我自己的经验是，个人服务器尽量别把太多服务堆在一台机器上，内存不够的时候所有服务一起卡。如果一定要堆，那 Node 进程要用 pm2 做资源限制，MongoDB 要启用 wiredTiger 的缓存上限设置，Nginx 的 worker 进程数也不能盲目调到和 CPU 核数相等。

4.4 Nginx 配置排查与日志定位技巧

Nginx 配置写完，如果网站打不开，或者出现 502、504 这类状态码，先别慌。看日志是第一步，在 1Panel 的“网站 → 日志”里能看到访问日志和错误日志。或者直接登服务器执行：

bash复制tail -f /var/log/nginx/error.log

502 的意思是 Nginx 连接不到后端服务，常见原因有：Node 进程挂了、端口写错、后端服务监听的是 IPv6 而 Nginx 用的是 IPv4。504 通常是后端处理超时，需要检查 Node 接口是不是有慢查询或者第三方请求超时。

我遇到过最隐蔽的一个问题：Node 服务明明在运行，接口用 curl 也能通，但 Nginx 转发就报 502。排查了半天发现是 Node 进程监听的是 ::（IPv6 所有地址），而 Nginx 的 proxy_pass 用的是 127.0.0.1 这个 IPv4 地址，连接不上。解决办法是把 Node 监听地址改成 0.0.0.0，或者在 Nginx 里改用 [::1] 去连接。

修改 Nginx 配置后，记得先执行 nginx -t 校验语法，确认无误后再重载。1Panel 在保存配置时会自动做语法检查，如果有错误会直接弹提示，还是很友好的。

5. 高频问题排查速查：部署完最常碰到的几个坑

5.1 常见报错与解决对照表

整个流程走下来，我把高频问题和对应解法整理成了一个速查表，部署时遇到直接对照：

这些坑有一个共同特征：基本都是配置问题，不是代码问题。所以排查的时候养好习惯，从上到下看日志，从外到内查端口，不要一上来就怀疑项目代码。

5.2 几个特别值得展开说的实际案例

第一个案例是 MongoDB 安装失败。我那次在 1Panel 应用商店里点安装 MongoDB，状态一直显示“创建中”，等了十分钟都没好。点进容器列表一看，容器状态是“重启中”。查看日志才发现，初始化脚本里要用 hostname 解析，但容器网络的 DNS 配置有问题。处理方法是把容器的网络模式改成 host，或者手动指定 DNS 为 8.8.8.8。这种情况在特定云厂商的 VPC 环境下偶尔会出现，不是面板的锅，但确实让人摸不着头脑。

第二个案例是 Nginx 配置完多个网站后，其中一个网站一直 403。排查后确定是目录权限问题：网站文件放在 /opt/www/ 下，但 Nginx 的 worker 进程用户是 www-data，对目录没有读权限。用 chmod -R 755 /opt/www 和 chown -R www-data:www-data /opt/www 解决。所以部署静态站点时，一定要确认文件所有者和权限，这个在 1Panel 的文件管理器里也能直接改。

第三个案例是 pm2 进程守护失效。我把 Node 应用加到 pm2 后，测试重启服务器发现应用没有自动恢复。检查后确认是 pm2 save 和 pm2 startup 没有执行，或者执行用户不对。pm2 的 startup 脚本是和用户绑定的，如果你之前用 root 启动，重启后用其他用户登录，是看不到进程的。建议全程用一个部署用户来管理 Node 和 pm2，别一会儿 root 一会儿普通用户，免得进程管理混乱。

5.3 给第一次用 1Panel 部署的人的建议

如果你正准备照着这个流程部署自己的第一个项目，我的建议是先在本地或者测试服务器上把流程完整走一遍，再上生产。具体来说有三件事：

第一，先在本地把 Node 项目跑通，确认数据库连接、接口逻辑都没有问题，再上服务器部署。服务器上排查问题的成本比本地高得多。第二，MongoDB 的认证和 Nginx 的 HTTPS 证书，最好在部署当天就配好，千万不要想“先跑起来再说”。安全这种东西是一票否决项，裸奔的数据库挂在公网上，快的话几小时就会被人扫描到。第三，安装完所有服务后，及时在 1Panel 里做一次快照或者备份策略，至少把 MongoDB 的数据目录和 Nginx 的配置目录纳入备份计划。数据备份是最便宜的风险对冲手段，等到数据丢了再想起来就晚了。

我在实际部署中还有一个体会：1Panel 的“计划任务”功能可以用来定期备份数据库、清理日志。比如每天凌晨 3 点自动执行 MongoDB 的 dump 备份，保留最近 7 天，这些都在面板里可视化配置，比自己在 crontab 里写脚本直观不少。把这些基础工作做好了，后面项目上线迭代就只需要关注业务代码本身了。