故障排除
本指南可帮助您解决 SonarQube connectors 的常见问题。
Connector 未就绪
症状
SonarQube connector 显示 Ready: False 状态。
诊断步骤
-
检查 connector 状态:
检查
status.conditions字段以获取具体错误消息。 -
常见原因和解决方案:
令牌无效:
- 错误:“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 在分析期间失败或挂起。
诊断步骤
-
检查 job 日志:
-
常见原因和解决方案:
缺少 sonar-project.properties:
- 错误:“You must define the following mandatory properties”
- 解决方案:确保项目根目录中存在 sonar-project.properties,并包含必需字段:
未加载代理配置:
- 错误:“Authentication required”
- 解决方案:验证 scanner 正在使用 connector 配置:
权限不足:
- 错误:“Insufficient privileges” 或 “403 Forbidden”
- 解决方案:验证令牌对项目具有“Execute Analysis”权限
Scanner JRE 在 Alauda OS 节点上失败:
- 错误:
- 上下文:在 Alauda OS 或其他强化型节点映像上,较新版本的 SonarScanner CLI 可能会在运行 scanner engine 前自动配置 JRE。如果下载的 JRE 无法在节点安全策略下运行,即使 connector、代理、身份验证和 SonarQube 连接均正常,scanner 容器也可能以退出代码
3失败。 - 诊断:如果 scanner 日志显示其在 JVM 初始化错误之前已连接到 SonarQube 并下载 scanner engine 或 JRE,则应将此问题视为 scanner 运行时兼容性问题,而不是 connector 身份验证问题。
- 解决方案:当 scanner image 提供的 Java 运行时与您的 SonarQube 版本兼容时,使用该运行时: 您也可以设置等效的环境变量:
- 验证:在 scanner image 中运行
java -version,并在禁用 JRE 配置前确认存在受支持的 Java 运行时。
找不到配置
症状
Pod 无法挂载 sonar-project.properties 配置。
诊断步骤
-
验证 CSI 卷配置正确:
检查 Pod 规范中是否已正确配置 CSI 卷,并设置正确的connectorName和configuration.names属性。 -
常见原因和解决方案:
Connector 未就绪:
- 解决方案:等待 Connector 达到 Ready 状态
- 只有当 Connector 处于 Ready 状态时,配置才可用
卷配置不正确:
- 解决方案:验证 CSI 卷配置包含:
connectorName:Connector 的名称connectorNamespace:Connector 的命名空间configuration.names:"sonar-scanner"
质量门禁失败
症状
分析已完成,但质量门禁状态不是预期状态。
诊断步骤
-
检查 SonarQube 项目监控面板,查看质量门禁详细信息
-
常见原因和解决方案:
质量配置文件不匹配:
- 解决方案:验证项目是否分配了正确的质量配置文件
未达到覆盖率阈值:
- 解决方案:检查项目是否包含测试覆盖率数据
- 确保在分析前生成覆盖率报告
新代码周期配置:
- 解决方案:验证 SonarQube 中的新代码周期定义
性能问题
症状
Scanner 运行时间过长或超时。
诊断步骤
-
常见原因和解决方案:
代码库较大:
- 解决方案:增加作业超时和资源限制:
网络延迟:
- 解决方案:检查与 SonarQube 实例的网络连接
- 考虑使用距离集群更近的 SonarQube 实例
获取帮助
如果问题仍然存在:
-
检查 Connector 日志(将
<connectors-namespace>替换为安装 Connectors 系统的命名空间 — 默认为connectors-system,但可配置): -
查看 Connector 事件:
-
验证 SonarQube 实例运行状况:
- 访问 SonarQube Web 界面
- 直接检查
/api/system/status端点
-
查阅文档: