故障排查
本指南帮助您解决 SonarQube 连接器的常见问题。
连接器未就绪
症状
SonarQube 连接器显示 Ready: False 状态。
排查步骤
-
检查连接器状态:
查看
status.conditions字段中的具体错误信息。 -
常见原因与解决方案:
无效令牌:
- 错误:"Authentication failed" 或 "Token invalid"
- 解决方案:验证 Secret 中的令牌是否正确且未过期
- 在 SonarQube 中生成新的令牌并更新 Secret
连接问题:
- 错误:"Connection refused" 或 "Timeout"
- 解决方案:验证集群是否可以访问 SonarQube 实例
- 检查网络策略、防火墙和 DNS 解析
地址不正确:
- 错误:"404 Not Found" 或 "Invalid URL"
- 解决方案:验证
spec.address是否包含正确的协议(https://)和路径
扫描器 Job 失败
症状
sonar-scanner Job 在分析过程中失败或挂起。
排查步骤
-
检查 Job 日志:
-
常见原因与解决方案:
缺少 sonar-project.properties:
- 错误:"You must define the following mandatory properties"
- 解决方案:确保项目根目录下存在 sonar-project.properties,并包含所需字段:
未加载代理配置:
- 错误:"Authentication required"
- 解决方案:验证扫描器是否正在使用连接器配置:
权限不足:
- 错误:"Insufficient privileges" 或 "403 Forbidden"
- 解决方案:验证该令牌是否对项目具有 "Execute Analysis" 权限
Scanner JRE 在 Alauda OS 节点上失败:
- 错误:
- 背景:在 Alauda OS 或其他加固型节点镜像上,较新的 SonarScanner CLI 版本可能会在运行 scanner engine 之前自动预配 JRE。如果下载的 JRE 无法在节点安全策略下运行,即使连接器、代理、认证以及 SonarQube 连通性都正常,scanner 容器仍可能以退出码
3失败。 - 排查:如果 scanner 日志显示它已连接到 SonarQube,并在 JVM 初始化错误之前下载了 scanner engine 或 JRE,应将其视为 scanner 运行时兼容性问题,而不是连接器认证问题。
- 解决方案:在与您的 SonarQube 版本兼容时,使用 scanner image 中已提供的 Java 运行时: 您也可以设置等效的环境变量:
- 验证:在 scanner image 中运行
java -version,并确认在禁用 JRE 预配之前可用的 Java 运行时是受支持的版本。
未找到配置
症状
Pod 无法挂载 sonar-project.properties 配置。
排查步骤
-
验证 CSI volume 配置是否正确: 检查 Pod 规范中的 CSI volume 是否使用了正确的
connectorName和configuration.names属性进行配置。 -
常见原因与解决方案:
连接器未就绪:
- 解决方案:等待连接器进入 Ready 状态
- 只有当连接器处于 Ready 状态时,配置才可用
卷配置不正确:
- 解决方案:验证 CSI volume 配置是否包含:
connectorName:您的连接器名称connectorNamespace:您的连接器所在命名空间configuration.names:"sonar-scanner"
质量门失败
症状
分析已完成,但质量门状态并非预期结果。
排查步骤
-
检查 SonarQube 项目 dashboard 以查看质量门详情
-
常见原因与解决方案:
质量配置文件不匹配:
- 解决方案:验证是否已将正确的质量配置文件分配给项目
未达到覆盖率阈值:
- 解决方案:检查项目是否具有测试覆盖率数据
- 确保在分析前已生成覆盖率报告
新代码周期配置:
- 解决方案:验证 SonarQube 中的新代码周期定义
性能问题
症状
扫描器耗时过长或超时。
排查步骤
-
常见原因与解决方案:
代码库过大:
- 解决方案:增加 Job 超时时间和资源限制:
网络延迟:
- 解决方案:检查到 SonarQube 实例的网络连通性
- 考虑使用距离集群更近的 SonarQube 实例
获取帮助
如果您仍然遇到问题:
-
检查连接器日志(将
<connectors-namespace>替换为安装 Connectors 系统的命名空间——默认为connectors-system,但可配置): -
查看连接器事件:
-
验证 SonarQube 实例健康状态:
- 访问 SonarQube Web 界面
- 直接检查
/api/system/status端点
-
查阅文档: