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. 检查当前数据库版本

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

### 2. 执行数据库升级

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

### 3. 验证升级结果

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

## 详细使用指南

### 命令行接口

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

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

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

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

### 配置文件

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

```bash
# 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. 环境检查

确保以下条件满足：

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

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

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

```bash
docker stop ljwx-boot ljwx-admin ljwx-bigscreen
```

### 升级流程详解

#### 步骤 1: 健康检查

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

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

#### 步骤 2: 数据备份

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

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

#### 步骤 3: 执行迁移脚本

```bash
[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: 数据完整性验证

```bash
[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: 性能优化

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

#### 步骤 6: 生成报告

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

## 版本管理机制

### 版本表结构

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

```sql
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`

### 手动备份

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

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

### 回滚操作

#### 自动回滚

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

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

#### 手动回滚

```bash
# 回滚到升级前状态
./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] 数据备份失败
```

**解决方案**:
```bash
# 检查备份目录权限
chmod 755 backup/database-upgrade/
chown $(whoami):$(whoami) backup/database-upgrade/

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

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

**问题**:
```
[WARN] 磁盘使用率 88%，建议清理空间
```

**解决方案**:
```bash
# 清理 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 执行失败
```

**解决方案**:
```bash
# 手动检查脚本内容
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
```

**解决方案**:
```bash
# 检查备份文件
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
```

### 日志分析

#### 升级日志位置

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

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

#### 关键日志模式

```bash
# 查找错误信息
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+分钟  |

### 性能优化建议

#### 升级前优化

```bash
# 清理无用数据
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();"
```

#### 升级后优化

```bash
# 分析表统计信息
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

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

```bash
# 在 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`：

```bash
#!/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. 升级后验证

```bash
# 功能验证脚本
#!/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. 监控和告警

```bash
# 设置升级监控脚本
#!/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