📈 升级指南

本文档提供 NextConsole 系统的完整升级指南，帮助您安全、高效地完成版本更新。

📋 升级前准备

1. 环境检查

# 检查服务状态
docker compose ps

# 备份重要数据
docker compose exec db pg_dump -U next_console next_console > backup_$(date +%Y%m%d).sql

2. 升级检查清单

• 阅读目标版本的 Release Notes
• 检查数据兼容性说明
• 备份数据库和配置文件
• 确认磁盘空间充足
• 安排维护窗口时间

🐳 Docker 直接升级方式

常规升级流程（数据兼容版本）

1. 拉取最新镜像

# 停止当前服务
docker compose down

# 拉取最新镜像
docker compose pull

# 启动新版本服务
docker compose up -d

2. 验证升级结果

# 检查服务状态
docker compose ps
 

3. 升级后检查

# 查看日志确认无错误
docker compose logs -f server
 

⚠️ 数据不兼容升级处理

存在数据不兼容性的版本升级

当版本说明中明确存在数据不向前兼容的情况时，需要执行特殊升级流程：

1. 准备升级脚本

# 进入升级脚本目录
cd docker/scripts/upgrade

# 查看可用的升级脚本
ls -la upgrade_*.sh

# 执行对应版本的升级脚本
bash upgrade_v2.0.0.sh

2. 升级脚本执行流程

3. 手动执行数据迁移（示例）

#!/bin/bash
# upgrade_v2.0.0.sh

echo "开始执行 v2.0.0 数据迁移..."

# 1. 停止服务
docker compose down

# 2. 备份数据库
BACKUP_FILE="backup_$(date +%Y%m%d_%H%M%S).sql"
docker compose exec db pg_dump -U next_console next_console > $BACKUP_FILE

# 3. 执行数据迁移SQL
docker compose exec db psql -U next_console -d next_console -f /app/scripts/upgrade/v2.0.0_migration.sql

# 4. 更新索引
docker compose exec db psql -U next_console -d next_console -c "REINDEX DATABASE next_console;"

# 5. 启动新服务
docker compose up -d

echo "v2.0.0 数据迁移完成！"

🔄 非带数据升级（Clean Upgrade）

全新数据环境升级

当需要完全重新初始化数据时，可以采用非带数据升级方式：

1. 数据目录重命名

# 停止服务
docker compose down

# 重命名数据目录（保留历史数据）
mv /app/data /app/data.bak_$(date +%Y%m%d_%H%M%S)

# 创建新的数据目录
mkdir -p /app/data

# 设置正确的权限
chmod 755 /app/data
chown -R 1000:1000 /app/data

2. 更新镜像并启动

# 拉取最新镜像
docker compose pull

# 启动新服务（自动初始化新数据库）
docker compose up -d

3. 数据迁移（可选）

如果需要从旧数据中恢复部分数据：

# 复制上传文件等非结构化数据
cp -r /app/data.bak_20250128/upload /app/data/
cp -r /app/data.bak_20250128/download /app/data/

# 设置正确的权限
chown -R 1000:1000 /app/data/upload
chown -R 1000:1000 /app/data/download

🚨 升级故障处理

常见问题及解决方案

1. 升级失败回滚

# 停止服务
docker compose down

# 恢复数据库备份
docker compose exec db psql -U next_console -d next_console -f backup_file.sql

# 回滚到旧版本镜像
docker compose up -d

2. 数据迁移错误

# 检查数据库日志
docker compose logs db

# 手动执行迁移步骤
docker compose exec db psql -U next_console -d next_console -c "SELECT * FROM pg_tables WHERE schemaname = 'next_console';"

📝 升级后验证

功能验证清单

• 系统启动正常
• 数据库连接正常
• API接口访问正常
• 用户登录功能正常
• 核心业务流程正常
• 数据完整性验证

🛡️ 升级最佳实践

1. 生产环境升级流程

2. 升级时间选择

• ⏰ 选择业务低峰期进行升级
• 📅 提前通知相关用户
• 🔄 安排技术人员值守

3. 监控和告警

# 监控关键指标
监控项：
- 服务响应时间
- 数据库连接数
- 内存使用情况
- 错误日志增长

# 设置告警阈值
- 响应时间 > 2s
- 错误率 > 1%
- 内存使用 > 80%

📞 技术支持

如果升级过程中遇到问题：

1. 查看日志: docker compose logs -f
2. 检查文档: 故障排查指南
3. 社区支持: GitHub Discussions
4. 提交Issue: GitHub Issues

🔄 版本回滚指南

紧急回滚步骤

# 1. 停止当前服务
docker compose down

# 2. 恢复数据备份
docker compose exec db psql -U next_console -d next_console -f /backups/backup_20250128.sql

# 3. 回退到旧版本镜像
docker compose up -d

回滚检查清单

• 数据库版本兼容性
• 配置文件回退
• 服务依赖检查
• 功能验证测试

---