#故障排除

本指南帮助您解决 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”权限

#配置未找到

#现象

Pod 挂载 sonar-project.properties 配置失败。

#诊断步骤

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

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

   连接器未就绪：

   • 解决方案：等待连接器达到 Ready 状态
   • 只有连接器就绪时配置才可用

   卷配置错误：

   • 解决方案：确认 CSI 卷配置包含：
     • connectorName：连接器名称
     • connectorNamespace：连接器所在命名空间
     • configuration.names："sonar-scanner"

#质量门失败

#现象

分析完成但质量门状态不符合预期。

#诊断步骤

1. 查看 SonarQube 项目监控面板，了解质量门详情

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

   质量配置文件不匹配：

   • 解决方案：确认项目分配了正确的质量配置文件

   覆盖率阈值未达标：

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

   新代码周期配置：

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

#性能问题

#现象

扫描器耗时过长或超时。

#诊断步骤

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

   代码库过大：

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

     spec:
       activeDeadlineSeconds: 1800  # 30 分钟
       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