core/CONSERVATIVE_UPGRADE_GUIDE.md

保守升级指南 - 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	🟢 低	稳定性提升

🚀 升级步骤

第一步: 备份当前环境

# 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 文件

# 1. 替换 POM 文件
cp pom-conservative-upgrade.xml pom.xml

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

第三步: 验证依赖

# 检查依赖冲突
mvn dependency:tree

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

第四步: 测试验证

# 1. 编译测试
mvn clean compile

# 2. 运行单元测试
mvn test

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

⚠️ 可能需要的配置调整

1. MySQL 连接器变更

由于从 mysql-connector-java 升级到 mysql-connector-j，可能需要检查：

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

// 检查 JWT 相关的配置类是否需要调整
// 通常无需修改，但建议测试 JWT 功能

</augment_code_snippet>

🧪 测试检查清单

✅ 功能测试

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

✅ 性能测试

• 应用启动时间
• 内存使用情况
• 数据库连接池性能
• API 响应时间

✅ 安全测试

• 依赖漏洞扫描
• SQL 注入防护
• XSS 防护
• CSRF 防护

🔧 故障排除

问题1: 编译错误

# 清理并重新下载依赖
mvn clean
rm -rf ~/.m2/repository/com/mysql
mvn dependency:resolve

问题2: 数据库连接问题

# 检查 MySQL 连接器版本兼容性
mvn dependency:tree | grep mysql

问题3: JWT 功能异常

# 检查 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），建议在此基础上进行分阶段升级。