207 lines
3.8 KiB
Markdown
207 lines
3.8 KiB
Markdown
# 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 &
|
||
```
|