# 保守升级指南 - POM 依赖安全升级

## 📋 升级概述

本次保守升级主要目标是**修复安全漏洞**，同时**保持系统稳定性**。我们采用最小化变更原则，只升级有安全风险的依赖版本。

## 🎯 升级策略

### ✅ **保持不变的组件**
- **Spring Boot**: 保持 2.5.x 系列 (2.5.4 → 2.5.15)
- **API 文档**: 继续使用 Swagger (springfox)
- **核心业务逻辑**: 无需修改
- **配置文件**: 基本无需修改

### 🔄 **安全升级的依赖**
- **MySQL 连接器**: `mysql-connector-java` → `mysql-connector-j 8.2.0` (修复 CVE-2023-22102)
- **FastJSON**: `2.0.20` → `2.0.43` (修复多个安全漏洞)
- **Hutool**: `5.8.11` → `5.8.25` (安全更新)
- **JWT**: 升级到 `0.11.5` 并优化依赖结构
- **BouncyCastle**: `bcprov-jdk15on` → `bcprov-jdk18on 1.77`
- **其他组件**: 多个依赖的安全版本升级

## 📊 **主要变更对比**

| 组件 | 当前版本 | 升级版本 | 风险等级 | 变更原因 |
|------|----------|----------|----------|----------|
| Spring Boot | 2.5.4 | 2.5.15 | 🟢 低 | 安全补丁 |
| MySQL Connector | mysql-connector-java | mysql-connector-j 8.2.0 | 🟡 中 | CVE-2023-22102 |
| FastJSON | 2.0.20 | 2.0.43 | 🟢 低 | 安全漏洞修复 |
| Hutool | 5.8.11 | 5.8.25 | 🟢 低 | 安全更新 |
| JWT | 0.11.2 | 0.11.5 | 🟡 中 | 依赖结构优化 |
| Druid | 1.2.6 | 1.2.20 | 🟢 低 | 稳定性提升 |

## 🚀 **升级步骤**

### 第一步: 备份当前环境
```bash
# 1. 备份当前 pom.xml
cp pom.xml pom-backup-$(date +%Y%m%d).xml

# 2. 提交当前代码到版本控制
git add .
git commit -m "备份：升级前的稳定版本"
git tag v1.5.2-before-upgrade
```

### 第二步: 应用新的 POM 文件
```bash
# 1. 替换 POM 文件
cp pom-conservative-upgrade.xml pom.xml

# 2. 清理并重新构建
mvn clean
mvn dependency:resolve
```

### 第三步: 验证依赖
```bash
# 检查依赖冲突
mvn dependency:tree

# 检查安全漏洞
mvn org.owasp:dependency-check-maven:check
```

### 第四步: 测试验证
```bash
# 1. 编译测试
mvn clean compile

# 2. 运行单元测试
mvn test

# 3. 启动应用测试
mvn spring-boot:run
```

## ⚠️ **可能需要的配置调整**

### 1. MySQL 连接器变更
由于从 `mysql-connector-java` 升级到 `mysql-connector-j`，可能需要检查：

```yaml
# application.yml - 通常无需修改，但建议验证
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver  # 确认驱动类名
```

### 2. JWT 依赖结构变更
新的 JWT 依赖结构更加模块化，如果有自定义 JWT 配置，请验证：

<augment_code_snippet path="src/main/java/com/gxwebsoft/common/core/config" mode="EXCERPT">
````java
// 检查 JWT 相关的配置类是否需要调整
// 通常无需修改，但建议测试 JWT 功能
````
</augment_code_snippet>

## 🧪 **测试检查清单**

### ✅ **功能测试**
- [ ] 用户登录/注册功能
- [ ] JWT Token 生成和验证
- [ ] 数据库连接和查询
- [ ] Redis 缓存功能
- [ ] 文件上传下载
- [ ] 微信支付功能
- [ ] 阿里云 OSS 功能
- [ ] API 文档访问 (Swagger UI)

### ✅ **性能测试**
- [ ] 应用启动时间
- [ ] 内存使用情况
- [ ] 数据库连接池性能
- [ ] API 响应时间

### ✅ **安全测试**
- [ ] 依赖漏洞扫描
- [ ] SQL 注入防护
- [ ] XSS 防护
- [ ] CSRF 防护

## 🔧 **故障排除**

### 问题1: 编译错误
```bash
# 清理并重新下载依赖
mvn clean
rm -rf ~/.m2/repository/com/mysql
mvn dependency:resolve
```

### 问题2: 数据库连接问题
```bash
# 检查 MySQL 连接器版本兼容性
mvn dependency:tree | grep mysql
```

### 问题3: JWT 功能异常
```bash
# 检查 JWT 相关依赖
mvn dependency:tree | grep jjwt
```

## 📈 **升级后的优势**

### 🔒 **安全性提升**
- 修复了 MySQL 连接器的 CVE-2023-22102 漏洞
- 升级 FastJSON 修复多个安全漏洞
- 更新 BouncyCastle 加密库到最新安全版本

### 🚀 **稳定性提升**
- Spring Boot 2.5.15 包含多个稳定性修复
- Druid 连接池性能优化
- Hutool 工具库 bug 修复

### 🔧 **维护性提升**
- JWT 依赖结构更加清晰
- 依赖版本更加统一
- 减少了潜在的依赖冲突

## 📞 **技术支持**

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

1. **检查日志**: 查看详细的错误信息
2. **回滚方案**: 使用备份的 POM 文件快速回滚
3. **逐步排查**: 可以先注释掉有问题的依赖，逐个测试

## 🎉 **升级完成确认**

升级成功的标志：
- ✅ 应用正常启动
- ✅ 所有核心功能正常
- ✅ 依赖漏洞扫描通过
- ✅ 性能无明显下降

---

**注意**: 这是一个保守升级方案，风险相对较低。如果后续需要更大的功能升级（如 Spring Boot 2.7+ 或 SpringDoc），建议在此基础上进行分阶段升级。