AuthHub 多程序聚合授权系统【小白安装教程】

智能摘要

你想搭建一个自己的授权验证系统，但被网上那些动辄几十条命令的部署教程吓退了？看着满屏的SSH命令和配置文件，你甚至不知道从哪开始。实际上，部署一个生产级授权系统，根本不需要你懂Linux。宝塔面板加上一条npm命令，就能自动完成依赖安装、数据库初始化和PM2进程管理。这个小白教程把原本需要一下午的工作，压缩到了20分钟。但真正关键的问题在于：为什么官方要特意留这个“一步到位”的入口？这背后藏着的部署逻辑，可能和你想象的完全不一样。

这份教程给第一次部署的人看。照着做即可，推荐使用宝塔面板或 1Panel 面板部署。

一、准备材料

你需要准备：

一台 Linux 服务器
一个已经解析到服务器的域名，例如 auth.example.com
宝塔面板或 1Panel 面板
MySQL 5.7+ / MySQL 8.0+ / MariaDB 10.3+
Node.js 20+
项目发布包，例如：

epay-plugin-auth-workspace-1.0.0-20260616142937.zip

发布包由开发者提前打好，安装用户只需要上传和解压。

解压后目录大概是：

epay-plugin-auth-workspace-1.0.0-xxxxxxxxxxxx/
├── frontend/          # 前端静态文件
├── backend/           # 后端服务
│   ├── dist/
│   ├── package.json
│   ├── .env.example
│   └── scripts/
├── database/          # 数据库脚本
├── INSTALL.md         # 小白安装教程
└── README-DEPLOY.md

二、最简安装流程

如果你已经会在面板里创建网站和数据库，按这个流程走即可：

上传发布包，整理成 frontend/、backend/、database/ 三个目录
面板里创建 MySQL 数据库
复制 backend/.env.example 为 backend/.env，填数据库账号密码和 JWT_SECRET
进入 backend 目录执行：

npm run deploy

这条命令会自动完成依赖安装、发布包检查、空数据库初始化、PM2 启动或重启、后端健康检查。

在面板的 Nginx/OpenResty 配置里，把 /api/、/ws/、/uploads/、/health 代理到 http://127.0.0.1:3000
在伪静态里配置前端路由回退：try_files $uri $uri/ /index.html

第一次安装不需要手动运行一堆 PM2 命令，也不需要手动安装扩展依赖。后端目录里执行一次 npm run deploy 即可。

三、宝塔面板安装

1. 安装运行环境

在宝塔面板安装：

Nginx
MySQL
Node.js 20 或更高版本
PM2 管理器

如果宝塔的软件商店里没有 Node.js 20，建议用服务器终端安装：

curl -fsSL https://rpm.nodesource.com/setup_20.x | bash -
yum install -y nodejs
node -v
npm -v

Ubuntu/Debian 用：

curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs
node -v
npm -v

注意：不要再单独执行 apt install npm。上面的 apt install -y nodejs 已经会带上匹配的 npm。

如果安装时出现 Daemons using outdated libraries，问你 Which services should be restarted?，这不是报错。保持默认勾选，按 Tab 选到 <Ok>，再按 Enter 继续即可。

看到 v20.x.x 就可以。

2. 创建网站

进入宝塔面板：

网站 -> 添加站点

填写：

域名：auth.example.com
根目录：/www/wwwroot/epay-plugin-auth/frontend
数据库：先不创建或选择不创建
PHP：纯静态

创建完成后，记住网站目录。

3. 上传并解压发布包

进入宝塔：

文件 -> /www/wwwroot/

新建目录：

epay-plugin-auth

上传发布包到：

/www/wwwroot/epay-plugin-auth

解压后，把解压出来的内容放成这样：

/www/wwwroot/epay-plugin-auth/frontend
/www/wwwroot/epay-plugin-auth/backend
/www/wwwroot/epay-plugin-auth/database

如果多了一层目录，例如：

/www/wwwroot/epay-plugin-auth/epay-plugin-auth-workspace-1.0.0-xxxx/frontend

就把里面的 frontend、backend、database 移到 /www/wwwroot/epay-plugin-auth/ 下。

解压整理完后，先检查发布包是否完整：

cd /www/wwwroot/epay-plugin-auth
ls -la frontend
ls -la backend
ls -la backend/dist/index.js
ls -la backend/package.json
ls -la backend/scripts/preflight.js
ls -la backend/scripts/deploy.js
ls -la database/schema.sql

必须能看到 backend/dist/index.js。如果提示找不到这个文件，说明后端构建产物没有上传完整，需要重新上传发布包里的整个 backend/dist/ 目录。不要只上传 backend/package.json，也不要只上传 node_modules。

4. 创建数据库

进入宝塔：

数据库 -> 添加数据库

示例填写：

数据库名：pluginsauth
用户名：pluginsauth
密码：自己生成一个强密码
访问权限：本地服务器

这里只需要创建空数据库，不需要手动导入 SQL。

后面执行 npm run deploy 时，如果检测到数据库是空的，会自动导入 schema.sql 和 init_data.sql。如果数据库里已经有表，脚本会跳过初始化，避免覆盖已有数据。

5. 配置后端 `.env`

进入目录：

/www/wwwroot/epay-plugin-auth/backend

复制：

.env.example

改名为：

.env

编辑 .env，示例：

PORT=3000

JWT_SECRET=请改成一串很长的随机字符
JWT_EXPIRE=7d
JWT_REFRESH_EXPIRE=30d

UPLOAD_DIR=./uploads

DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=pluginsauth
DB_PASSWORD=你的数据库密码
DB_NAME=pluginsauth
DB_CHARSET=utf8mb4
DB_SQL_MODE=STRICT_TRANS_TABLES,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION

JWT_SECRET 一定要改，不要用默认值。

6. 一键部署后端

打开宝塔终端，执行一条命令：

cd /www/wwwroot/epay-plugin-auth/backend
npm run deploy

这条命令会自动完成：

检查 Node.js 版本
检查 dist/index.js、.env、package.json
安装生产依赖
检查数据库连接
如果数据库是空的，自动导入 schema.sql 和 init_data.sql
启动或重启 PM2 后端进程
检查 http://127.0.0.1:3000/health

看到 ✅ 后端部署完成 就可以继续下一步。

7. 配置 Nginx

宝塔进入：

网站 -> 你的站点 -> 设置 -> 配置文件

不要把面板生成的配置全部删掉。宝塔/1Panel 默认会有 listen 443 ssl、证书、日志、伪静态、SSL 参数、include 等内容，这些都保留。

主配置只做两件事：

确认 root 指向前端 frontend 目录
在当前 server { ... } 里面新增接口代理

先找到原配置里的 root，改成你的前端目录，例如：

root /www/wwwroot/epay-plugin-auth/frontend;

如果你的目录是 1Panel 这种，也可以是：

root /www/sites/console.sg65.cn/index/frontend;

然后在 server { ... } 里面、最后一个 } 之前，新增下面内容。建议放在已有的 include /www/sites/你的域名/proxy/*.conf; 前面。

注意：这里不要加 location / { ... }，这个放到面板的“伪静态”里配置。

location /api/ {
    proxy_pass http://127.0.0.1:3000/api/;
    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;
}

location /ws/ {
    proxy_pass http://127.0.0.1:3000/ws/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    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;
}

location /uploads/ {
    proxy_pass http://127.0.0.1:3000/uploads/;
    proxy_set_header Host $host;
}

location /health {
    proxy_pass http://127.0.0.1:3000/health;
    proxy_set_header Host $host;
}

再进入：

网站 -> 你的站点 -> 伪静态

把伪静态内容改成：

location / {
    try_files $uri $uri/ /index.html;
}

如果保存时报 duplicate location "/"，说明你在“配置文件”里也加了 location /。删掉配置文件里的 location /，只保留“伪静态”里的这一段。

以面板默认配置为例，最后应该像这样：

server {
    listen 80;
    listen 443 ssl;
    server_name console.sg65.cn;

    # 其他 SSL、日志、证书、header、include 配置都保留

    root /www/sites/console.sg65.cn/index/frontend;
    index index.html index.htm default.html;

    location /api/ {
        proxy_pass http://127.0.0.1:3000/api/;
        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;
    }

    location /ws/ {
        proxy_pass http://127.0.0.1:3000/ws/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;
    }

    location /uploads/ {
        proxy_pass http://127.0.0.1:3000/uploads/;
        proxy_set_header Host $host;
    }

    location /health {
        proxy_pass http://127.0.0.1:3000/health;
        proxy_set_header Host $host;
    }

    include /www/sites/console.sg65.cn/proxy/*.conf;
}

然后在面板“伪静态”里单独填写：

location / {
    try_files $uri $uri/ /index.html;
}

保存后，宝塔会自动检查 Nginx 配置。没有报错就重载 Nginx。

8. 配置 HTTPS

宝塔进入：

网站 -> 你的站点 -> SSL

申请 Let’s Encrypt 免费证书，然后开启强制 HTTPS。

开启 HTTPS 后，Nginx 里的 proxy_set_header X-Forwarded-Proto $scheme; 不要删。

9. 访问后台

浏览器打开：

https://auth.example.com

默认管理员：

用户名：admin
密码：123456

登录后第一件事：立即修改管理员密码。

10. 设置站点基础地址

进入后台后，找到系统配置，把下面这个配置改成你的正式域名：

api_basic_url = https://auth.example.com

这个地址用于生成支付回调、邮箱验证链接等外部访问地址。

四、1Panel 面板安装

1Panel 的思路和宝塔一样：一个静态网站 + 一个 Node 后端进程 + 一个 MySQL 数据库。

1. 安装应用

在 1Panel 应用商店安装：

OpenResty 或 Nginx
MySQL
Node.js 20+

2. 创建网站

进入：

网站 -> 创建网站

选择：

类型：静态网站
主域名：auth.example.com
网站目录：/opt/1panel/apps/openresty/openresty/www/sites/epay-plugin-auth/frontend

不同 1Panel 版本目录可能不同，以面板实际创建的网站目录为准。

3. 上传发布包

在 1Panel 文件管理里，上传发布包并解压。

最终目录建议整理为：

/opt/epay-plugin-auth/frontend
/opt/epay-plugin-auth/backend
/opt/epay-plugin-auth/database

然后把网站运行目录指向：

/opt/epay-plugin-auth/frontend

解压整理完后，先检查发布包是否完整：

cd /opt/epay-plugin-auth
ls -la frontend
ls -la backend
ls -la backend/dist/index.js
ls -la backend/package.json
ls -la backend/scripts/preflight.js
ls -la backend/scripts/deploy.js
ls -la database/schema.sql

4. 创建数据库

进入：

数据库 -> MySQL -> 创建数据库

示例：

数据库名：pluginsauth
用户名：pluginsauth
密码：自己生成一个强密码

这里只需要创建空数据库，不需要手动导入 SQL。

5. 配置后端环境变量

在：

/opt/epay-plugin-auth/backend

复制 .env.example 为 .env，内容参考：

PORT=3000

JWT_SECRET=请改成一串很长的随机字符
JWT_EXPIRE=7d
JWT_REFRESH_EXPIRE=30d

UPLOAD_DIR=./uploads

DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=pluginsauth
DB_PASSWORD=你的数据库密码
DB_NAME=pluginsauth
DB_CHARSET=utf8mb4
DB_SQL_MODE=STRICT_TRANS_TABLES,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION

1Panel 这里最容易填错。

如果后端是用 PM2 在服务器终端启动的，不要把 DB_HOST 填成这种容器名：

DB_HOST=1Panel-mysql-BZWy

这种名字通常只有同一个 Docker 网络里的容器能访问，服务器终端里的 Node 后端不一定能解析。

正确做法：

进入 1Panel -> 应用 -> MySQL -> 参数/端口
找到 MySQL 映射到服务器的端口，一般是 3306，也可能是其他端口
.env 里这样填：

DB_HOST=127.0.0.1
DB_PORT=面板里显示的外部端口

例如面板显示 MySQL 外部端口是 3306，就填：

DB_HOST=127.0.0.1
DB_PORT=3306

6. 一键部署后端

进入终端：

cd /opt/epay-plugin-auth/backend
npm run deploy

这条命令会自动完成：

检查 Node.js 版本
检查 dist/index.js、.env、package.json
安装生产依赖
检查数据库连接
如果数据库是空的，自动导入 schema.sql 和 init_data.sql
启动或重启 PM2 后端进程
检查 http://127.0.0.1:3000/health

看到 ✅ 后端部署完成 就可以继续下一步。

7. 配置网站反向代理

进入 1Panel：

网站 -> 你的站点 -> 配置 -> OpenResty/Nginx 配置

不要整段覆盖面板生成的 server { ... }。保留原来的 listen、server_name、SSL 证书、日志、include 等内容。

只需要确认 root 指向前端目录：

root /opt/epay-plugin-auth/frontend;
index index.html;

然后在当前 server { ... } 里面新增下面几个 location。建议放在已有的 include .../proxy/*.conf; 前面，或者放在最后一个 } 前面。

注意：这里不要加 location / { ... }，这个放到面板的“伪静态”里配置。

location /api/ {
    proxy_pass http://127.0.0.1:3000/api/;
    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;
}

location /ws/ {
    proxy_pass http://127.0.0.1:3000/ws/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    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;
}

location /uploads/ {
    proxy_pass http://127.0.0.1:3000/uploads/;
    proxy_set_header Host $host;
}

location /health {
    proxy_pass http://127.0.0.1:3000/health;
    proxy_set_header Host $host;
}

再进入网站的“伪静态”配置，把内容改成：

location / {
    try_files $uri $uri/ /index.html;
}

如果保存时报 duplicate location "/"，说明你在“配置文件”里也加了 location /。删掉配置文件里的 location /，只保留“伪静态”里的这一段。

保存并重载 OpenResty/Nginx。

8. 申请 HTTPS

进入：

网站 -> 证书 / HTTPS

申请 Let’s Encrypt 证书，并开启强制 HTTPS。

9. 登录后台

浏览器打开：

https://auth.example.com

默认账号：

用户名：admin
密码：123456

登录后立即修改密码，并把系统配置里的：

api_basic_url

改成：

https://auth.example.com

五、常见问题

1. 页面能打开，但登录接口 404

说明 Nginx 没有正确代理 /api/。

检查网站配置里是否有：

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

然后重载 Nginx。

2. 页面刷新后 404

说明伪静态没有配置前端路由回退。

进入面板的“伪静态”，填写：

location / {
    try_files $uri $uri/ /index.html;
}

3. 保存 Nginx 时提示 `duplicate location "/"`

这个错误表示 location / 重复了，通常是“配置文件”里加了一份，“伪静态”里又有一份。

location / {
    ...
}

处理方法：

打开“配置文件”
删除里面的 location / { ... }
打开“伪静态”
只在伪静态里保留下面这段：

location / {
    try_files $uri $uri/ /index.html;
}

不要删除 /api/、/ws/、/uploads/、/health，只处理重复的 location /。

4. 聊天或在线状态不正常

说明 WebSocket 没代理好。

检查是否有：

location /ws/ {
    proxy_pass http://127.0.0.1:3000/ws/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

5. 后端启动失败，提示数据库连接失败

检查 backend/.env：

DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=数据库用户名
DB_PASSWORD=数据库密码
DB_NAME=数据库名

常见原因：

数据库名写错
数据库密码写错
1Panel 里把 DB_HOST 写成了 1Panel-mysql-xxxx 这种容器名。PM2/Node 在主机上运行时一般不能直接连这个容器名，改成 127.0.0.1
MySQL 容器没有映射外部端口，或者 DB_PORT 没填面板显示的外部端口
数据库是空的，但还没有成功执行 npm run deploy

6. 页面请求 `/api/user/info` 返回 502 Bad Gateway

502 一般不是前端问题，是 Nginx/OpenResty 代理不到后端。先在服务器终端检查后端本机端口：

cd /opt/1panel/www/sites/console.sg65.cn/index/backend
npm run deploy

如果你的后端目录不是上面这个，把 cd 后面的路径换成实际的 backend 目录。

npm run deploy 会自动安装依赖、检查发布包、启动或重启 PM2，并检测 /health。如果它仍然失败，再看日志：

npx pm2 status
npx pm2 logs epay-plugin-auth --lines 100 --nostream

如果 pm2 status 里 epay-plugin-auth 是 errored、stopped，或者 /health 连不上，执行：

npx pm2 restart epay-plugin-auth --update-env
npx pm2 logs epay-plugin-auth --lines 100 --nostream

如果提示 Script already launched，说明进程已存在，不要再 start。直接重启即可：

npx pm2 restart epay-plugin-auth --update-env
npx pm2 save

如果进程配置乱了，可以重建一次：

npx pm2 delete epay-plugin-auth
npm run deploy
curl -i http://127.0.0.1:3000/health

curl http://127.0.0.1:3000/health 返回 ok 后，再访问：

https://你的域名/health
https://你的域名/api/user/info

如果本机 /health 正常，但域名还是 502，就检查 Nginx/1Panel 反向代理里的 /api/ 是否代理到：

http://127.0.0.1:3000/api/

如果日志里出现下面这种错误：

Cannot find module '/opt/1panel/www/sites/console.sg65.cn/index/backend/dist/index.js'

说明后端构建产物没有上传完整。进入后端目录先自检：

cd /opt/1panel/www/sites/console.sg65.cn/index/backend
npm run preflight

如果提示缺少 dist/index.js，重新上传发布包里的整个 backend/dist/ 目录，不能只上传 backend/package.json 或 backend/node_modules。

如果日志里出现下面这种错误：

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'express' imported from .../backend/dist/index.js

说明后端依赖没有正确安装，或者 node_modules 是旧的/坏的。进入后端目录，删掉依赖后重新安装：

cd /opt/1panel/www/sites/console.sg65.cn/index/backend
rm -rf node_modules package-lock.json
npm cache verify
npm run deploy
curl -i http://127.0.0.1:3000/health
npx pm2 logs epay-plugin-auth --lines 100 --nostream

如果你的后端目录不是上面这个，把 cd 后面的路径换成实际的 backend 目录。

如果重装依赖后 /health 正常，但之前支付或续费时报：

Unknown column 'order_type' in 'field list'

说明当前数据库还没补上新字段。重启后端后会自动检查数据库；如果日志仍然报这个字段不存在，执行下面的安全补字段 SQL：

mysql -h127.0.0.1 -P3306 -u你的数据库用户名 -p 你的数据库名 -e "ALTER TABLE payment_orders ADD COLUMN order_type ENUM('purchase', 'recharge') NOT NULL DEFAULT 'purchase' COMMENT '订单业务类型：purchase-购买，recharge-充值' AFTER description;"
npx pm2 restart epay-plugin-auth --update-env

如果日志里出现下面这种错误：

CREATE TABLE IF NOT EXISTS `IF` NOT EXISTS `auth_transfer_logs`

说明发布包里的数据库自动更新脚本是旧版本。请重新生成或上传最新发布包，覆盖 backend/dist/ 后再重启：

cd /opt/1panel/www/sites/console.sg65.cn/index/backend
npx pm2 restart epay-plugin-auth --update-env
curl -i http://127.0.0.1:3000/health
npx pm2 logs epay-plugin-auth --lines 100 --nostream

7. 后台登录失败

默认账号是：

admin / 123456

如果密码不对，可以在后端目录执行：

cd /www/wwwroot/epay-plugin-auth/backend
node scripts/reset-admin-password.js

1Panel 如果安装在 /opt：

cd /opt/epay-plugin-auth/backend
node scripts/reset-admin-password.js

8. 修改配置后没有生效

先重启后端：

npx pm2 restart epay-plugin-auth

再清理浏览器缓存后刷新。

9. 系统更新后怎么操作

系统更新按最简单方式做：上传新发布包，覆盖旧文件，然后执行一次一键部署。

第一步：上传并解压新发布包

把新发布包上传到当前程序目录。

宝塔一般是：

/www/wwwroot/epay-plugin-auth

1Panel 一般是：

/opt/epay-plugin-auth

解压后确认目录还是下面这样：

epay-plugin-auth/
├── frontend/
├── backend/
├── database/
├── INSTALL.md
└── README-DEPLOY.md

如果解压后多了一层目录，例如：

epay-plugin-auth/epay-plugin-auth-workspace-1.0.0-xxxx/frontend

就把里面的 frontend、backend、database、INSTALL.md、README-DEPLOY.md 移到当前程序目录，和旧文件同名覆盖。

第二步：覆盖旧文件

在面板文件管理里直接覆盖同名文件即可。

需要覆盖：

frontend/
backend/
database/
INSTALL.md
README-DEPLOY.md

.env 是你自己创建的独立配置文件，发布包里默认没有 backend/.env，所以正常覆盖不会影响数据库账号密码。

第三步：执行一键部署

进入后端目录。

宝塔：

cd /www/wwwroot/epay-plugin-auth/backend
npm run deploy

1Panel：

cd /opt/epay-plugin-auth/backend
npm run deploy

npm run deploy 会重新安装生产依赖、检查发布包、启动或重启 PM2，并在后端启动时自动检查数据库。

系统会自动补齐新增数据表、字段、索引，不需要用户自己导入 migrations。删除表、删除字段、字段收窄这类可能影响已有数据的变更不会自动执行，需要按版本说明单独处理。

可以查看后端日志确认：

npx pm2 logs epay-plugin-auth --lines 50

看到下面类似日志就说明自动更新执行过了：

正在检查数据库更新
数据库结构检查完成
数据库更新检查完成

检查后端：

curl http://127.0.0.1:3000/health

返回 ok 就正常。

第五步：刷新浏览器后测试

浏览器按：

Ctrl + F5

或者退出后台重新登录一次。

最后测试：

首页能打开
后台能登录
https://你的域名/health 正常返回

如果这次更新说明里提到新增了某些系统配置，登录后台进入系统配置搜索确认即可。例如极验配置可以搜索：

geetest

10. 执行 `apt install npm` 出现紫色服务重启界面

这个界面一般长这样：

Daemons using outdated libraries
Which services should be restarted?

这不是项目报错，也不是安装失败。它是系统提示有些服务用了旧版本库文件，需要重启服务。

处理方式：

保持默认勾选
按 Tab 选到 <Ok>
按 Enter
回到命令行后继续执行教程后面的步骤

另外，不建议执行 apt install npm。如果你是按本教程安装 Node.js，执行下面这个就够了：

apt install -y nodejs

安装后检查：

node -v
npm -v

只要 node -v 显示 v20.x.x 或更高版本，就可以继续。

11. 安装依赖时提示 `EBADENGINE`，或者 PM2 online 但 `/health` 连接不上

如果你看到类似：

npm WARN EBADENGINE Unsupported engine
required: { node: '>=20.0.0' }
current: { node: 'v12.22.9', npm: '8.5.1' }

说明服务器装的是 Ubuntu 自带的 Node 12，不是 Node.js 20。这个版本不能运行本项目。

直接按下面命令修复：

npx pm2 delete epay-plugin-auth || true
apt remove -y npm nodejs libnode-dev nodejs-doc
apt autoremove -y
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs
node -v
npm -v

确认 node -v 显示 v20.x.x 后，重新执行一键部署：

cd /opt/1panel/www/sites/console.sg65.cn/index/backend
rm -rf node_modules package-lock.json
npm run deploy
curl http://127.0.0.1:3000/health

如果你的后端目录不是上面这个，把 cd 后面的路径换成你实际的 backend 目录。

12. 更新前想先备份怎么办

正常更新可以直接覆盖文件。想更稳一点，可以先备份数据库和程序目录。

宝塔数据库备份：

数据库 -> 你的数据库 -> 备份

1Panel 数据库备份：

数据库 -> MySQL -> 你的数据库 -> 备份

备份程序目录：

cp -a /www/wwwroot/epay-plugin-auth /www/wwwroot/epay-plugin-auth-bak-$(date +%Y%m%d%H%M%S)

1Panel 如果安装在 /opt：

cp -a /opt/epay-plugin-auth /opt/epay-plugin-auth-bak-$(date +%Y%m%d%H%M%S)

13. 覆盖更新后 `.env` 没了怎么办

正常发布包没有 backend/.env，一般不会覆盖掉它。

如果你误删了 .env，进入后端目录：

cd /www/wwwroot/epay-plugin-auth/backend
cp .env.example .env

1Panel 如果安装在 /opt：

cd /opt/epay-plugin-auth/backend
cp .env.example .env

然后重新填写数据库配置：

DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=数据库用户名
DB_PASSWORD=数据库密码
DB_NAME=数据库名

保存后重启：

npx pm2 restart epay-plugin-auth

六、安装完成检查清单

安装完成后，逐项检查：

https://你的域名 能打开
https://你的域名/health 返回 ok
能用 admin / 123456 登录
登录后已修改管理员密码
系统配置里的 api_basic_url 已改成正式域名
Nginx 已配置 /api/
Nginx 已配置 /ws/
Nginx 已配置 /uploads/
已开启 HTTPS

一、准备材料

二、最简安装流程

三、宝塔面板安装

1. 安装运行环境

2. 创建网站

3. 上传并解压发布包

4. 创建数据库

5. 配置后端 .env

6. 一键部署后端

7. 配置 Nginx

8. 配置 HTTPS

9. 访问后台

10. 设置站点基础地址

四、1Panel 面板安装

1. 安装应用

2. 创建网站

3. 上传发布包

4. 创建数据库

5. 配置后端环境变量

6. 一键部署后端

7. 配置网站反向代理

8. 申请 HTTPS

9. 登录后台

五、常见问题

1. 页面能打开，但登录接口 404

2. 页面刷新后 404

3. 保存 Nginx 时提示 duplicate location "/"

4. 聊天或在线状态不正常

5. 后端启动失败，提示数据库连接失败

6. 页面请求 /api/user/info 返回 502 Bad Gateway

7. 后台登录失败

8. 修改配置后没有生效

9. 系统更新后怎么操作

第一步：上传并解压新发布包

第二步：覆盖旧文件

第三步：执行一键部署

第五步：刷新浏览器后测试

10. 执行 apt install npm 出现紫色服务重启界面

11. 安装依赖时提示 EBADENGINE，或者 PM2 online 但 /health 连接不上

12. 更新前想先备份怎么办

13. 覆盖更新后 .env 没了怎么办

六、安装完成检查清单

相关文章

微信

晨晖时光资源网

QQ交流群

5. 配置后端 `.env`

3. 保存 Nginx 时提示 `duplicate location "/"`

6. 页面请求 `/api/user/info` 返回 502 Bad Gateway

10. 执行 `apt install npm` 出现紫色服务重启界面

11. 安装依赖时提示 `EBADENGINE`，或者 PM2 online 但 `/health` 连接不上

13. 覆盖更新后 `.env` 没了怎么办