星屿客服系统程序部署教程

本文用于部署星屿客服系统，包含：

Node.js 后端 API：chatapi.iyqy.cn
管理后台：chatadmin.iyqy.cn
用户聊天端：chat.iyqy.cn
MySQL 数据库
Nginx 反向代理与 HTTPS
WebSocket 实时通信
PM2 进程守护

重要提示： 服务器 Node.js 版本必须为 22.22.3，版本不一致可能出现字节码无法加载、服务启动失败等问题。

一、域名规划

二、前置条件

部署前请确认服务器已具备以下环境：

宝塔面板已安装并可以正常登录
Node.js 22.22.3 已安装
MySQL 8.0 已安装并正常运行
Nginx 已安装并正常运行
域名已解析到当前服务器公网 IP
服务器安全组已放行 80、443 端口
不需要对公网开放 3003、3306、6379 端口

推荐服务器配置：

三、数据库配置

1. 创建数据库

用宝塔安装教程时创建的数据库账户密码。

数据库仅允许本机访问即可，不建议开启公网访问。

2. 记录数据库连接地址

后端 .env 文件需要填写：

DATABASE_URL="mysql://chatbox:你的数据库密码@127.0.0.1:3306/chatbox"

如果数据库密码中包含 @、#、%、& 等特殊字符，可能需要进行 URL 编码。为了减少配置问题，建议数据库密码尽量使用字母、数字和常规符号组合。

四、部署后端 API（chatapi.iyqy.cn）

1. 上传后端代码

将发布包中的 server 目录上传到：

/www/wwwroot/chatapi.iyqy.cn/

最终目录示例：

/www/wwwroot/chatapi.iyqy.cn/
├── dist/
├── prisma/
├── node_modules/
├── uploads/
├── package.json
├── package-lock.json
├── .env
└── ...

2. 安装 Node.js 22.22.3

宝塔面板进入：

网站 → Node 项目 → Node 版本管理器

找到：

22.22.3

如果版本列表中没有，先点击：

更新版本列表

然后安装 Node.js 22.22.3，并切换为该版本。

在宝塔终端执行：

node -v
npm -v

确认 Node.js 输出为：

v22.22.3

必须是 v22.22.3，不要使用 22.22.2、22.23.0 或其他 Node.js 大版本、补丁版本。

3. 安装后端依赖

进入宝塔终端，执行：

cd /www/wwwroot/chatapi.iyqy.cn
npm install

如果发布包已经带有 package-lock.json，推荐使用：

npm ci

npm ci 会严格按照锁定版本安装依赖，更适合正式服务器部署。

4. 配置环境变量

复制环境变量模板：

cp .env.example .env

编辑 .env：

vim .env

填写示例：

PORT=3003
NODE_ENV=production

DATABASE_URL="mysql://chatbox:你的数据库密码@127.0.0.1:3306/chatbox"

JWT_SECRET=请填写一段随机字符串
JWT_REFRESH_SECRET=请填写另一段随机字符串

生成随机密钥：

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

执行两次，分别填入：

JWT_SECRET=
JWT_REFRESH_SECRET=

不要使用以下简单值：

JWT_SECRET=123456
JWT_SECRET=admin
JWT_SECRET=chatbox

5. 初始化数据库

在后端目录执行：

cd /www/wwwroot/chatapi.iyqy.cn

npx prisma generate
npx prisma db push
npm run db:seed

说明：

npx prisma generate    生成 Prisma Client
npx prisma db push     创建或同步数据库表结构
npm run db:seed        写入默认账号、权限、菜单等初始数据

首次部署必须执行这三条命令。

6. 构建后端项目

执行：

npm run build

构建成功后应生成：

dist/

通常主入口文件为：

dist/main.js

7. 创建上传目录并设置权限

执行：

mkdir -p /www/wwwroot/chatapi.iyqy.cn/uploads
chmod -R 755 /www/wwwroot/chatapi.iyqy.cn/uploads

如系统使用 www 用户运行 Nginx 或 Node 服务，可以执行：

chown -R www:www /www/wwwroot/chatapi.iyqy.cn/uploads

如果文件上传时报“无写入权限”“Permission denied”，优先检查此目录权限。

8. 使用 PM2 启动后端

安装 PM2：

npm install -g pm2

启动 API：

cd /www/wwwroot/chatapi.iyqy.cn

pm2 start dist/main.js \
  --name chatapi \
  --max-memory-restart 512M

查看状态：

pm2 status

正常应显示：

chatapi    online

查看日志：

pm2 logs chatapi

后续重启查看可在网站-Node管理-pm2监控查看

访问自己的后端网址

返回 401 Unauthorized 或未授权提示是正常现象，说明 API 服务已正常启动。

9. 设置 PM2 开机自启

执行：

pm2 save
pm2 startup

执行 pm2 startup 后，终端会生成一条新的命令。

复制并执行终端返回的完整命令后，再执行：

pm2 save

安装日志轮转模块，避免长期运行后日志占满磁盘：

pm2 install pm2-logrotate

建议配置日志保留数量：

pm2 set pm2-logrotate:max_size 20M
pm2 set pm2-logrotate:retain 14
pm2 set pm2-logrotate:compress true

五、配置 API 域名反向代理

1. 添加 API 站点

进入宝塔面板：

网站 → 添加站点

填写：

域名：chatapi.iyqy.cn
根目录：/www/wwwroot/chatapi.iyqy.cn
PHP版本：纯静态
数据库：不创建

2. 添加反向代理

进入：

网站 → chatapi.iyqy.cn → 反向代理 → 添加反向代理

填写：

代理名称：chatapi
目标 URL：http://127.0.0.1:3003
发送域名：$host

保存后，找到刚创建的反向代理，点击右侧：

配置文件

替换为以下内容：

location ^~ / {
    proxy_pass http://127.0.0.1:3003;
    proxy_http_version 1.1;

    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;

    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    proxy_read_timeout 86400;
    proxy_send_timeout 86400;

    client_max_body_size 50m;

    add_header Cache-Control "no-store, no-cache, must-revalidate" always;
}

保存并重载 Nginx。

不要在“站点主配置文件”中另外再添加 location /，否则会与宝塔自动生成的反向代理规则冲突，并出现 duplicate location 错误。

3. WebSocket 配置说明

上面的配置已同时支持：

普通 HTTP 接口请求
WebSocket 实时消息
Socket.IO 长连接
在线状态同步
正在输入状态
客服端和用户端即时收发消息

proxy_read_timeout 86400 用于避免 WebSocket 长连接过早断开。

4. 申请 SSL 证书

进入：

网站 → chatapi.iyqy.cn → SSL → Let's Encrypt

申请成功后开启：

强制 HTTPS

API 最终地址：

https://chatapi.iyqy.cn

六、部署管理后台（chatadmin.iyqy.cn）

1. 本地构建项目

进入管理后台项目目录：

cd admin-console
npm install
npm run build

构建完成后会生成：

admin-console/dist/

2. 上传构建文件

将 admin-console/dist 文件夹中的全部内容上传到：

/www/wwwroot/chatadmin.iyqy.cn/

注意是上传 dist 内部文件，而不是把整个 dist 文件夹嵌套上传。

正确结构：

/www/wwwroot/chatadmin.iyqy.cn/
├── assets/
├── index.html
└── favicon.ico

3. 添加后台站点

宝塔面板：

网站 → 添加站点

填写：

域名：chatadmin.iyqy.cn
根目录：/www/wwwroot/chatadmin.iyqy.cn
PHP版本：纯静态
数据库：不创建

4. 配置 Vue SPA 路由

进入：

网站 → chatadmin.iyqy.cn → 配置文件

在站点配置的 server 区块内添加：

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

保存并重载 Nginx。

此配置用于支持 Vue Router 的 history 路由模式，避免刷新页面后出现：

404 Not Found

5. 申请 SSL 证书

进入：

网站 → chatadmin.iyqy.cn → SSL → Let's Encrypt

申请证书后开启：

强制 HTTPS

后台访问地址：

https://chatadmin.iyqy.cn

七、部署用户端（chat.iyqy.cn）

1. 本地构建 UniApp H5

进入用户端项目目录：

cd ltclient-app
npm install
npm run build:h5

构建产物默认目录：

ltclient-app/unpackage/dist/build/h5/

2. 上传 H5 文件

将以下目录中的全部文件上传至：

ltclient-app/unpackage/dist/build/h5/

目标目录：

/www/wwwroot/chat.iyqy.cn/

最终目录应类似：

/www/wwwroot/chat.iyqy.cn/
├── static/
├── assets/
├── index.html
└── manifest.json

3. 添加用户端站点

进入宝塔：

网站 → 添加站点

填写：

域名：chat.iyqy.cn
根目录：/www/wwwroot/chat.iyqy.cn
PHP版本：纯静态
数据库：不创建

4. 配置 H5 路由

进入：

网站 → chat.iyqy.cn → 配置文件

添加：

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

保存并重载 Nginx。

5. 申请 SSL 证书

进入：

网站 → chat.iyqy.cn → SSL → Let's Encrypt

申请成功后开启：

强制 HTTPS

用户端访问地址：

https://chat.iyqy.cn

八、前端发布前检查

管理后台和用户端打包前，请确认接口地址已改为正式 API 域名：

https://chatapi.iyqy.cn

不要保留以下本地开发地址：

http://localhost:3003
http://127.0.0.1:3003
ws://localhost:3003

生产环境 WebSocket 应使用：

wss://chatapi.iyqy.cn

如果前端项目只配置 API Base URL，且 WebSocket 由程序自动识别协议，也可以只填写：

https://chatapi.iyqy.cn

九、验证部署

1. 检查 API

服务器终端执行：

curl -I https://chatapi.iyqy.cn/api/v1/admin/auth/info

HTTP/2 401

或：

HTTP/1.1 401 Unauthorized

说明 API 反向代理和后端服务正常。

2. 检查 PM2 状态

pm2 status

确认：

chatapi    online

3. 检查管理后台

浏览器访问：

https://chatadmin.iyqy.cn

应正常显示管理后台登录页。

4. 检查用户端

浏览器访问：

https://chat.iyqy.cn

应正常显示在线客服聊天界面。

5. 测试默认账号

首次部署并成功执行种子数据后，可使用以下账号测试：

首次登录后，请立即修改默认管理员账号密码，避免服务器暴露后被他人登录。

十、常用运维命令

# 查看服务状态
pm2 status

# 查看实时日志
pm2 logs chatapi

# 查看最近 100 行日志
pm2 logs chatapi --lines 100

# 重启服务
pm2 restart chatapi

# 停止服务
pm2 stop chatapi

# 删除服务
pm2 delete chatapi

# 查看端口是否监听
ss -lntp | grep 3003

# 查看 Nginx 配置是否正确
nginx -t

# 重载 Nginx
nginx -s reload

十一、后端更新部署流程

更新代码后，进入后端目录执行：

cd /www/wwwroot/chatapi.iyqy.cn

git pull
npm install
npm run build
pm2 restart chatapi

如果不是 Git 部署，直接重新上传后端文件，再执行：

cd /www/wwwroot/chatapi.iyqy.cn

npm install
npm run build
pm2 restart chatapi

如数据库结构有调整，再执行：

npx prisma generate
npx prisma db push
pm2 restart chatapi

更新完成后查看日志：

pm2 logs chatapi --lines 100

确认没有数据库连接、Redis、环境变量、端口占用等报错。

十二、常见问题

1. 页面显示 502 Bad Gateway

执行：

pm2 status
pm2 logs chatapi
ss -lntp | grep 3003

常见原因：

Node.js 服务未启动。
Node.js 版本不是 22.22.3，Bytenode 字节码无法加载。
API 实际监听端口不是 3003。
.env 文件配置错误。
MySQL 无法连接。
构建文件 dist/main.js 不存在。
Nginx 反向代理地址填写错误。

2. 聊天消息无法实时刷新

优先检查：

1. chatapi.iyqy.cn 是否已申请 SSL。
2. Nginx 反向代理是否包含 Upgrade 和 Connection 配置。
3. 前端 WebSocket 地址是否为 wss://chatapi.iyqy.cn。
4. Cloudflare 或 CDN 是否缓存了 API、Socket、WebSocket 请求。

API 和 WebSocket 路径不建议缓存，例如：

/api/
/socket.io/
/ws/

如果使用 Cloudflare，建议先将 chatapi.iyqy.cn 设置为“仅 DNS”，确认系统正常后再单独配置 WebSocket 和缓存规则。

3. 文件上传失败

检查上传目录：

ls -ld /www/wwwroot/chatapi.iyqy.cn/uploads

重新设置权限：

mkdir -p /www/wwwroot/chatapi.iyqy.cn/uploads
chown -R www:www /www/wwwroot/chatapi.iyqy.cn/uploads
chmod -R 755 /www/wwwroot/chatapi.iyqy.cn/uploads

同时确认 API 反向代理配置中存在：

client_max_body_size 50m;

需要上传更大文件时，可改为：

client_max_body_size 200m;

4. 数据库连接失败

检查 .env：

DATABASE_URL="mysql://chatbox:你的数据库密码@127.0.0.1:3306/chatbox"

检查 MySQL 状态：

systemctl status mysqld

部分系统服务名可能是：

systemctl status mysql

修改数据库密码后，需要同步修改 .env，再重启 API：

pm2 restart chatapi

5. 宝塔配置保存后提示 duplicate location

不要同时在以下两个位置都添加：

location / { ... }

正确做法：

API 域名：在“反向代理 → 配置文件”中维护代理规则。
管理后台、用户端静态站点：在“站点配置文件”中配置 SPA 的 try_files 规则。

十三、安全建议

3003、3306、6379 不对外开放。
只放行 80、443、SSH 端口和宝塔面板端口。
宝塔面板不要长期使用默认 8888 端口。
修改宝塔后台默认用户名和密码。
给宝塔设置安全入口和授权 IP。
修改默认管理员账号 admin / admin123。
定期备份 MySQL 数据库和 uploads 文件目录。
.env 文件不得上传到 Git 仓库。
chatapi.iyqy.cn 不建议走缓存型 CDN。
定期检查 PM2 日志和服务器磁盘空间。

十四、最终部署结构

/www/wwwroot/
├── chatapi.iyqy.cn/          Node.js / NestJS 后端
│   ├── dist/
│   ├── prisma/
│   ├── uploads/
│   ├── .env
│   └── package.json
│
├── chatadmin.iyqy.cn/        Vue 3 管理后台静态文件
│   ├── assets/
│   └── index.html
│
└── chat.iyqy.cn/             UniApp H5 用户端静态文件
    ├── assets/
    ├── static/
    └── index.html

最终访问关系：

用户访问：
https://chat.iyqy.cn

管理后台访问：
https://chatadmin.iyqy.cn

前端 API / WebSocket 请求：
https://chatapi.iyqy.cn
wss://chatapi.iyqy.cn

Nginx：
chatapi.iyqy.cn → 127.0.0.1:3003

后端：
Node.js 22.22.3 + NestJS + PM2

数据层：
MySQL 8.0

知识库

程序部署教程

星屿客服系统程序部署教程

一、域名规划

二、前置条件

三、数据库配置

1. 创建数据库

2. 记录数据库连接地址

四、部署后端 API（chatapi.iyqy.cn）

1. 上传后端代码

2. 安装 Node.js 22.22.3

3. 安装后端依赖

4. 配置环境变量

5. 初始化数据库

6. 构建后端项目

7. 创建上传目录并设置权限

8. 使用 PM2 启动后端

9. 设置 PM2 开机自启

五、配置 API 域名反向代理

1. 添加 API 站点

2. 添加反向代理

3. WebSocket 配置说明

4. 申请 SSL 证书

六、部署管理后台（chatadmin.iyqy.cn）

1. 本地构建项目

2. 上传构建文件

3. 添加后台站点

4. 配置 Vue SPA 路由

5. 申请 SSL 证书

七、部署用户端（chat.iyqy.cn）

1. 本地构建 UniApp H5

2. 上传 H5 文件

3. 添加用户端站点

4. 配置 H5 路由

5. 申请 SSL 证书

八、前端发布前检查

九、验证部署

1. 检查 API

2. 检查 PM2 状态

3. 检查管理后台

4. 检查用户端

5. 测试默认账号

十、常用运维命令

十一、后端更新部署流程

十二、常见问题

1. 页面显示 502 Bad Gateway

2. 聊天消息无法实时刷新

3. 文件上传失败

4. 数据库连接失败

5. 宝塔配置保存后提示 duplicate location

十三、安全建议

十四、最终部署结构