侠客岛论坛 Rhex 安全更新教程
适用场景：手动下载 GitHub 仓库 ZIP 包，通过宝塔/服务器手动更新
最后更新：2026-05-01

一、更新前准备（必须执行）

1. 备份整个项目目录
   cp -r /www/wwwroot/rhex /www/wwwroot/rhex_backup_$(date +%Y%m%d_%H%M%S)

2. 备份数据库
   pg_dump -U postgres rhex > /root/rhex_db_$(date +%Y%m%d_%H%M%S).sql

3. 单独备份配置文件
   cp /www/wwwroot/rhex/.env /root/rhex_env_backup.txt

4. 记下备份目录的名称
   ls -la /www/wwwroot/ | grep rhex_backup

二、停止服务

pm2 stop rhex-web rhex-worker

三、删除旧代码（保留 .env、addons、uploads）

cd /www/wwwroot/rhex

删除以下代码目录（这些会被新版本覆盖）

rm -rf src
rm -rf prisma
rm -rf public
rm -rf scripts
rm -rf docs
rm -rf .next

删除根目录的配置文件（保留 .env）

rm -f package.json
rm -f pnpm-lock.yaml
rm -f next.config.mjs
rm -f tsconfig.json

注意：addons、uploads、.env 这三个绝对不能删除！

四、解压并部署新版本

1. 进入项目目录
   cd /www/wwwroot/rhex

2. 解压已上传的压缩包（示例：Rhex-main.zip）
   unzip Rhex-main.zip

3. 将解压出的文件夹内容移动到根目录
   mv Rhex-main/* ./
   mv Rhex-main/.* ./ 2>/dev/null

4. 删除空文件夹和压缩包
   rm -rf Rhex-main
   rm -f Rhex-main.zip

五、恢复配置

1. 恢复 .env 文件
   cp /root/rhex_env_backup.txt .env

2. 确保目录存在
   mkdir -p uploads addons

3. 设置权限
   chown -R www:www .env uploads addons 2>/dev/null
   chmod 755 uploads addons

六、修改端口配置（重要）

sed -i ‘s/“start”: “next start”/“start”: “next start -p 10240”/’ package.json

七、安装依赖并更新数据库

1. 安装依赖
   pnpm install

2. 生成 Prisma 客户端
   npx prisma generate

3. 同步数据库结构（重要！新版经常需要新增表）
   npx prisma db push

4. 重新构建
   pnpm run build

八、重启服务并验证

1. 启动服务
   pm2 start rhex-web rhex-worker

2. 保存 PM2 配置
   pm2 save

3. 查看日志确认正常
   pm2 logs rhex-web --lines 30

4. 检查端口监听
   netstat -tlnp | grep 10240

5. 测试本地访问
   curl http://127.0.0.1:10240

九、浏览器测试

访问 https://xiakedao.hk0.cc 检查以下内容：

• 首页能正常打开
• 能正常登录
• 帖子能正常显示
• 插件功能正常
• 上传的附件/图片能正常显示

十、常见错误及解决方案

错误1：The table public.CustomPage does not exist
原因：新版数据库缺少表
解决：执行 npx prisma db push

错误2：DYNAMIC_SERVER_USAGE
原因：Next.js 构建问题
解决：rm -rf .next && pnpm run build

错误3：端口被占用（EADDRINUSE）
原因：10240 端口被占用
解决：netstat -tlnp | grep 10240 找到进程并 kill

错误4：pnpm install 很慢
解决：使用淘宝镜像
pnpm install --registry=https://registry.npmmirror.com

十一、如果更新失败，回滚操作

1. 停止服务
   pm2 stop rhex-web rhex-worker

2. 删除新版本
   rm -rf /www/wwwroot/rhex

3. 恢复备份
   cp -r /www/wwwroot/rhex_backup_* /www/wwwroot/rhex

4. 重启服务
   pm2 restart rhex-web rhex-worker

5. 恢复数据库（如需）
   psql -U postgres -d rhex < /root/rhex_db_备份文件名.sql

十二、关键注意事项

【必须保留的目录和文件】
├── .env # 配置文件
├── addons/ # 插件目录（绝对不能删）
└── uploads/ # 上传文件目录

【每次更新必须做的】

1. 备份项目和数据库
2. 只删除代码目录（src、prisma、public、scripts 等）
3. 保留 addons、uploads、.env
4. 修改 package.json 中的端口为 10240
5. 执行 prisma db push 更新数据库结构（新版必做）
6. 执行 pnpm run build 重新构建

========================================
保存本文件为：更新说明.txt
下次更新时按顺序执行即可