故障排查

本指南帮助您解决 SonarQube connectors 的常见问题。

Connector 未就绪

症状

SonarQube connector 显示 Ready: False 状态。

诊断步骤

  1. 检查 connector 状态:

    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://)和路径

Scanner Job 失败

症状

sonar-scanner job 在分析期间失败或挂起。

诊断步骤

  1. 检查 job 日志:

    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”
    • 解决方案:验证 scanner 正在使用 connector 配置:
      SONAR_SCANNER_OPTS="-Dproject.settings=/scanner-config/sonar-project.properties"

    权限不足:

    • 错误:“Insufficient privileges” 或 “403 Forbidden”
    • 解决方案:验证令牌对项目具有 “Execute Analysis” 权限

    Scanner JRE 在 Alauda OS 节点上失败:

    • 错误:
      Error occurred during initialization of VM
      Failed to mark memory page as executable - check if grsecurity/PaX is enabled
    • 上下文:在 Alauda OS 或其他强化型节点镜像上,较新版本的 SonarScanner CLI 可能会在运行 scanner engine 之前自动预配 JRE。如果下载的 JRE 无法在节点安全策略下运行,则 scanner 容器可能会以退出代码 3 失败,即使 connector、代理、身份验证和 SonarQube 连接均正常工作。
    • 诊断:如果 scanner 日志显示其在 JVM 初始化错误之前已连接到 SonarQube 并下载 scanner engine 或 JRE,请将此问题视为 scanner 运行时兼容性问题,而不是 connector 身份验证问题。
    • 解决方案:当 scanner 镜像已提供的 Java runtime 与您的 SonarQube 版本兼容时,使用该 Java runtime:
      sonar-scanner -Dsonar.scanner.skipJreProvisioning=true
      您也可以设置等效的环境变量:
      SONAR_SCANNER_SKIP_JRE_PROVISIONING=true
    • 验证:在 scanner 镜像中运行 java -version,并在禁用 JRE 预配之前确认存在受支持的 Java runtime。

找不到配置

症状

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

诊断步骤

  1. 验证 CSI 卷配置正确:
    检查 Pod 规范中的 CSI 卷是否已正确配置,并设置了正确的 connectorName 和 configuration.names 属性。

  2. 常见原因和解决方案:

    Connector 未就绪:

    • 解决方案:等待 Connector 达到 Ready 状态
    • 只有当 Connector 处于 Ready 状态时,配置才可用

    卷配置不正确:

    • 解决方案:验证 CSI 卷配置包含:
      • connectorName:Connector 的名称
      • connectorNamespace:Connector 的命名空间
      • configuration.names:"sonar-scanner"

Quality Gate 失败

症状

分析已完成,但 Quality Gate 状态不符合预期。

诊断步骤

  1. 检查 SonarQube 项目监控面板,查看 Quality Gate 详细信息

  2. 常见原因和解决方案:

    Quality Profile 不匹配:

    • 解决方案:验证项目是否分配了正确的 Quality Profile

    未达到覆盖率阈值:

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

    新代码周期配置:

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

性能问题

症状

Scanner 运行时间过长或超时。

诊断步骤

  1. 常见原因和解决方案:

    代码库规模较大:

    • 解决方案:增加作业超时时间和资源限制:
      spec:
        activeDeadlineSeconds: 1800  # 30 minutes
        template:
          spec:
            containers:
            - name: sonar-scanner
              resources:
                limits:
                  memory: "2Gi"
                  cpu: "1000m"

    网络延迟:

    • 解决方案:检查与 SonarQube 实例的网络连接
    • 考虑使用距离集群更近的 SonarQube 实例

获取帮助

如果问题仍然存在:

  1. 检查 Connector 日志(将 <connectors-namespace> 替换为安装 Connectors 系统的命名空间——默认为 connectors-system,但可以配置):

    kubectl logs -n <connectors-namespace> -l app=connectors-proxy-service
  2. 查看 Connector 事件:

    kubectl get events -n <namespace> --field-selector involvedObject.name=<connector-name>
  3. 验证 SonarQube 实例运行状况:

    • 访问 SonarQube Web 界面
    • 直接检查 /api/system/status 端点
  4. 查阅文档: