260 lines
4.6 KiB
Markdown
260 lines
4.6 KiB
Markdown
# 版本升级与回滚
|
||
|
||
> 平滑升级生产环境，数据库迁移方案，紧急回滚操作手册。
|
||
|
||
## ⚠️ 升级前必读
|
||
|
||
### 重要检查清单
|
||
|
||
- [ ] 备份数据库
|
||
- [ ] 查阅版本更新日志
|
||
- [ ] 在测试环境验证
|
||
- [ ] 确认回滚方案
|
||
- [ ] 通知相关人员
|
||
- [ ] 选择低峰期执行
|
||
|
||
### 版本兼容性
|
||
|
||
| 当前版本 | 可直接升级到 |
|
||
|----------|-------------|
|
||
| 2.0.x | 2.1.x |
|
||
| 2.1.x | 2.2.x, 2.3.x |
|
||
| 2.2.x | 2.3.x |
|
||
| 1.x | 需要先升级到 2.0 |
|
||
|
||
## 🚀 升级步骤
|
||
|
||
### 准备工作
|
||
|
||
```bash
|
||
# 1. 进入部署目录
|
||
cd ~/websopy-deploy
|
||
|
||
# 2. 备份当前版本配置
|
||
cp docker-compose.yml docker-compose.yml.bak
|
||
cp .env .env.bak
|
||
|
||
# 3. 备份数据库（必须！）
|
||
docker-compose exec postgres pg_dump -U websopy > backups/db_backup_$(date +%Y%m%d).sql
|
||
|
||
# 4. 备份上传文件
|
||
tar -czf backups/uploads_$(date +%Y%m%d).tar.gz -C /data/websopy uploads/
|
||
```
|
||
|
||
### 执行升级
|
||
|
||
```bash
|
||
# 1. 停止服务
|
||
docker-compose down
|
||
|
||
# 2. 拉取新版本镜像
|
||
docker-compose pull
|
||
|
||
# 3. 更新代码（如果使用 git 部署）
|
||
git fetch origin
|
||
git checkout v2.3.0
|
||
|
||
# 4. 检查新版本配置变更
|
||
git diff v2.2.0 v2.3.0 -- .env.example
|
||
|
||
# 5. 合并配置变更
|
||
nano .env
|
||
|
||
# 6. 启动服务
|
||
docker-compose up -d
|
||
|
||
# 7. 执行数据库迁移
|
||
docker-compose run --rm api websopy migrate
|
||
```
|
||
|
||
### 验证升级
|
||
|
||
```bash
|
||
# 检查服务状态
|
||
docker-compose ps
|
||
|
||
# 检查 API 健康
|
||
curl http://localhost:3000/api/health
|
||
|
||
# 检查版本号
|
||
docker-compose exec api websopy --version
|
||
|
||
# 查看迁移日志
|
||
docker-compose logs api | grep -i migrate
|
||
```
|
||
|
||
## 🔧 数据库迁移
|
||
|
||
### 迁移说明
|
||
|
||
每个版本可能包含数据库迁移脚本，确保数据结构与代码兼容。
|
||
|
||
### 手动迁移
|
||
|
||
```bash
|
||
# 查看待执行迁移
|
||
docker-compose run --rm api websopy migrate:status
|
||
|
||
# 执行迁移
|
||
docker-compose run --rm api websopy migrate
|
||
|
||
# 回滚上一个迁移
|
||
docker-compose run --rm api websopy migrate:rollback
|
||
```
|
||
|
||
### 迁移脚本结构
|
||
|
||
```bash
|
||
migrations/
|
||
├── 2024_01_15_000001_create_users.sql
|
||
├── 2024_01_20_000002_add_avatar_to_users.sql
|
||
└── 2024_02_01_000003_create_projects_table.sql
|
||
```
|
||
|
||
## ⤵️ 紧急回滚
|
||
|
||
### 自动回滚
|
||
|
||
```bash
|
||
# 如果启动失败，查看错误
|
||
docker-compose logs api
|
||
|
||
# 回滚到上一个版本
|
||
docker-compose down
|
||
git checkout v2.2.0
|
||
docker-compose pull
|
||
docker-compose up -d
|
||
```
|
||
|
||
### 恢复数据库
|
||
|
||
```bash
|
||
# 停止服务
|
||
docker-compose down
|
||
|
||
# 删除新数据库
|
||
docker-compose exec postgres dropdb -U websopy websopy
|
||
|
||
# 创建空数据库
|
||
docker-compose exec postgres createdb -U websopy websopy
|
||
|
||
# 恢复备份
|
||
docker exec -i $(docker-compose ps -q postgres) psql -U websopy < backups/db_backup_20240115.sql
|
||
|
||
# 启动服务
|
||
docker-compose up -d
|
||
```
|
||
|
||
### 恢复文件
|
||
|
||
```bash
|
||
# 恢复上传文件
|
||
tar -xzf backups/uploads_20240115.tar.gz -C /data/websopy/
|
||
```
|
||
|
||
## 📊 版本更新日志
|
||
|
||
### v2.3.0（最新）
|
||
|
||
**新增功能：**
|
||
- 🚀 AI 流式输出优化，延迟降低 50%
|
||
- 📊 新增数据看板组件
|
||
- 🔔 支持自定义 Webhook 事件
|
||
|
||
**Breaking Changes：**
|
||
- ⚠️ API `/ai/chat` 端点参数变更
|
||
- ⚠️ 环境变量 `AI_MODEL` 重命名为 `DEFAULT_MODEL`
|
||
|
||
### v2.2.0
|
||
|
||
**新增功能：**
|
||
- 💬 多语言支持
|
||
- 📱 移动端优化
|
||
- 🔐 SSO 单点登录
|
||
|
||
### v2.1.0
|
||
|
||
**新增功能：**
|
||
- 🤖 AI Agent 功能
|
||
- 📚 RAG 知识库
|
||
- ⚡ 工作流自动化
|
||
|
||
## 🧪 测试环境验证
|
||
|
||
### 创建测试环境
|
||
|
||
```bash
|
||
# 克隆生产配置到测试目录
|
||
cp -r ~/websopy-deploy ~/websopy-test
|
||
|
||
# 修改配置
|
||
cd ~/websopy-test
|
||
nano .env
|
||
# 修改端口避免冲突
|
||
# WEBSOPY_PORT=3001
|
||
|
||
# 启动测试环境
|
||
docker-compose up -d
|
||
|
||
# 使用测试数据
|
||
docker-compose exec -T postgres psql -U websopy < test_data.sql
|
||
```
|
||
|
||
### 测试清单
|
||
|
||
- [ ] 首页访问正常
|
||
- [ ] 用户登录/注册
|
||
- [ ] 主要功能操作
|
||
- [ ] API 接口调用
|
||
- [ ] Webhook 接收
|
||
- [ ] 性能无明显下降
|
||
|
||
## ❓ 常见问题
|
||
|
||
### Q: 迁移失败怎么办？
|
||
|
||
1. 停止所有服务
|
||
2. 恢复数据库备份
|
||
3. 检查迁移脚本错误
|
||
4. 联系技术支持
|
||
|
||
### Q: 升级后性能下降？
|
||
|
||
1. 检查资源使用情况
|
||
2. 重启服务清理缓存
|
||
3. 查看日志排查问题
|
||
|
||
### Q: 如何跳过测试直接升级？
|
||
|
||
不建议跳过测试。但如果必须：
|
||
|
||
```bash
|
||
# 强制拉取最新镜像
|
||
docker-compose pull --force
|
||
|
||
# 跳过测试启动
|
||
docker-compose up -d
|
||
```
|
||
|
||
### Q: 镜像拉取失败？
|
||
|
||
```bash
|
||
# 使用国内镜像源
|
||
nano /etc/docker/daemon.json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"registry-mirrors": ["https://mirror.ccs.tencentyun.com"]
|
||
}
|
||
```
|
||
|
||
```bash
|
||
sudo systemctl restart docker
|
||
docker-compose pull
|
||
```
|
||
|
||
---
|
||
|
||
**上一步：** [Docker Compose 部署](./docker.md)
|