在香港服务器部署SonarQube前,怎样核对Java与数据库依赖?
香港服务器能否顺利部署 SonarQube,不能只看“服务器已经安装了 Java”或“数据库端口可以访问”。交付前应先锁定 SonarQube 的具体版本、部署方式和数据库产品,再按该版本的支持矩阵核对服务端 Java、扫描端 Java、数据库版本、字符集、账号权限及跨地域连接条件。
其中,服务端使用的 JDK 与项目构建阶段使用的 Java 不一定相同;数据库端口连通也不等于账号具备建表、建索引和执行升级迁移的权限。香港服务器还需要单独确认数据库是否位于相同网络区域、DNS 是否解析到预期地址、TLS 证书是否可验证,以及服务器和数据库的时间是否同步。以下内容可作为上线前的验收清单。
版本基线先行:先确认“支持什么”,再检查“已经装了什么”
1. 固定 SonarQube 版本、版本类型和部署方式
先把以下信息写入交付记录:
| 对象 | 需要固定的内容 | 判断依据 |
|---|---|---|
| SonarQube | 完整版本号,而不是只写 9.x、10.x 或最新版 | 必须能够对应到明确的服务端与数据库支持矩阵 |
| 版本类型 | 长期支持版本、普通版本或商业版本 | 不同版本的升级路径、支持周期和依赖要求可能不同 |
| 部署方式 | 二进制包、Docker 容器或其他编排方式 | 决定 Java 是读取宿主机,还是使用镜像内运行时 |
| 服务器架构 | x86_64、ARM64 等 | 需要确认该架构与目标版本、JDK 发行包兼容 |
| 数据库 | PostgreSQL、Microsoft SQL Server 或 Oracle 等具体产品 | 只能使用该 SonarQube 版本支持的数据库产品和主版本 |
| 扫描方式 | SonarScanner CLI、Maven、Gradle、.NET 等 | 扫描器使用的运行环境与服务端 JDK 是两套核对对象 |
“安装了较新的 Java”不能代替版本兼容性判断。例如,SonarQube 9.9 LTS 及不少 10.x 版本的服务端通常以 Java 17 为运行基线,但某个更高版本的 Java 是否受支持,仍应以目标 SonarQube 版本的要求为准。Java 21 能够启动某个程序,也不代表它已经被当前版本列入支持范围。
2. 不能用“最新版数据库”替代版本矩阵
数据库版本要核对到主版本,必要时还要核对小版本、补丁级别和数据库发行版。常见的可选产品包括 PostgreSQL、Microsoft SQL Server 和 Oracle,但具体可用范围取决于 SonarQube 版本及部署形态。
以下情况不能直接放行:
- 数据库产品不在目标版本的支持列表中;
- 只确认“数据库服务正常”,没有确认具体主版本;
- 使用 MySQL、MariaDB 等未列入支持矩阵的产品,并试图通过更换 JDBC 驱动接入;
- 数据库版本过新,尚未被目标 SonarQube 版本验证;
- 数据库使用了业务系统已有的复杂排序规则、字符集或兼容模式,但没有完成兼容性核对。
版本矩阵无法覆盖时,正确处理方式不是凭经验判断,而是将 SonarQube 降级到已验证的版本、调整数据库版本,或先在相同环境中完成试运行。
Java:分别验收服务端运行时和扫描端运行时
1. 服务端 Java 要看“实际启动进程”
服务端 Java 是 SonarQube Web 服务及其后台组件启动时使用的 JDK。通过 SSH 登录后执行 java -version,只能说明当前 Shell 找到的 Java,不一定是 systemd 服务真正使用的 Java。
可先检查当前环境:
java -version
command -v java
readlink -f "$(command -v java)"
printf 'JAVA_HOME=%s\n' "${JAVA_HOME:-未设置}"
如果使用 systemd,还应确认服务用户、启动命令和环境变量:

systemctl show sonarqube -p User -p ExecStart -p Environment
systemctl cat sonarqube
将 sonarqube 替换为实际服务名。若服务使用专用账号和固定 JDK 路径,还可以在相同账号下验证:
sudo -u sonarqube -- /opt/jdk-17/bin/java -version
通过标准应同时满足以下条件:
- 实际启动 SonarQube 的 Java 版本处于目标版本支持范围;
- Java 的位数与服务器架构匹配;
- 服务用户能够执行 Java 文件;
JAVA_HOME、PATH和 systemd 中的启动路径没有相互矛盾;- 重启服务后仍使用同一个 JDK,而不是依赖管理员登录环境;
- JDK 的证书库、时区数据和系统时间能够满足 HTTPS 与数据库 TLS 校验需要。
若交付记录写的是 Java 17,但 systemctl 显示服务实际调用的是 /usr/bin/java,就不能仅凭记录放行。应先统一路径,再重启并重新留证。
2. 不要把 JRE、JDK 和扫描器环境混为一谈
SonarQube 服务端、构建工具和扫描器可能运行在不同主机,甚至由不同容器执行:

- SonarQube 服务端需要满足服务端要求的 JDK;
- Maven 或 Gradle 扫描通常使用构建机启动 Maven、Gradle 时的 Java;
- SonarScanner CLI 使用自身的运行时或系统 Java,具体取决于安装包;
- .NET 项目主要依赖 .NET SDK,但扫描器仍可能通过 Java 或内置运行时完成部分工作;
- Docker 部署时,宿主机安装的 Java 不一定会被容器使用。
因此,构建机上还要单独记录扫描器类型和执行环境。例如 Maven 项目可以检查:
mvn -version
java -version
Gradle 项目可以检查:
./gradlew --version
java -version
如果使用 SonarScanner CLI,则应确认其版本、安装位置和实际调用的 Java:
sonar-scanner --version
command -v sonar-scanner
部分较新的扫描器安装包可能自带 Java 运行时,但不能据此跳过核对。需要查看该安装包的说明,并通过实际执行命令确认运行时来源。
判断时要区分两类问题:
- SonarQube 页面打不开、后台进程起不来:优先检查服务端 JDK;
- 构建任务报 Java 版本、类版本或扫描器启动错误:优先检查构建机或扫描器 JDK;
- 扫描完成但报告无法上传:再检查服务端地址、令牌、网络和权限,不要把所有问题都归因于 Java。
3. 检查 JDK 的来源、架构和服务限制
生产环境不建议混用多个来源不明的 JDK。应记录发行版名称、完整版本、安装路径和架构。可以使用以下命令查看 Java 属性:
java -XshowSettings:properties -version 2>&1 | \
egrep 'java.version|java.home|os.arch|file.encoding|user.timezone'
重点核对:
java.home是否指向预期 JDK;os.arch是否与服务器架构相符;file.encoding是否导致日志或项目名称出现异常;user.timezone是否与团队的时间记录约定一致;- JDK 的 CA 证书库是否包含数据库或反向代理使用的证书链。
SonarQube 运行还会涉及搜索与索引组件,因此 Linux 主机的文件描述符、进程数和内核映射参数也不能完全忽略。常见检查命令如下:
ulimit -n
sysctl vm.max_map_count
systemctl show sonarqube -p LimitNOFILE -p TasksMax
这些命令只读取当前值,不会修改系统。若需要调整 sysctl、systemd 限制或服务账号权限,应在维护窗口执行,先记录原值,确认影响范围后再变更;回滚时恢复原配置并重启受影响服务。不要为了让服务启动而直接使用 root 运行 SonarQube。
数据库:核对产品、版本、字符集和账号能力
1. 数据库必须是专用、可迁移的目标库
生产 SonarQube 不应使用嵌入式 H2 数据库作为长期存储。H2 更适合测试、演示或短期验证,不能作为正式交付数据库的替代品。
正式环境至少应确认:
- 数据库产品和主版本在支持矩阵中;
- SonarQube 使用独立数据库,不能与核心业务表混用;
- 数据库实例、数据库名和账号都已经明确;
- 数据库所在位置与香港服务器之间的网络路径已验证;
- 数据库具备备份、恢复和监控能力;
- SonarQube 升级时仍有执行必要迁移的权限。
“独立数据库”不一定要求独立物理服务器,但应至少使用独立数据库或独立实例边界。将 SonarQube 表直接放入订单、用户、财务等业务数据库,会增加表名冲突、权限扩大、升级影响和恢复范围,验收时应判定为高风险方案。
2. 核对数据库版本和字符集
以 PostgreSQL 为例,应从香港服务器或 SonarQube 容器内部执行查询,而不是只在数据库管理员电脑上查询:
psql "host=db.example.com port=5432 dbname=sonarqube user=sonarqube sslmode=require" \
-c "select version(), current_database(), current_user;"
确认数据库编码和区域设置:
psql "host=db.example.com port=5432 dbname=sonarqube user=sonarqube sslmode=require" \
-c "show server_encoding; show lc_collate; show lc_ctype;"
对于 PostgreSQL,通常应重点确认编码为 UTF8,并将排序规则、区域设置与目标 SonarQube 版本要求进行比对。使用 Microsoft SQL Server 或 Oracle 时,不应套用 PostgreSQL 的判断命令,而应按照对应产品的数据库要求检查字符集、排序规则、兼容级别和连接驱动。
数据库“能接受中文”不等于数据库条件完全合格。排序规则或大小写敏感性不合适,可能在初始化、升级或检索数据时产生隐蔽问题。已有业务库即使编码正确,也不代表适合直接作为 SonarQube 数据库。
3. 核对账号权限,但不要直接授予超级管理员权限
SonarQube 数据库账号不是只读账号。首次初始化和后续版本升级可能需要创建或修改表、索引、约束等对象。权限应满足目标版本文档要求,但不应为了省事直接使用数据库超级管理员。
以 PostgreSQL 默认 public schema 为例,可以进行只读权限检查:
psql "host=db.example.com port=5432 dbname=sonarqube user=sonarqube sslmode=require" \
-c "select has_database_privilege(current_user, current_database(), 'CONNECT');"
psql "host=db.example.com port=5432 dbname=sonarqube user=sonarqube sslmode=require" \
-c "select has_schema_privilege(current_user, 'public', 'USAGE'), \
has_schema_privilege(current_user, 'public', 'CREATE');"
如果使用了其他 schema,应将 public 换成实际 schema,并确认该版本是否支持自定义 schema。不能只检查数据库端口开放,还要验证以下内容:
- 账号可以连接目标数据库,而不是只连接默认数据库;
- 账号密码没有过期,认证方式与客户端驱动匹配;
- 账号拥有目标版本初始化和升级所需的对象权限;
- 账号不是业务系统共用账号;
- 账号密码不会直接写入 Shell 历史、工单或公开配置;
- 数据库管理员已经明确后续升级是否仍由该账号执行迁移。
如果权限不足,先确认是否是新建空库。对空库调整账号权限通常影响较小;若数据库已经初始化或正在被使用,应先备份并安排维护窗口。不要在生产数据库上直接试验权限修改,也不要通过删除表、重建 schema 等方式“重新初始化”。
4. 先做连接测试,再做代表性分析
从 SonarQube 所在主机测试数据库端口:
nc -vz db.example.com 5432
这个命令只能证明 TCP 端口路径基本可达,不能证明账号认证成功。真正有意义的验证是使用与 SonarQube 相同的地址、端口、数据库名、账号和 TLS 条件执行一次 psql 登录查询。
数据库连接验收应分为三层:
| 层次 | 核对内容 | 通过标准 |
|---|---|---|
| 网络层 | 服务器到数据库 IP 和端口 | TCP 可达,且防火墙只允许必要来源 |
| 认证层 | 数据库名、账号、密码、TLS | 能够完成认证并执行只读查询 |
| 应用层 | SonarQube JDBC 参数和迁移能力 | 服务能够初始化、读取和写入自己的表 |
如果启用了数据库 SSL,Java 的信任库必须能够验证数据库证书链。证书主机名、有效期、签发链和服务器时间任一项不匹配,都可能表现为“数据库端口正常但 SonarQube 启动失败”。
5. 检查容量、连接数和恢复条件
SonarQube 数据库增长量不只取决于源代码仓库大小,还与项目数量、分支数量、分析频率、问题历史和保留策略有关。容量验收应使用实际项目规模估算,而不是给所有环境套用一个固定磁盘值。
建议至少记录:
- 数据库当前占用空间和可用空间;
- 数据库磁盘类型及 I/O 监控方式;
- SonarQube 预计并发分析数;
- 数据库最大连接数以及其他业务连接占用;
- 备份频率、备份保留周期和最近一次恢复演练结果;
- 分析历史清理策略及其执行窗口。
例如,一个只有几十个项目的测试环境可以采用较小的数据库规格,但拥有数百个项目、多个长期分支并且每天多次分析的环境,数据库写入和索引压力会明显增加。此时即便 Java 服务能够正常启动,也不能据此判断数据库容量合格。
面向SonarQube代码质量平台的部署需求,A5数据提供香港Xeon Gold与AMD EPYC物理服务器,以多档内存和SSD、NVMe存储资源,为Java服务运行、数据库缓存及分析数据读写提供硬件基础,也能支撑服务端、数据库与构建任务分机部署。香港产品的CN2与国际带宽方案可衔接不同地区的研发访问和扫描结果上传需求,大容量存储系列则可用于自建备份与分析资料归档。
香港服务器特有的网络、时间和位置核对
1. 服务器所在地区不等于数据库所在地区
“香港服务器”只说明 SonarQube 主机的位置,数据库可能仍位于其他地区、其他云厂商或本地机房。验收时应单独记录:
- SonarQube 服务器所在区域和可用区;
- 数据库所在区域和可用区;
- 使用公网、专线、云内网还是其他网络路径;
- 数据库白名单允许的实际出口 IP;
- 数据是否需要留在指定地区;
- 跨区域传输是否符合组织的合规要求。
SonarQube 与数据库之间存在较多事务和索引操作。数据库放在远端并不一定无法使用,但网络延迟、丢包和抖动会累积到初始化、项目分析和后台任务中。若数据库位于香港以外,不要只在办公电脑上测试,也不要只执行一次 ping。应从 SonarQube 主机或容器内部完成 TCP 和数据库登录测试,并使用一个代表性项目完成完整分析。
没有适用于所有版本和项目规模的统一延迟阈值。作为实施判断,若同区域内网连接稳定且延迟较低,通常更容易控制;若跨区域连接长期达到数十毫秒甚至更高,就应把代表性分析耗时、后台任务积压和数据库响应纳入验收,而不能仅凭端口可达放行。
2. DNS、出口和防火墙规则要按通信方向确认
至少区分三条通信方向:

- 管理员或扫描器到 SonarQube Web 地址;
- SonarQube 服务端到数据库地址;
- 反向代理到 SonarQube 内部 Web 端口。
SonarQube 默认 Web 端口常见为 9000,PostgreSQL 默认端口常见为 5432,SQL Server 和 Oracle 使用不同默认端口;实际端口以部署配置为准。防火墙不应简单地对公网开放数据库端口,数据库入站规则通常只允许 SonarQube 服务器的固定私网地址或安全组来源。
验收记录应包含:
- 从 SonarQube 主机解析到的数据库 IP;
- 实际使用的数据库端口;
- 防火墙或安全组的来源、目标和方向;
- 反向代理是否正确转发 Host、协议和路径;
- 扫描器所在构建网络是否能够访问 SonarQube;
- DNS 变更后是否仍能解析到正确地址。
若使用公网数据库地址,应特别检查 NAT 后的出口地址是否与数据库白名单一致。很多“本地工具可以连接、服务器连接失败”的问题,实际是白名单记录了管理员电脑 IP,而不是香港服务器的出口 IP。
3. 时间同步直接影响 Java 和数据库认证
服务器、数据库和反向代理的系统时间应保持同步,时区可以不同,但时间基准不能明显漂移。时间异常可能导致:
- TLS 证书被判断为尚未生效或已经过期;
- 扫描令牌、会话和日志时间难以对应;
- 数据库连接认证失败;
- 分析记录的时间顺序异常。
可以先查看香港服务器的时间状态:
timedatectl status
date -u
同时向数据库管理员确认数据库主机的时间同步状态。生产环境建议统一使用可信 NTP 来源,并在交付记录中写明采用 UTC 还是本地时区展示。不要为了“让日志时间一致”临时修改系统时间,这可能影响其他服务和证书验证。
用空库和代表性项目完成最终放行
1. 空库验证适合检查依赖,不适合替代生产迁移演练
在正式接入前,应准备一个与生产版本、JDK、数据库产品和网络路径一致的空数据库。空库验证可以发现:
- 服务端 JDK 不兼容;
- JDBC 驱动或 TLS 信任链错误;
- 数据库账号缺少建表、建索引或写入权限;
- 字符集、排序规则和连接参数不匹配;
- 数据库跨区域连接不稳定;
- systemd 服务用户无法读取目录或启动 Java。
如果目标是升级已有 SonarQube,不应直接拿生产库进行首次试验。应先完成数据库备份或云数据库快照,再在副本或恢复环境执行迁移演练。迁移期间可能锁定对象、增加磁盘占用或影响服务,不应在业务高峰期操作。
2. 代表性项目比“登录成功”更能说明环境合格
测试项目应尽量覆盖实际交付中会出现的情况,例如:
- Java、JavaScript、Python 等主要语言;
- 多模块构建;
- 较大的依赖目录或生成目录;
- 多分支分析;
- 实际使用的构建工具和扫描器;
- 通过反向代理访问 SonarQube 的场景。
验收时记录以下结果:

| 验收动作 | 重点观察 |
|---|---|
| SonarQube 服务启动 | Web 进程、后台任务和日志无持续性依赖错误 |
| 数据库初始化 | 能创建所需对象,且没有权限或字符集异常 |
| 扫描器执行 | 构建机 Java 与扫描器版本匹配 |
| 报告上传 | 扫描器能够访问香港服务器的 SonarQube 地址 |
| 后台处理 | 分析任务能够从队列进入完成状态 |
| 重启后复核 | 重启服务后仍使用预期 JDK、数据库连接和配置 |
| 备份恢复演练 | 数据库备份可读取,恢复后的 SonarQube 数据可用 |
“页面能打开”只能证明 Web 层部分正常;只有数据库写入、扫描上传和后台处理都完成,才能说明 Java 与数据库依赖基本通过验收。
放行记录与常见异常处理
建议将以下内容作为交付附件或变更单的一部分:
- SonarQube 完整版本和版本类型;
- 服务端实际 JDK 路径、发行版、版本和架构;
- 扫描器类型、构建工具和构建机 Java 版本;
- 数据库产品、主版本、数据库名和部署区域;
- 数据库字符集、排序规则和 TLS 配置;
- 数据库账号权限检查结果;
- 从香港服务器执行的连通性和认证测试结果;
- 代表性项目的扫描耗时、后台任务结果和日志;
- 备份位置、恢复验证记录和回滚负责人;
- 尚未满足的条件、临时豁免期限和后续整改时间。
常见异常可以按对象处理,而不是笼统地重装全部组件:
| 异常表现 | 优先核对对象 | 处理方向 |
|---|---|---|
| 服务启动后立即退出 | 服务实际使用的 JDK、架构和系统限制 | 修正 JDK 路径或运行参数,保留原配置以便回滚 |
| 数据库端口可达但连接失败 | 数据库名、账号、TLS、白名单 | 从 SonarQube 主机重新认证,不要只在本地电脑测试 |
| 初始化时报权限错误 | 数据库账号的对象权限和目标 schema | 按版本要求补充权限,禁止直接改用超级管理员 |
| 扫描器启动失败 | 构建机 Java、扫描器版本和项目构建工具 | 单独修复扫描端环境,不要修改服务端 JDK |
| 分析上传成功但后台长时间不完成 | 数据库延迟、磁盘 I/O、连接数和后台队列 | 使用代表性项目复测,并检查数据库所在区域 |
| 重启后恢复到旧 Java | systemd 的 ExecStart、环境变量和软链接 | 固定服务路径后重启验证,记录变更前配置 |
只有当版本矩阵、服务端 JDK、扫描端运行时、数据库产品与版本、账号权限、香港服务器到数据库的实际路径,以及空库和代表性分析结果都能对应起来,SonarQube 部署才具备可交付条件。任何一项只能通过“端口开放”或“命令能执行”证明的内容,都不应直接替代应用层验收。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/3368.html



