知识库
产品文档与帮助中心
程序迁移教程
星屿客服系统备份与迁移教程
本文用于将已部署好的星屿客服系统，从旧服务器迁移到新服务器，或在重装服务器前备份重要数据。
本教程按以下实际部署结构编写：
/www/wwwroot/chat/ ├── chatapi.iyqy.cn/ 后端 API 程序 ├── chatadmin.iyqy.cn/ 管理后台静态文件 └── chat.iyqy.cn/ 用户聊天端静态文件
系统使用：
Node.js：22.22.3 MySQL：8.0 Nginx：宝塔安装 进程管理：PM2 数据库：chatbox 后端端口：3003
重要提示： 新服务器 Node.js 必须安装 22.22.3。版本不一致可能导致后端字节码无法加载，出现启动失败。
一、需要备份哪些内容
迁移客服系统时，至少要备份以下两项：
内容是否必须说明MySQL 数据库 chatbox | 必须 | 包含用户、商户、客服、聊天记录、知识库、系统配置等数据
/www/wwwroot/chat/ 文件夹 | 必须 | 包含后端、前端、上传文件、.env 配置等
chat 文件夹中通常包括：
chatapi.iyqy.cn/ ├── dist/ ├── prisma/ ├── uploads/ ├── .env ├── package.json └── package-lock.json chatadmin.iyqy.cn/ ├── assets/ └── index.html chat.iyqy.cn/ ├── assets/ ├── static/ └── index.html
数据库和 chat 文件夹缺一不可。
只备份数据库会导致图片、文件附件丢失；只备份程序文件会导致用户、商户、聊天记录等数据丢失。
二、迁移前准备
建议选择用户访问量较低的时间进行迁移。
为了避免备份期间仍有新的聊天记录写入数据库，先停止旧服务器后端服务。
进入旧服务器宝塔终端，执行：
pm2 stop chatapi
检查服务状态：
pm2 status
正常会看到：
chatapi stopped
此时管理后台和用户端页面可能仍能打开，但无法正常发送和接收新消息，适合开始最终备份。
三、备份旧服务器数据库
1. 宝塔面板备份数据库
进入旧服务器宝塔面板：
数据库 → 找到 chatbox → 备份
点击：
备份数据库
等待备份完成。
宝塔通常会生成一个 .sql 数据库文件，常见目录为：
/www/backup/database/
或：
/www/backup/mysql/
文件名称可能类似：
chatbox_2026-07-03_120000.sql
将这个数据库备份文件下载到电脑保存。
2. 确认备份文件正常
在宝塔文件管理器中确认数据库备份文件不是 0B。
例如：
chatbox_2026-07-03_120000.sql 大小：5MB、20MB、100MB 等
只要不是 0B，通常说明数据库备份已成功。
四、备份整体程序文件
首次安装时，客服系统程序统一放在：
/www/wwwroot/chat/
该目录已经包含：
后端 API 程序 管理后台静态文件 用户端 H5 静态文件 上传图片和附件 .env 配置文件
因此迁移时直接压缩整个 chat 文件夹即可。
1. 在宝塔文件管理器中压缩
进入宝塔：
文件 → /www/wwwroot/
找到：
chat
选中 chat 文件夹后，点击：
压缩
压缩格式选择：
tar.gz
压缩完成后会生成类似文件：
chat.tar.gz
建议放到：
/www/backup/
最终例如：
/www/backup/chat.tar.gz
2. 使用终端压缩
也可以在宝塔终端执行：
mkdir -p /www/backup cd /www/wwwroot tar -czf /www/backup/chat.tar.gz chat
压缩完成后检查：
ls -lh /www/backup/chat.tar.gz
只要文件不是 0B，说明压缩成功。
五、下载备份到本地电脑
建议不要只把备份留在旧服务器。
至少下载以下两个文件：
数据库备份文件：chatbox_xxx.sql 程序备份文件：chat.tar.gz
下载方式：
宝塔面板 → 文件
分别进入：
数据库备份所在目录 /www/backup/
下载：
chatbox_xxx.sql chat.tar.gz
建议电脑本地保存一份，同时再上传一份到网盘、对象存储或另一台服务器。
六、新服务器准备
在新服务器按《星屿客服系统宝塔部署教程》先完成基础环境安装：
宝塔面板 Nginx MySQL 8.0 Node.js 22.22.3 PM2
新服务器必须确认：
node -v
输出必须为：
v22.22.3
然后在宝塔中先添加三个站点：
chatapi.iyqy.cn chatadmin.iyqy.cn chat.iyqy.cn
站点根目录建议设置为：
/www/wwwroot/chat/chatapi.iyqy.cn /www/wwwroot/chat/chatadmin.iyqy.cn /www/wwwroot/chat/chat.iyqy.cn
先创建站点是为了让宝塔自动生成网站配置。后面恢复程序文件后，再配置反向代理、伪静态和 SSL。
七、恢复整体程序文件
将电脑中的：
chat.tar.gz
上传到新服务器：
/www/wwwroot/
上传后目录类似：
/www/wwwroot/chat.tar.gz
进入宝塔终端，执行：
cd /www/wwwroot tar -xzf chat.tar.gz
解压后应自动得到：
/www/wwwroot/chat/
检查目录：
ls -lah /www/wwwroot/chat/
应能看到：
chatapi.iyqy.cn chatadmin.iyqy.cn chat.iyqy.cn
八、恢复数据库
1. 新服务器创建数据库
进入新服务器宝塔：
数据库 → 添加数据库
数据库信息建议和旧服务器保持一致：
数据库名：chatbox 用户名：chatbox 密码：使用旧密码，或设置新密码 访问权限：本地服务器 字符集：utf8mb4
如果你设置了新密码，后面必须同步修改后端 .env 中的数据库连接信息。
2. 导入数据库
进入宝塔：
数据库 → chatbox → 导入
选择旧服务器备份好的数据库文件：
chatbox_xxx.sql
等待导入完成。
导入后，进入数据库管理或 phpMyAdmin，确认可以看到系统相关数据表即可。
九、检查后端环境变量
进入新服务器终端：
cd /www/wwwroot/chat/chatapi.iyqy.cn
编辑 .env：
vim .env
确认端口和数据库配置正确：
PORT=3003 NODE_ENV=production DATABASE_URL="mysql://chatbox:数据库密码@127.0.0.1:3306/chatbox"
如果新服务器数据库密码和旧服务器不同，需要把 .env 中的数据库密码改成新密码。
以下配置建议不要修改：
JWT_SECRET= JWT_REFRESH_SECRET=
迁移服务器时保留原 JWT 密钥，可以避免部分已登录用户立即失效。
如果修改 JWT 密钥，所有用户和客服人员需要重新登录。
十、安装依赖并生成 Prisma
进入后端目录：
cd /www/wwwroot/chat/chatapi.iyqy.cn
安装依赖：
npm install
如果存在 package-lock.json，推荐执行：
npm ci
生成 Prisma Client：
npx prisma generate
已经导入旧数据库时，通常不需要再执行 npx prisma db push 和 npm run db:seed。
否则可能改变已有表结构，或重复写入初始账号和数据。
十一、检查上传文件权限
执行：
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 反向代理
进入宝塔：
网站 → 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。
不要在 API 站点主配置文件中额外添加 location /，否则可能提示 duplicate location。
十三、配置管理后台和用户端路由
1. 管理后台 chatadmin.iyqy.cn
进入：
网站 → chatadmin.iyqy.cn → 配置文件
添加：
location / {
try_files $uri $uri/ /index.html;
}
保存并重载 Nginx。
2. 用户端 chat.iyqy.cn
进入：
网站 → chat.iyqy.cn → 配置文件
添加：
location / {
try_files $uri $uri/ /index.html;
}
保存并重载 Nginx。
十四、启动 PM2 后端服务
进入后端目录：
cd /www/wwwroot/chat/chatapi.iyqy.cn
启动服务：
pm2 start dist/main.js \ --name chatapi \ --max-memory-restart 512M
查看状态：
pm2 status
正常应显示：
chatapi online
查看日志：
pm2 logs chatapi
如果没有报错，说明后端已正常运行。
设置服务器重启后自动启动：
pm2 save pm2 startup
执行 pm2 startup 后，复制终端返回的完整命令执行一次。
最后再执行：
pm2 save
十五、重新申请 SSL 证书
迁移到新服务器后，有证书直接复制旧服务器证书，快过期了就申请新的
分别进入：
网站 → chatapi.iyqy.cn → SSL 网站 → chatadmin.iyqy.cn → SSL 网站 → chat.iyqy.cn → SSL
选择：
Let's Encrypt → 申请证书
申请成功后，三个站点都开启：
强制 HTTPS
十六、切换域名解析
确认新服务器已恢复好程序、数据库、反向代理后，再去域名后台修改 A 记录。
域名修改为chatapi.iyqy.cn | 新服务器公网 IP
chatadmin.iyqy.cn | 新服务器公网 IP
chat.iyqy.cn | 新服务器公网 IP
DNS 解析生效后，再重新申请 SSL 证书。
十七、迁移后检查
1. 检查 API
服务器终端执行：
curl -I http://127.0.0.1:3003/api/v1/admin/auth/info
返回 401 Unauthorized 属于正常，说明 API 已启动。
域名和 SSL 配置完成后，执行：
curl -I https://chatapi.iyqy.cn/api/v1/admin/auth/info
返回 401 说明 API、Nginx、域名配置均正常。
2. 检查后台和用户端
浏览器分别访问：
https://chatadmin.iyqy.cn https://chat.iyqy.cn
确认：
- 管理后台可以打开登录页面
- 用户端可以打开聊天页面
- 页面静态资源没有 404
- 接口请求地址为 https://chatapi.iyqy.cn
- WebSocket 地址为 wss://chatapi.iyqy.cn
3. 检查业务数据
登录管理后台后检查：
- 超级管理员、商户管理员、客服账号是否存在
- 商户和坐席数据是否完整
- 历史会话和聊天记录是否存在
- 知识库和 AI 配置是否存在
- 公告、套餐、系统配置是否正常
- 历史图片和附件是否能正常打开
4. 测试实时聊天
完整测试一次：
- 打开 https://chat.iyqy.cn
- 打开 https://chatadmin.iyqy.cn
- 用户发送文字消息
- 后台客服是否实时收到
- 客服回复后用户端是否立即收到
- 测试上传图片和文件
- 检查图片、附件是否能正常查看
- 检查 AI 自动回复、转人工是否正常
- 检查在线状态、正在输入状态是否正常
十八、旧服务器保留建议
新服务器稳定运行后，不要立即释放旧服务器。
建议保留旧服务器至少：
7～14 天
确认以下内容都没有问题后，再考虑下线旧服务器：
数据库完整 聊天记录完整 图片与附件完整 实时消息正常 后台和用户端正常 AI 回复正常 域名和 SSL 正常
十九、日常备份建议
建议定期备份：
内容建议频率chatbox 数据库 | 每天
/www/wwwroot/chat/ 整体目录 | 每周，或每次更新前
.env 文件 | 每次配置变更后
uploads 文件夹 | 每天或每周
宝塔中可设置：
计划任务 → 备份数据库 → chatbox → 每天执行
程序文件可定期压缩：
cd /www/wwwroot tar -czf /www/backup/chat-$(date +%F).tar.gz chat
建议把数据库备份和程序备份同步到本地电脑、网盘、对象存储或另一台服务器。
只备份在当前服务器，服务器故障时备份也可能一起丢失。
二十、快速迁移顺序
1. 停止旧服务器 chatapi 2. 宝塔备份 chatbox 数据库并下载 3. 压缩 /www/wwwroot/chat/ 文件夹并下载 4. 新服务器安装宝塔、Nginx、MySQL、Node.js 22.22.3、PM2 5. 新服务器添加 chatapi、chatadmin、chat 三个站点 6. 上传并解压 chat.tar.gz 到 /www/wwwroot/ 7. 创建 chatbox 数据库并导入旧数据库 8. 修改 chatapi 的 .env 数据库密码 9. npm ci 或 npm install 10. npx prisma generate 11. 配置 API 反向代理和 WebSocket 12. 配置两个前端 SPA 路由 13. PM2 启动 chatapi 14. 申请三个域名 SSL 证书 15. 修改三个域名解析到新服务器 16. 测试登录、聊天、上传、附件和 WebSocket 17. 旧服务器保留 7～14 天后再下线