Archery项目从1.9.1升级至1.10.0版本问题分析与解决方案

问题背景

在将Archery数据库管理平台从1.9.1版本升级至1.10.0版本过程中，用户遇到了Server Error (500)错误。该错误主要发生在访问SQL审核功能时，系统日志显示数据库字段缺失的异常信息。

错误现象分析

升级后系统报错的核心信息为"Unknown column 'sql_instance.is_ssl' in 'field list'"，这表明数据库结构中缺少了is_ssl字段。进一步检查升级日志发现，执行数据库升级脚本时还出现了"Duplicate column name 'db_name'"的错误提示。

问题根源

经过深入分析，该问题主要由以下几个因素导致：

1. 数据库结构未完整同步：新版本1.10.0在sql_instance表中新增了is_ssl字段，但升级过程中未能正确执行数据库结构变更。

2. 升级脚本执行异常：尝试执行v1.10.0.sql升级脚本时，由于部分字段已存在(db_name)，导致脚本执行中断，后续的字段添加操作未能完成。

3. 环境配置问题：系统提示.env文件缺失，这可能影响了数据库连接参数的读取，进而导致升级脚本无法正常执行。

解决方案

完整升级步骤

1. 备份现有数据：在进行任何升级操作前，务必完整备份当前数据库和数据文件。

2. 更新配置文件：

   • 确保/opt/archery/.env文件存在且配置正确
   • 检查docker-compose.yml中的镜像版本配置

3. 执行数据库升级：

   • 使用增量SQL脚本更新数据库结构
   • 对于已存在的字段错误，可手动修改升级脚本或临时注释相关语句

4. 容器更新：

   • 停止旧版本容器
   • 启动新版本容器
   • 监控日志确认服务正常运行

针对特定错误的处理

对于"Duplicate column name 'db_name'"错误，可以采取以下措施：

1. 编辑v1.10.0.sql脚本，注释或删除已存在字段的添加语句
2. 仅执行新增字段和表结构的变更部分
3. 手动验证每个变更语句的必要性

升级建议

1. 使用最新代码分支：考虑使用master分支而非特定版本进行升级，可能包含更多修复。

2. 分步验证：升级后逐步验证各功能模块，而非一次性全面切换。

3. 日志监控：升级过程中密切监控系统日志，及时发现并解决问题。

4. 回滚预案：准备完整的回滚方案，包括数据库备份和旧版本容器镜像。

总结

Archery项目版本升级过程中，数据库结构变更是需要特别关注的重点环节。通过系统化的升级流程、完善的备份机制和详细的日志分析，可以有效避免类似问题的发生。对于复杂系统的升级，建议在测试环境充分验证后再应用于生产环境。