初次提交

VoiceHub-main/UPGRADE.md

@@ -0,0 +1,206 @@
+# VoiceHub 升级指南
+
+本文档介绍如何将 VoiceHub 项目从旧版本升级到最新版本。请根据您的部署方式选择相应的升级步骤。
+
+> ⚠️ **升级前请务必备份数据库和配置文件！**
+
+## 1. 备份数据
+
+无论使用何种部署方式，升级前请先备份数据库。
+
+### 1.1 使用管理后台备份（推荐）
+
+1. 登录管理员后台
+2. 进入"数据库管理"页面
+3. 点击"创建备份" -> 选择"完整备份"
+4. 待备份完成后，下载备份文件到本地保存
+
+### 1.2 使用命令行备份
+
+也可以使用 PostgreSQL 命令行工具：
+
+```bash
+# 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. **拉取最新代码**
+
+   ```bash
+   git pull
+   ```
+
+2. **重建并重启服务**
+
+   ```bash
+   docker-compose up -d --build
+   ```
+
+   > **注意**：由于默认配置使用本地构建，单纯使用 `pull` 命令无效。必须添加 `--build` 参数以确保应用代码变更。
+
+3. **验证升级**
+   ```bash
+   docker-compose logs -f voicehub
+   ```
+   查看日志确认没有报错，且显示 "部署完成"。
+
+### 2.2 使用 Docker Run 命令
+
+如果您直接使用 `docker run` 命令：
+
+1. **停止并删除旧容器**
+
+   ```bash
+   docker stop voicehub
+   docker rm voicehub
+   ```
+
+2. **拉取最新镜像**
+
+   ```bash
+   docker pull ghcr.io/laoshuikaixue/voicehub:latest
+   # 或
+   docker pull ghcr.nju.edu.cn/laoshuikaixue/voicehub:latest
+   ```
+
+3. **启动新容器**
+   使用与之前相同的环境变量启动：
+   ```bash
+   docker run -d \
+     -p 3000:3000 \
+     -e DATABASE_URL="..." \
+     -e JWT_SECRET="..." \
+     --name voicehub \
+     ghcr.io/laoshuikaixue/voicehub:latest
+   ```
+
+---
+
+## 3. 源码/本地部署升级
+
+### 3.1 停止运行中的服务
+
+```bash
+# 如果使用 PM2
+pm2 stop voicehub
+
+# 如果使用 systemd
+sudo systemctl stop voicehub
+
+# 如果直接运行（Ctrl+C 停止进程）
+```
+
+### 3.2 获取最新代码
+
+```bash
+# 拉取最新代码
+git pull origin main
+
+# 或指定分支
+# git pull origin <branch-name>
+```
+
+### 3.3 更新依赖
+
+```bash
+# 安装最新依赖
+pnpm install --frozen-lockfile
+```
+
+### 3.4 数据库迁移
+
+**重要**：新版本通常包含数据库结构变更，必须执行迁移。
+
+```bash
+# 方式 1：使用自动同步脚本（推荐）
+node scripts/db-sync.js
+
+# 方式 2：手动执行迁移
+pnpm run db:migrate
+
+# 方式 3：如果迁移失败，且确信可以覆盖（仅开发环境）
+# pnpm run db:push
+```
+
+**迁移说明**：
+
+- `db-sync.js` 脚本会自动检测数据库状态并选择合适的迁移方式
+- 空数据库会执行完整迁移
+- 已有数据的数据库会使用 push 方式同步结构
+
+### 3.5 重新构建应用
+
+```bash
+# 清理旧的构建文件（可选）
+rm -rf .nuxt .output
+
+# 构建生产版本
+pnpm run build
+```
+
+构建完成后，会在 `.output` 目录生成生产环境文件。
+
+### 3.6 重启服务
+
+根据您的部署方式选择：
+
+#### 使用 PM2（推荐）
+
+```bash
+# 重启服务
+pm2 restart voicehub
+
+# 查看日志
+pm2 logs voicehub
+
+# 查看状态
+pm2 status
+```
+
+如果是首次使用 PM2：
+
+```bash
+# 安装 PM2
+pnpm add -g pm2
+
+# 启动应用
+pm2 start pnpm --name voicehub -- run start
+
+# 设置开机自启
+pm2 startup
+pm2 save
+```
+
+#### 使用 systemd
+
+```bash
+# 重启服务
+sudo systemctl restart voicehub
+
+# 查看状态
+sudo systemctl status voicehub
+
+# 查看日志
+sudo journalctl -u voicehub -f
+```
+
+#### 直接运行
+
+```bash
+# 生产模式启动
+pnpm run start
+
+# 或使用 nohup 后台运行
+nohup pnpm run start > voicehub.log 2>&1 &
+```