java-template/client-deployment/docs/DATABASE_UPGRADE_GUIDE.md

智能穿戴系统数据库升级指南

概述

本指南提供了智能穿戴系统客户现场数据库升级的完整解决方案。该方案旨在为现有客户提供安全、可靠、可回滚的数据库升级体验。

核心特性

🔧 智能版本管理

• 自动版本检测: 自动识别现网数据库版本
• 版本记录追踪: 完整的升级历史记录
• 迁移脚本管理: 按版本自动应用迁移脚本

🛡️ 安全保障机制

• 完整数据备份: 升级前自动创建完整备份
• 原子事务执行: 确保升级过程的一致性
• 健康检查验证: 升级前后完整的健康检查
• 一键回滚功能: 升级失败自动回滚

📊 可观测性

• 详细升级日志: 完整的升级过程记录
• 升级状态报告: 自动生成升级报告
• 性能监控: 升级过程性能指标

目录结构

client-deployment/
├── database-upgrade-manager.sh     # 主升级管理脚本
├── database/
│   ├── migrations/                 # 迁移脚本目录
│   │   ├── 003_create_weight_cache_table.sql
│   │   ├── 004_optimize_health_baseline_for_userid.sql
│   │   ├── 005_create_message_v2_tables.sql
│   │   └── 006_alert_auto_process_enhancement_fixed.sql
│   └── upgrade_1.0.0_to_1.1.0.sql  # 版本特定升级脚本
├── backup/
│   └── database-upgrade/           # 升级备份目录
└── logs/
    └── database-upgrade/           # 升级日志目录

快速开始

1. 检查当前数据库版本

# 查看当前数据库版本状态
./database-upgrade-manager.sh status

2. 执行数据库升级

# 从版本 1.0.0 升级到 1.1.0
./database-upgrade-manager.sh upgrade 1.0.0 1.1.0

3. 验证升级结果

升级完成后，脚本会自动生成升级报告和执行健康检查。

详细使用指南

命令行接口

# 显示帮助信息
./database-upgrade-manager.sh help

# 检查数据库版本和状态
./database-upgrade-manager.sh status

# 执行数据库升级
./database-upgrade-manager.sh upgrade [源版本] [目标版本]

# 回滚到升级前状态
./database-upgrade-manager.sh rollback

配置文件

脚本默认读取 custom-config.env 配置文件，包含以下关键配置：

# MySQL 配置
MYSQL_CONTAINER=ljwx-mysql
MYSQL_USER=root
MYSQL_PASSWORD=123456
MYSQL_DATABASE=lj-06

# 备份配置
BACKUP_DIR=backup/database-upgrade
LOG_DIR=logs/database-upgrade

升级前准备

1. 环境检查

确保以下条件满足：

• MySQL 容器正常运行
• 数据库连接正常
• 磁盘空间充足 (建议预留 > 15%)
• 备份目录可写
• 日志目录可写

2. 停止应用服务（可选）

为避免升级过程中的数据冲突，建议停止应用服务：

docker stop ljwx-boot ljwx-admin ljwx-bigscreen

升级流程详解

步骤 1: 健康检查

[10:30:15] 🔍 执行升级前健康检查...
[10:30:16] ✅ 健康检查通过

• 检查 MySQL 容器状态
• 验证数据库连接
• 检查磁盘空间使用率
• 评估数据库大小

步骤 2: 数据备份

[10:30:16] 📦 创建数据库备份...
[10:30:25] ✅ 数据备份完成: pre_upgrade_20250911_103025.sql.gz (45MB)

• 创建完整的数据库备份
• 备份表结构文件
• 保存备份路径供回滚使用

步骤 3: 执行迁移脚本

[10:30:25] 📝 执行数据库迁移脚本...
[10:30:26] 执行迁移脚本: 006_alert_auto_process_enhancement_fixed.sql
[10:30:27] ✅ 006_alert_auto_process_enhancement_fixed.sql 执行成功
[10:30:27] 执行迁移脚本: upgrade_1.0.0_to_1.1.0.sql
[10:30:30] ✅ upgrade_1.0.0_to_1.1.0.sql 执行成功

步骤 4: 数据完整性验证

[10:30:30] 🔍 验证数据库完整性...
[10:30:31] 数据库包含 45 个表
[10:30:31] ✅ 表 sys_user: 125 条记录
[10:30:31] ✅ 表 sys_dict: 89 条记录
[10:30:31] ✅ 表 t_alert_rules: 23 条记录

步骤 5: 性能优化

[10:30:32] ⚡ 执行数据库性能优化...
[10:30:35] ✅ 数据库优化完成

步骤 6: 生成报告

[10:30:35] 📋 生成升级报告...
[10:30:36] ✅ 升级报告已生成: logs/database-upgrade/upgrade_report_20250911_103025.md

版本管理机制

版本表结构

系统自动创建 database_version 表记录升级历史：

CREATE TABLE database_version (
    id INT AUTO_INCREMENT PRIMARY KEY,
    version VARCHAR(20) NOT NULL,
    description TEXT,
    applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    applied_by VARCHAR(100) DEFAULT 'system',
    migration_files TEXT COMMENT '应用的迁移文件列表'
);

版本检测逻辑

1. 首次安装: 自动创建版本表，设置初始版本为 1.0.0
2. 版本检测: 从版本表读取当前版本
3. 版本验证: 确保源版本与当前版本一致

迁移脚本管理

脚本命名规范

• 通用迁移脚本: database/migrations/XXX_description.sql
• 版本特定脚本: database/upgrade_[源版本]_to_[目标版本].sql

脚本执行顺序

1. 按文件名排序执行 migrations/ 目录中的脚本
2. 执行版本特定的升级脚本
3. 更新版本记录

备份与恢复

自动备份策略

每次升级前自动创建：

1. 完整数据备份: pre_upgrade_[时间戳].sql.gz
2. 表结构备份: structure_[时间戳].sql
3. 备份路径记录: latest_backup.path

手动备份

# 使用现有的备份脚本
./auto-backup.sh

# 或使用 MySQL 原生备份
docker exec ljwx-mysql mysqldump -uroot -p123456 --single-transaction --routines --triggers --events lj-06 | gzip > manual_backup.sql.gz

回滚操作

自动回滚

升级失败时会自动触发回滚：

[10:35:15] 🔄 开始数据库回滚操作...
[10:35:25] ✅ 数据库回滚成功
[10:35:30] ✅ 回滚操作完成

手动回滚

# 回滚到升级前状态
./database-upgrade-manager.sh rollback

回滚流程

1. 停止应用服务
2. 从备份文件恢复数据库
3. 重启应用服务
4. 验证回滚结果

支持的升级路径

当前版本升级矩阵

源版本	目标版本	升级脚本	状态
1.0.0	1.1.0	✅ 可用	已测试
1.1.0	1.2.0	🚧 开发中	计划中

版本更新内容

v1.1.0 更新内容

功能增强:

• ✅ 告警自动处理功能
• ✅ 权重配置缓存系统
• ✅ 性能优化索引

数据库变更:

• 新增 t_weight_cache 表
• t_alert_rules 表增加自动处理字段
• t_alert_info 表增加处理跟踪字段
• 新增多个性能优化索引

迁移脚本:

• 006_alert_auto_process_enhancement_fixed.sql
• upgrade_1.0.0_to_1.1.0.sql

故障排除

常见问题

1. 升级失败：权限不足

问题:

[ERROR] 数据备份失败

解决方案:

# 检查备份目录权限
chmod 755 backup/database-upgrade/
chown $(whoami):$(whoami) backup/database-upgrade/

# 检查 MySQL 容器状态
docker ps | grep ljwx-mysql

2. 升级失败：磁盘空间不足

问题:

[WARN] 磁盘使用率 88%，建议清理空间

解决方案:

# 清理 Docker 镜像
docker image prune -f

# 清理旧备份文件
find backup/ -name "*.sql.gz" -mtime +30 -delete

# 清理 Docker 日志
docker system prune -f

3. 迁移脚本执行失败

问题:

[ERROR] 006_alert_auto_process_enhancement_fixed.sql 执行失败

解决方案:

# 手动检查脚本内容
cat database/migrations/006_alert_auto_process_enhancement_fixed.sql

# 手动执行脚本测试
docker exec -i ljwx-mysql mysql -uroot -p123456 lj-06 < database/migrations/006_alert_auto_process_enhancement_fixed.sql

# 检查表结构
docker exec ljwx-mysql mysql -uroot -p123456 lj-06 -e "DESCRIBE t_alert_rules;"

4. 回滚失败

问题:

[ERROR] 备份文件不存在: backup/database-upgrade/pre_upgrade_xxx.sql.gz

解决方案:

# 检查备份文件
ls -la backup/database-upgrade/

# 使用最新可用备份
ls -t backup/database-upgrade/*.sql.gz | head -1

# 手动指定备份文件恢复
zcat backup/database-upgrade/[备份文件] | docker exec -i ljwx-mysql mysql -uroot -p123456

日志分析

升级日志位置

# 查看最新升级日志
tail -f logs/database-upgrade/upgrade_*.log

# 查看升级报告
cat logs/database-upgrade/upgrade_report_*.md

关键日志模式

# 查找错误信息
grep "ERROR" logs/database-upgrade/upgrade_*.log

# 查找警告信息
grep "WARN" logs/database-upgrade/upgrade_*.log

# 查看执行时间
grep "执行时间" logs/database-upgrade/upgrade_*.log

性能考虑

升级时间预估

数据库大小	预估升级时间	备份时间	迁移时间
< 100MB	1-2 分钟	10-20秒	30-60秒
100MB-1GB	3-8 分钟	1-2分钟	2-5分钟
1GB-10GB	10-30 分钟	3-8分钟	5-15分钟
> 10GB	30+ 分钟	10+分钟	15+分钟

性能优化建议

升级前优化

# 清理无用数据
docker exec ljwx-mysql mysql -uroot -p123456 lj-06 -e "
DELETE FROM t_alert_info WHERE create_time < DATE_SUB(NOW(), INTERVAL 6 MONTH);
OPTIMIZE TABLE t_alert_info;
"

# 释放磁盘空间
docker exec ljwx-mysql mysql -uroot -p123456 -e "PURGE BINARY LOGS BEFORE NOW();"

升级后优化

# 分析表统计信息
docker exec ljwx-mysql mysql -uroot -p123456 lj-06 -e "
ANALYZE TABLE t_alert_rules, t_alert_info, t_weight_cache;
"

# 检查索引使用情况
docker exec ljwx-mysql mysql -uroot -p123456 lj-06 -e "
SHOW INDEX FROM t_alert_info;
"

集成到现有部署流程

修改 deploy-client.sh

在现有部署脚本中集成数据库升级检查：

# 在 deploy-client.sh 中添加升级检查
if ! is_first_deployment; then
    echo "🔄 检测到升级部署，执行数据库升级检查..."
    
    # 检查是否需要数据库升级
    CURRENT_DB_VERSION=$(./database-upgrade-manager.sh status | grep "当前数据库版本" | cut -d: -f2 | xargs)
    TARGET_DB_VERSION="1.1.0"  # 从配置文件或环境变量读取
    
    if [ "$CURRENT_DB_VERSION" != "$TARGET_DB_VERSION" ]; then
        echo "数据库需要从 $CURRENT_DB_VERSION 升级到 $TARGET_DB_VERSION"
        
        if confirm "是否执行数据库升级？"; then
            ./database-upgrade-manager.sh upgrade "$CURRENT_DB_VERSION" "$TARGET_DB_VERSION"
        else
            echo "跳过数据库升级"
        fi
    else
        echo "数据库版本已是最新: $CURRENT_DB_VERSION"
    fi
fi

自动化升级流程

创建升级检查脚本 check-upgrade.sh：

#!/bin/bash
# 自动检查和执行升级

# 读取配置中的目标版本
TARGET_VERSION=$(grep "DB_VERSION=" custom-config.env | cut -d= -f2)
CURRENT_VERSION=$(./database-upgrade-manager.sh status | grep "当前数据库版本" | cut -d: -f2 | xargs)

if [ "$CURRENT_VERSION" != "$TARGET_VERSION" ]; then
    echo "检测到数据库版本差异，启动升级流程..."
    ./database-upgrade-manager.sh upgrade "$CURRENT_VERSION" "$TARGET_VERSION"
else
    echo "数据库版本已是最新"
fi

最佳实践

1. 升级前准备清单

• 确认服务运行状态正常
• 验证数据库连接和权限
• 检查磁盘空间充足 (>20% 可用空间)
• 备份关键配置文件
• 通知相关人员升级计划
• 准备回滚计划

2. 升级执行

• 选择业务低峰期执行
• 停止非必要应用服务
• 监控升级过程日志
• 验证升级后功能正常
• 检查性能指标

3. 升级后验证

# 功能验证脚本
#!/bin/bash
echo "开始升级后验证..."

# 1. 数据库连接测试
if docker exec ljwx-mysql mysql -uroot -p123456 lj-06 -e "SELECT 1;" &>/dev/null; then
    echo "✅ 数据库连接正常"
else
    echo "❌ 数据库连接失败"
    exit 1
fi

# 2. 关键表检查
TABLES=("sys_user" "t_alert_rules" "t_alert_info" "t_weight_cache")
for table in "${TABLES[@]}"; do
    count=$(docker exec ljwx-mysql mysql -uroot -p123456 lj-06 -e "SELECT COUNT(*) FROM $table;" -s -N 2>/dev/null)
    if [[ $count -ge 0 ]]; then
        echo "✅ 表 $table: $count 条记录"
    else
        echo "❌ 表 $table 检查失败"
    fi
done

# 3. 新功能测试
if docker exec ljwx-mysql mysql -uroot -p123456 lj-06 -e "DESCRIBE t_alert_rules auto_process_enabled;" &>/dev/null; then
    echo "✅ 自动处理功能字段存在"
else
    echo "❌ 自动处理功能字段缺失"
fi

# 4. 应用服务健康检查
sleep 10
curl -f http://localhost:9998/actuator/health &>/dev/null && echo "✅ ljwx-boot 服务正常" || echo "❌ ljwx-boot 服务异常"
curl -f http://localhost:8001/health &>/dev/null && echo "✅ ljwx-bigscreen 服务正常" || echo "❌ ljwx-bigscreen 服务异常"
curl -f http://localhost:8080/ &>/dev/null && echo "✅ ljwx-admin 服务正常" || echo "❌ ljwx-admin 服务异常"

echo "验证完成！"

4. 监控和告警

# 设置升级监控脚本
#!/bin/bash
# upgrade-monitor.sh

LOG_FILE="logs/database-upgrade/upgrade_$(date +%Y%m%d_*).log"

# 监控升级进度
tail -f $LOG_FILE | while read line; do
    case "$line" in
        *"ERROR"*)
            # 发送告警通知
            echo "数据库升级遇到错误: $line" | mail -s "升级告警" [email protected]
            ;;
        *"✅ 数据库升级成功"*)
            # 发送成功通知
            echo "数据库升级成功完成" | mail -s "升级成功" [email protected]
            break
            ;;
    esac
done

技术架构

脚本架构设计

database-upgrade-manager.sh
├── 配置管理模块
│   ├── 环境变量加载
│   └── 参数验证
├── 版本管理模块
│   ├── 版本检测
│   ├── 版本表创建
│   └── 版本记录更新
├── 备份恢复模块
│   ├── 数据备份
│   ├── 结构备份
│   └── 自动回滚
├── 迁移执行模块
│   ├── 脚本扫描
│   ├── 事务执行
│   └── 错误处理
├── 验证模块
│   ├── 健康检查
│   ├── 完整性验证
│   └── 性能测试
└── 报告模块
    ├── 日志记录
    ├── 报告生成
    └── 统计分析

数据流图

现网数据库 --> 版本检测 --> 健康检查 --> 数据备份
                                             ↓
升级报告 <-- 性能优化 <-- 完整性验证 <-- 迁移执行
    ↓                                        ↓
用户确认                                   错误处理
    ↓                                        ↓
升级完成 <-- 服务重启 <-- 清理临时文件    自动回滚

总结

本数据库升级解决方案提供了：

✅ 完整的版本管理: 自动版本检测和升级路径管理
✅ 可靠的安全保障: 完整备份和一键回滚机制
✅ 详细的可观测性: 全程日志记录和升级报告
✅ 灵活的扩展性: 支持自定义迁移脚本和配置
✅ 便捷的操作体验: 一键命令完成复杂升级流程

通过这套解决方案，客户可以安全、便捷地完成数据库升级，确保业务连续性和数据安全性。

---

技术支持: 如有问题请联系技术支持团队
文档版本: v1.0
更新时间: 2025-09-11