SonarQube启动失败，提示“Database connection failed”，如何排查？

Question

SonarQube启动失败并报“Database connection failed”，常见原因有四类：①数据库服务未运行（如PostgreSQL/MySQL宕机）；②`conf/sonar.properties`中`sonar.jdbc.url`、`username`、`password`配置错误或权限不足；③JDBC驱动缺失（如`postgresql-42.x.jar`未放入`extensions/jdbc-driver/postgresql/`）；④网络/防火墙阻断（如容器间DNS不可达、端口被封）。排查建议：先`telnet db-host 5432`验证连通性；再用相同账号密码手动连接数据库确认凭证有效；检查`logs/sonar.log`中紧邻报错前的Caused by堆栈（常暴露具体异常如`Connection refused`或`Access denied`）；最后验证驱动版本与数据库兼容性（如PG 15需驱动≥42.6.0）。切忌忽略日志时序——首条ERROR往往非根因，需向上追溯ConnectionPool初始化失败记录。

Answer 1

```html

一、现象层：启动失败的表征与日志初筛

SonarQube 启动时抛出 Database connection failed 错误，表面看是连接异常，但本质是 HikariCP 连接池初始化失败的最终呈现。首条 ERROR 日志（如 Unable to start web server）常具误导性——需逆向扫描 sonar.log 中时间戳更早的 Caused by: 堆栈链。典型线索包括：java.net.ConnectException: Connection refused（网络/服务层）、java.sql.SQLException: Access denied for user（认证层）、java.lang.ClassNotFoundException: org.postgresql.Driver（类加载层）。

二、基础设施层：数据库服务状态验证

• 检查 PostgreSQL/MySQL 进程是否存活：systemctl status postgresql 或 docker ps | grep postgres
• 确认监听地址与端口：ss -tlnp | grep :5432（Linux），注意 postgresql.conf 中 listen_addresses 是否为 '*' 或含宿主机 IP
• 验证数据库健康度：pg_isready -h db-host -p 5432 -U sonar（返回 accepting connections 才为有效）

三、配置层：sonar.properties 的精准校验

配置项	典型错误示例	合规写法（PostgreSQL）
sonar.jdbc.url	jdbc:postgresql://localhost:5432/sonar（容器内 localhost ≠ 宿主机）	jdbc:postgresql://pg-db:5432/sonar?currentSchema=public&useSSL=false
sonar.jdbc.username	sonar（但数据库中该用户无 CREATEDB 权限）	需执行：ALTER USER sonar CREATEDB;

四、驱动层：JDBC 驱动的版本兼容性治理

驱动缺失或版本错配是高发隐性故障点。SonarQube 9.9+ 强制要求：

• PostgreSQL ≥ 13 → 需 postgresql-42.6.0.jar（PG 15 要求 ≥42.6.0）
• MySQL 8.0+ → 必须用 mysql-connector-java-8.0.33.jar，且 URL 含 serverTimezone=UTC

验证方式：ls -l extensions/jdbc-driver/postgresql/，并比对 jar -tf postgresql-42.6.0.jar | head -5 确认 Driver 类存在。

五、网络与安全层：跨环境通信的深度诊断

graph TD
  A[SonarQube容器] -->|telnet pg-db 5432| B[DNS解析]
  B --> C{解析成功？}
  C -->|否| D[检查 /etc/hosts 或 docker-compose network]
  C -->|是| E[端口可达性]
  E --> F{nc -zv pg-db 5432 成功？}
  F -->|否| G[防火墙/Security Group/SELinux拦截]
  F -->|是| H[凭据与权限复核]

六、日志时序分析法：根因定位的黄金路径

关键原则：拒绝“从报错第一行开始读”。正确顺序为：

1. 定位 INFO — Initializing Connection Pool 行（约启动后 3–8 秒）
2. 向下追踪至首次 WARN — Could not create connection
3. 捕获紧邻其上的 Caused by 异常（如 org.postgresql.util.PSQLException: The authentication type 10 is not supported 暴露 PG 认证协议不匹配）
4. 交叉验证 web.log 中 HikariPool-1 - Starting... 后是否出现 isClosed 相关警告

七、实战验证矩阵：四类原因的交叉验证清单

验证维度	数据库宕机	配置错误	驱动缺失	网络阻断
telnet db-host 5432	失败	成功	成功	失败
psql -h db-host -U sonar -d sonar	N/A	Access denied	Fatal: database "sonar" does not exist（驱动不影响此命令）	Connection refused
grep "Driver" sonar.log	无输出	无输出	ClassNotFoundException	无输出

八、高级陷阱：容器化部署中的特有雷区

Docker/K8s 环境下需额外关注：

• DNS 缓存：K8s CoreDNS 可能缓存旧 Service IP，执行 kubectl exec -it sonar-pod -- cat /etc/resolv.conf 确认 nameserver
• InitContainer 依赖：若使用 initContainers 等待 DB 就绪，需检查其 exit code 是否为 0
• Volume 权限：extensions/jdbc-driver/ 目录在 OpenShift 等平台可能被 SELinux 标记为 container_file_t，导致类加载失败

九、自动化诊断脚本：一线运维的提效利器

#!/bin/bash
# sonar-db-check.sh
echo "=== Step 1: DB Service Status ==="
docker exec pg-db pg_isready -U sonar 2>&1 || echo "PG not ready"

echo "=== Step 2: Network Reachability ==="
timeout 3 bash -c 'cat < /dev/null > /dev/tcp/pg-db/5432' 2>/dev/null && echo "Port open" || echo "Port blocked"

echo "=== Step 3: Credential Validation ==="
docker exec sonarqube bash -c 'psql -h pg-db -U sonar -d sonar -c "SELECT 1" 2>/dev/null && echo "Auth OK" || echo "Auth FAIL"'

十、版本演进视角：SonarQube 9.x 与 10.x 的驱动策略差异

SonarQube 10.0+ 已移除内置 JDBC 驱动，强制外部挂载；而 9.9 仍支持 lib/jdbc/ 目录自动加载。升级时若未迁移驱动位置，将触发静默类加载失败——此时 sonar.log 不报 ClassNotFoundException，仅在 Hikari 初始化阶段抛出泛化连接异常。解决方案：严格遵循 官方文档 的驱动部署路径规范，禁用任何 CLASSPATH 注入式 hack。

```