SonarQube LTA 升级与数据库迁移指南：从旧版本到 8.9/9.9/2025 LTA

SonarQube 升级不能简单覆盖目录。尤其从旧版本升级到 LTA / LTS 版本时，需要关注数据库支持、Java 版本、插件兼容、Elasticsearch 索引、升级路径和回滚方案。

本文保留一次从 SonarQube 7.6 升级到 7.9.6 LTS，再升级到 8.9.6 LTS 的实践，并补充当前升级时应该遵守的通用原则。

CI/CD 系列文章

本文属于 Jenkins + GitLab + SonarQube CI/CD 系列，相关内容可以继续阅读：

• Git 提交规范实践：Conventional Commits、Commitizen 与 CHANGELOG 自动生成
• GitLab Docker 部署与 Personal Access Token 配置指南
• Jenkins 安装部署与 JDK、Maven、Agent 构建环境配置
• GitLab Webhook 触发 Jenkins Pipeline：Push、Tag 与 Merge Request 自动构建
• Jenkins 基于 GitLab 分支与 Tag 的自动化打包发布实践
• Jenkins 集成 SonarQube：代码扫描、质量门禁与 Pipeline 实践
• SonarQube Docker 部署与 Java 项目静态代码分析指南
• SonarQube for IDE 使用指南：IntelliJ 安装、Connected Mode 与规则同步
• SonarQube LTA 升级与数据库迁移指南：从旧版本到 8.9/9.9/2025 LTA

升级原则

• 先读官方升级路径，不要盲目跨版本。
• 先备份数据库和 SonarQube Home。
• 先在测试环境演练。
• 检查 Java、数据库、插件兼容性。
• 不要直接复制旧版本配置文件覆盖新版本。
• 升级后访问 /setup 完成数据库升级。

旧案例：7.6 -> 7.9.6 -> 8.9.6

历史背景：SonarQube 7.9 之后不再支持 MySQL，因此旧环境如果使用 MySQL，需要先迁移到 PostgreSQL。

推荐路径：

7.6 + MySQL -> 7.6 + PostgreSQL -> 7.9.6 LTS -> 8.9.6 LTS

MySQL 迁移到 PostgreSQL

使用官方迁移工具前，先完整备份数据库。

源配置：

sonar.jdbc.url=jdbc:mysql://old-host:3306/sonar
sonar.jdbc.username=sonar
sonar.jdbc.password=sonar

目标配置：

sonar.jdbc.url=jdbc:postgresql://new-host:5432/sonar
sonar.jdbc.username=sonar
sonar.jdbc.password=sonar

迁移后删除旧 Elasticsearch 索引目录，让 SonarQube 重建索引。

升级执行步骤

1. 停止旧 SonarQube。
2. 备份数据库。
3. 备份 SonarQube 安装目录和扩展插件。
4. 下载目标版本。
5. 按新版本模板重新配置 sonar.properties。
6. 检查 Java 版本。
7. 检查插件兼容性。
8. 启动新版本。
9. 访问 /setup 执行数据库升级。
10. 验证项目、规则、质量门禁和扫描任务。

插件兼容

升级前要检查：

• 中文插件。
• PDF 插件。
• P3C 插件。
• 自定义规则插件。

不兼容插件可能导致 SonarQube 启动失败。建议先移除第三方插件，升级成功后逐个验证。

回滚方案

升级一旦执行数据库迁移，不能简单降级。回滚依赖升级前备份：

• 恢复旧数据库。
• 恢复旧 SonarQube 目录。
• 恢复旧插件。
• 恢复旧 Java 环境。

当前版本注意事项

SonarSource 现在使用 LTA 等版本节奏。升级时应根据当前官方文档确定路径，例如从旧 LTS/LTA 逐级升级到目标 LTA。不要只照搬 7.6 -> 8.9 的旧路径。

常见问题

1. 启动失败

检查 Java 版本、数据库连接、插件兼容和日志。

2. 页面提示需要 setup

访问：

http://<host>:9000/setup

按提示完成数据库升级。

3. 扫描任务失败

检查 Scanner 版本、Token、项目 Key、JDK 和质量配置。

参考资料

• SonarQube 升级路径
• SonarQube Server 安装文档
• SonarQube Docker 安装