tiantian-system/public/docs/upgrade.md

版本升级与回滚

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

⚠️ 升级前必读

重要检查清单

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

版本兼容性

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

🚀 升级步骤

准备工作

# 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/

执行升级

# 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

验证升级

# 检查服务状态
docker-compose ps

# 检查 API 健康
curl http://localhost:3000/api/health

# 检查版本号
docker-compose exec api websopy --version

# 查看迁移日志
docker-compose logs api | grep -i migrate

🔧 数据库迁移

迁移说明

每个版本可能包含数据库迁移脚本，确保数据结构与代码兼容。

手动迁移

# 查看待执行迁移
docker-compose run --rm api websopy migrate:status

# 执行迁移
docker-compose run --rm api websopy migrate

# 回滚上一个迁移
docker-compose run --rm api websopy migrate:rollback

迁移脚本结构

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

⤵️ 紧急回滚

自动回滚

# 如果启动失败，查看错误
docker-compose logs api

# 回滚到上一个版本
docker-compose down
git checkout v2.2.0
docker-compose pull
docker-compose up -d

恢复数据库

# 停止服务
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

恢复文件

# 恢复上传文件
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 知识库
• ⚡ 工作流自动化

🧪 测试环境验证

创建测试环境

# 克隆生产配置到测试目录
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: 如何跳过测试直接升级？

不建议跳过测试。但如果必须：

# 强制拉取最新镜像
docker-compose pull --force

# 跳过测试启动
docker-compose up -d

Q: 镜像拉取失败？

# 使用国内镜像源
nano /etc/docker/daemon.json

{
  "registry-mirrors": ["https://mirror.ccs.tencentyun.com"]
}

sudo systemctl restart docker
docker-compose pull

---

上一步： Docker Compose 部署