#故障排查

本指南帮助你解决 SonarQube 连接器的常见问题。

#连接器未就绪

#症状

SonarQube 连接器显示 Ready: False 状态。

#诊断步骤

1. 检查连接器状态：

   kubectl get connector <connector-name> -n <namespace> -o yaml

   查看 status.conditions 字段以获取具体错误消息。

2. 常见原因及解决方案：

   令牌无效：

   • 错误："Authentication failed" 或 "Token invalid"
   • 解决方案：验证 secret 中的令牌是否正确且未过期
   • 在 SonarQube 中生成新令牌并更新 secret

   连接问题：

   • 错误："Connection refused" 或 "Timeout"
   • 解决方案：验证集群是否能够访问 SonarQube 实例
   • 检查网络策略、防火墙和 DNS 解析

   地址不正确：

   • 错误："404 Not Found" 或 "Invalid URL"
   • 解决方案：验证 spec.address 是否包含正确的协议（https://）和路径

#扫描器作业失败

#症状

sonar-scanner 作业在分析过程中失败或挂起。

#诊断步骤

1. 检查作业日志：

   kubectl logs job/<job-name> -n <namespace>

2. 常见原因及解决方案：

   缺少 sonar-project.properties：

   • 错误："You must define the following mandatory properties"
   • 解决方案：确保 sonar-project.properties 存在于项目根目录中，并包含所需字段：

     sonar.projectKey=my-project-key
     sonar.sources=.

   代理配置未加载：

   • 错误："Authentication required"
   • 解决方案：验证扫描器正在使用连接器配置：

     SONAR_SCANNER_OPTS="-Dproject.settings=/scanner-config/sonar-project.properties"

   权限不足：

   • 错误："Insufficient privileges" 或 "403 Forbidden"
   • 解决方案：验证令牌是否具有项目的 "Execute Analysis" 权限

   Scanner JRE 在 MicroOS 节点上失败：

   • 错误：

     Error occurred during initialization of VM
     Failed to mark memory page as executable - check if grsecurity/PaX is enabled
   • 背景：在 MicroOS 或其他加固过的节点镜像上，新版 SonarScanner CLI 可能会在运行扫描器引擎之前自动配置 JRE。如果下载的 JRE 无法在节点安全策略下运行，即使连接器、代理、身份验证以及到 SonarQube 的连通性都正常，扫描器容器仍可能以退出码 3 失败。
   • 诊断：如果扫描器日志显示它已连接到 SonarQube，并且在 JVM 初始化错误之前已下载扫描器引擎或 JRE，则应将其视为扫描器运行时兼容性问题，而不是连接器身份验证问题。
   • 解决方案：在与 SonarQube 版本兼容时，使用扫描器镜像已提供的 Java 运行时：

     sonar-scanner -Dsonar.scanner.skipJreProvisioning=true
     你也可以设置等效的环境变量：

     SONAR_SCANNER_SKIP_JRE_PROVISIONING=true
   • 验证：在扫描器镜像中运行 java -version，并确认在禁用 JRE provisioning 之前已提供受支持的 Java 运行时。

#未找到配置

#症状

Pod 无法挂载 sonar-project.properties 配置。

#诊断步骤

1. 验证 CSI 卷是否正确配置： 检查 Pod 规范中的 CSI 卷是否已正确配置，并包含适当的 connectorName 和 configuration.names 属性。

2. 常见原因及解决方案：

   连接器未就绪：

   • 解决方案：等待连接器达到 Ready 状态
   • 仅当连接器处于 Ready 状态时，配置才可用

   卷配置不正确：

   • 解决方案：验证 CSI 卷配置是否包含：
     • connectorName：你的连接器名称
     • connectorNamespace：你的连接器命名空间
     • configuration.names："sonar-scanner"

#质量门禁失败

#症状

分析完成，但质量门禁状态与预期不符。

#诊断步骤

1. 检查 SonarQube 项目监控面板，查看质量门禁详细信息

2. 常见原因及解决方案：

   质量配置文件不匹配：

   • 解决方案：验证是否为项目分配了正确的质量配置文件

   未达到覆盖率阈值：

   • 解决方案：检查项目是否具有测试覆盖率数据
   • 确保在分析之前已生成覆盖率报告

   新代码周期配置：

   • 解决方案：验证 SonarQube 中的新代码周期定义

#性能问题

#症状

扫描器耗时过长或超时。

#诊断步骤

1. 常见原因及解决方案：

   代码库较大：

   • 解决方案：增加作业超时时间和资源限制：

     spec:
       activeDeadlineSeconds: 1800  # 30 minutes
       template:
         spec:
           containers:
           - name: sonar-scanner
             resources:
               limits:
                 memory: "2Gi"
                 cpu: "1000m"

   网络延迟：

   • 解决方案：检查到 SonarQube 实例的网络连通性
   • 考虑使用更靠近集群的 SonarQube 实例

#获取帮助

如果你仍然遇到问题：

1. 检查连接器日志：

   kubectl logs -n connectors-system -l app=connectors-proxy-service

2. 查看连接器事件：

   kubectl get events -n <namespace> --field-selector involvedObject.name=<connector-name>

3. 验证 SonarQube 实例运行状况：

   • 访问 SonarQube Web 界面
   • 直接检查 /api/system/status 端点

4. 查阅文档：

   • SonarQube ConnectorClass