BYW-VoiceHub/VoiceHub-main/UPGRADE.md

VoiceHub 升级指南

本文档介绍如何将 VoiceHub 项目从旧版本升级到最新版本。请根据您的部署方式选择相应的升级步骤。

⚠️ 升级前请务必备份数据库和配置文件！

1. 备份数据

无论使用何种部署方式，升级前请先备份数据库。

1.1 使用管理后台备份（推荐）

1. 登录管理员后台
2. 进入"数据库管理"页面
3. 点击"创建备份" -> 选择"完整备份"
4. 待备份完成后，下载备份文件到本地保存

1.2 使用命令行备份

也可以使用 PostgreSQL 命令行工具：

# Docker 部署用户
docker exec voicehub-postgres-1 pg_dump -U user voicehub > backup_$(date +%Y%m%d).sql

# 源码部署用户
pg_dump -h localhost -U your_username -d voicehub > backup_$(date +%Y%m%d).sql

---

2. Docker 部署升级

2.1 使用 Docker Compose（推荐）

如果您使用 docker-compose.yml 部署：

1. 拉取最新代码

   git pull
   

2. 重建并重启服务

   docker-compose up -d --build
   

   注意：由于默认配置使用本地构建，单纯使用 pull 命令无效。必须添加 --build 参数以确保应用代码变更。

3. 验证升级

   docker-compose logs -f voicehub
   

   查看日志确认没有报错，且显示 "部署完成"。

2.2 使用 Docker Run 命令

如果您直接使用 docker run 命令：

1. 停止并删除旧容器

   docker stop voicehub
   docker rm voicehub
   

2. 拉取最新镜像

   docker pull ghcr.io/laoshuikaixue/voicehub:latest
   # 或
   docker pull ghcr.nju.edu.cn/laoshuikaixue/voicehub:latest
   

3. 启动新容器 使用与之前相同的环境变量启动：

   docker run -d \
     -p 3000:3000 \
     -e DATABASE_URL="..." \
     -e JWT_SECRET="..." \
     --name voicehub \
     ghcr.io/laoshuikaixue/voicehub:latest
   

---

3. 源码/本地部署升级

3.1 停止运行中的服务

# 如果使用 PM2
pm2 stop voicehub

# 如果使用 systemd
sudo systemctl stop voicehub

# 如果直接运行（Ctrl+C 停止进程）

3.2 获取最新代码

# 拉取最新代码
git pull origin main

# 或指定分支
# git pull origin <branch-name>

3.3 更新依赖

# 安装最新依赖
pnpm install --frozen-lockfile

3.4 数据库迁移

重要：新版本通常包含数据库结构变更，必须执行迁移。

# 方式 1：使用自动同步脚本（推荐）
node scripts/db-sync.js

# 方式 2：手动执行迁移
pnpm run db:migrate

# 方式 3：如果迁移失败，且确信可以覆盖（仅开发环境）
# pnpm run db:push

迁移说明：

• db-sync.js 脚本会自动检测数据库状态并选择合适的迁移方式
• 空数据库会执行完整迁移
• 已有数据的数据库会使用 push 方式同步结构

3.5 重新构建应用

# 清理旧的构建文件（可选）
rm -rf .nuxt .output

# 构建生产版本
pnpm run build

构建完成后，会在 .output 目录生成生产环境文件。

3.6 重启服务

根据您的部署方式选择：

使用 PM2（推荐）

# 重启服务
pm2 restart voicehub

# 查看日志
pm2 logs voicehub

# 查看状态
pm2 status

如果是首次使用 PM2：

# 安装 PM2
pnpm add -g pm2

# 启动应用
pm2 start pnpm --name voicehub -- run start

# 设置开机自启
pm2 startup
pm2 save

使用 systemd

# 重启服务
sudo systemctl restart voicehub

# 查看状态
sudo systemctl status voicehub

# 查看日志
sudo journalctl -u voicehub -f

直接运行

# 生产模式启动
pnpm run start

# 或使用 nohup 后台运行
nohup pnpm run start > voicehub.log 2>&1 &