# 版本升级与回滚

> 平滑升级生产环境，数据库迁移方案，紧急回滚操作手册。

## ⚠️ 升级前必读

### 重要检查清单

- [ ] 备份数据库
- [ ] 查阅版本更新日志
- [ ] 在测试环境验证
- [ ] 确认回滚方案
- [ ] 通知相关人员
- [ ] 选择低峰期执行

### 版本兼容性

| 当前版本 | 可直接升级到 |
|----------|-------------|
| 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)