心域网络
DOCS

知识库

产品文档与帮助中心

星屿客服使用教程

其他问题

星屿客服系统常见问题

本教程用于处理星屿客服系统安装、部署、运行及使用过程中常见的问题。

系统部署结构：

API 后端：https://chatapi.你的域名
管理后台：https://chatadmin.你的域名
用户端：https://chat.你的域名

后端端口：3003
Node.js 版本：22.22.3
数据库：MySQL 8.0
进程管理：PM2
重要：后端 Node.js 必须使用 22.22.3，不要随意升级或更换版本。

一、页面打不开或显示 502 Bad Gateway

问题表现

访问以下地址时出现：

502 Bad Gateway

https://chatapi.你的域名

排查步骤

进入宝塔终端，执行：

pm2 status

正常应看到：

chatapi    online

如果不是 online，查看报错日志：

pm2 logs chatapi --lines 100

然后检查后端端口是否正常监听：

ss -lntp | grep 3003

正常会看到 Node.js 正在监听 3003 端口。

常见原因

  • PM2 后端服务没有启动
  • 后端启动后报错退出
  • Node.js 版本不是 22.22.3
  • .env 数据库配置错误
  • MySQL 未启动
  • Nginx 反向代理目标端口填写错误
  • dist/main.js 文件不存在

处理方法

进入后端目录重新启动：

cd /www/wwwroot/chat/chatapi.iyqy.cn

pm2 restart chatapi

如果 PM2 中没有服务，则执行：

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

二、后端服务启动失败

问题表现

执行：

pm2 status

显示：

chatapi    errored

或频繁重启。

处理方法

查看具体错误：

pm2 logs chatapi --lines 100

重点检查以下内容：

node -v

必须显示：

v22.22.3

检查后端文件是否存在：

cd /www/wwwroot/chat/chatapi.iyqy.cn

ls -lah dist/main.js

检查环境变量文件：

ls -lah .env

重新安装依赖并生成 Prisma：

npm ci
npx prisma generate
pm2 restart chatapi
如果没有 package-lock.json，把 npm ci 改为 npm install。

三、数据库连接失败

问题表现

PM2 日志中出现：

Database connection failed
Access denied for user
Can't reach database server
PrismaClientInitializationError

排查方法

进入后端目录：

cd /www/wwwroot/chat/chatapi.iyqy.cn
vim .env

检查数据库配置：

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

确认：

  • 数据库名是否正确
  • 用户名是否正确
  • 密码是否正确
  • 数据库服务是否已启动
  • 密码中是否存在特殊字符

检查 MySQL 服务：

systemctl status mysql

部分服务器可使用：

systemctl status mysqld

修改 .env 后重启：

pm2 restart chatapi
数据库密码包含 @、#、%、& 等字符时，可能导致连接地址识别错误。建议数据库密码使用大小写字母、数字和普通符号组合。

四、管理后台或用户端刷新后显示 404

问题表现

后台或用户端首次访问正常，但刷新页面后出现：

404 Not Found

原因

Vue 或 UniApp H5 使用了前端路由，Nginx 没有配置 SPA 回退规则。

处理方法

进入宝塔：

网站 → chatadmin.你的域名 → 配置文件

在站点配置中加入：

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

用户端 chat.你的域名 也添加同样配置：

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

保存后重载 Nginx。

五、聊天消息不能实时刷新

问题表现

  • 用户发送消息后，客服后台没有立即收到
  • 客服回复后，用户端没有立即显示
  • 在线状态不更新
  • 正在输入状态不显示
  • 刷新页面后才看到新消息

排查步骤

确认 API 站点反向代理已配置 WebSocket。

进入：

网站 → chatapi.你的域名 → 反向代理 → 配置文件

确认存在以下内容：

proxy_http_version 1.1;

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

proxy_read_timeout 86400;
proxy_send_timeout 86400;

完整示例：

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;
}

同时确认：

  • API 域名已配置 SSL
  • 用户端、后台使用 HTTPS
  • WebSocket 使用 wss://
  • API 域名没有被 CDN 缓存
  • 前端接口地址不是 localhost 或 127.0.0.1

生产环境应使用：

https://chatapi.你的域名
wss://chatapi.你的域名

六、图片或文件上传失败

问题表现

  • 上传图片失败
  • 上传文件提示服务器错误
  • 文件上传后无法打开
  • 报错 Permission denied
  • 大文件无法上传

处理方法

检查上传目录：

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

重新设置目录权限：

mkdir -p /www/wwwroot/chat/chatapi.iyqy.cn/uploads

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

同时检查 API 反向代理是否存在：

client_max_body_size 50m;

需要上传更大文件时可调整为：

client_max_body_size 200m;

保存后重载 Nginx。

七、图片或附件以前能打开，现在打不开

常见原因

  • uploads 文件夹被删除
  • 文件迁移时漏复制 uploads
  • 域名变更后旧文件地址失效
  • Nginx 未正确转发 API 请求
  • 文件权限被修改

处理方法

确认上传目录仍存在：

ls -lah /www/wwwroot/chat/chatapi.iyqy.cn/uploads

如果服务器迁移过，请确认已恢复：

/www/wwwroot/chat/chatapi.iyqy.cn/uploads/

然后重新设置权限：

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

八、浏览器提示不安全或 HTTPS 无法访问

问题表现

  • 浏览器显示“不安全”
  • SSL 证书申请失败
  • HTTPS 访问打不开
  • WebSocket 无法连接

处理方法

确认域名已解析到当前服务器公网 IP。

然后进入宝塔：

网站 → 对应域名 → SSL → Let's Encrypt

分别为以下域名申请证书：

chatapi.你的域名
chatadmin.你的域名
chat.你的域名

申请成功后开启：

强制 HTTPS

注意：

  • 域名必须先解析生效
  • 服务器安全组必须放行 80 和 443
  • CDN 代理可能导致证书申请失败，可暂时关闭代理后申请

九、SSL 证书申请失败

常见原因

  • 域名没有解析到当前服务器
  • 域名解析尚未生效
  • 80 端口未放行
  • 域名被 CDN 代理
  • 域名已有错误的网站配置
  • DNS 记录填写错误

排查方法

确认域名解析是否正确：

ping chatapi.你的域名

检查 Nginx 是否正常：

nginx -t

确认 80 端口已在云服务器安全组放行。

如果使用 Cloudflare，申请证书前建议先将域名记录设置为：

仅 DNS

证书申请成功后，再按需开启代理。

十、服务器重启后系统无法自动运行

问题表现

服务器重启后：

  • 管理后台可打开
  • 用户端可打开
  • API 显示 502
  • 聊天无法发送

处理方法

进入终端执行：

pm2 status

如果 chatapi 未启动，执行：

cd /www/wwwroot/chat/chatapi.iyqy.cn

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

然后设置开机自启：

pm2 startup

终端会生成一条命令，复制并执行该命令。

最后执行：

pm2 save

十一、PM2 日志文件太大，服务器磁盘空间不足

问题表现

  • 服务器磁盘占满
  • PM2 日志越来越大
  • 系统提示磁盘空间不足
  • 后端无法写入日志或上传文件

处理方法

安装 PM2 日志轮转：

pm2 install pm2-logrotate

设置日志规则：

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

查看日志目录大小：

du -sh ~/.pm2/logs

需要清空当前日志时：

pm2 flush
pm2 flush 会清空当前日志，但不会停止服务。

十二、接口访问出现跨域错误

问题表现

浏览器控制台出现：

CORS policy
Access-Control-Allow-Origin
跨域请求被拦截

常见原因

前端域名未加入 API 后端允许访问的域名列表。

检查后端 .env 或项目 CORS 配置，确保包含：

https://chat.你的域名
https://chatadmin.你的域名

修改后重启后端：

pm2 restart chatapi

十三、后台无法登录或登录后自动退出

常见原因

  • 数据库连接异常
  • JWT 密钥被修改
  • 服务器时间不正确
  • 浏览器缓存旧版本前端文件
  • HTTPS、Cookie 或跨域配置异常

处理方法

先确认后端日志没有数据库报错：

pm2 logs chatapi --lines 100

检查 .env 中 JWT 配置是否被修改：

JWT_SECRET=
JWT_REFRESH_SECRET=

迁移服务器时建议保留原来的 JWT 密钥。

清理浏览器缓存或使用无痕窗口重新登录。

检查服务器时间：

date

十四、更新系统后页面还是旧版本

常见原因

  • 浏览器缓存未清理
  • CDN 缓存未清理
  • 上传文件放错目录
  • 新版前端没有覆盖旧文件

处理方法

确认管理后台文件上传位置：

/www/wwwroot/chat/chatadmin.iyqy.cn/

确认用户端文件上传位置：

/www/wwwroot/chat/chat.iyqy.cn/

上传时应覆盖旧文件。

然后：

  • 使用 Ctrl + F5 强制刷新浏览器
  • 清理浏览器缓存
  • 使用无痕窗口访问
  • 清理 CDN 缓存
  • 确认前端构建后的接口地址正确

十五、更新后端代码后无法启动

推荐更新流程

进入后端目录：

cd /www/wwwroot/chat/chatapi.iyqy.cn

执行：

npm install
npm run build
npx prisma generate
pm2 restart chatapi

查看日志：

pm2 logs chatapi --lines 100

如果数据库表结构有更新，再执行：

npx prisma db push
pm2 restart chatapi
正常更新不要执行 npm run db:seed，避免重复创建初始数据。

十六、宝塔保存配置时报 duplicate location

问题表现

保存 Nginx 配置时报错：

duplicate location "/"

原因

同一个网站配置中重复添加了：

location / {
}

处理方法

  • API 站点：只在“反向代理 → 配置文件”中配置 location
  • 管理后台和用户端：只在“网站 → 配置文件”中配置 SPA 路由
  • 不要重复添加多个 location /

API 站点不要额外添加：

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

十七、CDN 或 Cloudflare 开启后聊天不刷新

问题表现

不开 CDN 时聊天正常，开启 CDN 后：

  • 消息不实时更新
  • WebSocket 连接失败
  • 接口偶尔 405、502、缓存旧数据
  • 用户端收不到客服消息

处理方法

建议 API 域名：

chatapi.你的域名

先不要开启 CDN 代理，设置为：

仅 DNS

不要缓存以下路径：

/api/
/socket.io/
/ws/
/uploads/

客服系统的 API、WebSocket、实时消息接口不适合走普通静态缓存规则。

十八、服务器迁移后图片、附件或登录异常

迁移服务器后请确认：

1. 已导入 chatbox 数据库
2. 已恢复 /www/wwwroot/chat/ 整体文件夹
3. uploads 文件夹已完整恢复
4. .env 中数据库密码已改为新服务器密码
5. JWT_SECRET 和 JWT_REFRESH_SECRET 没有随意修改
6. Node.js 版本仍然是 22.22.3
7. 后端服务已重新通过 PM2 启动
8. 域名已切换到新服务器
9. SSL 已重新配置或恢复

迁移完成后建议完整测试：

登录后台
用户发消息
客服回复消息
发送图片
发送文件
查看历史聊天
测试 AI 自动回复
测试转人工

十九、联系客服时需要提供什么信息

遇到无法自行解决的问题，请提供以下内容，方便快速排查：

1. 问题描述
2. 出现问题的具体时间
3. 出问题的网址
4. 浏览器报错截图
5. 宝塔 PM2 状态截图
6. PM2 日志截图
7. 是否刚更新、迁移、改域名或改过配置

获取日志命令：

pm2 logs chatapi --lines 100

不要直接发送以下敏感信息：

数据库密码
.env 完整文件
JWT_SECRET
JWT_REFRESH_SECRET
AI API Key
服务器 root 密码
宝塔面板密码

如客服确实需要排查配置，可先将密码、密钥打码后再发送截图。