做SonarQube扫描时，很多人一看到失败就先去改项目配置，结果改了半天，真正的问题其实可能在令牌、服务器地址、证书、代理，或者服务器后台任务本身。Sonar官方文档把这件事拆得很清楚：分析参数里有一批必须在CI/CD主机上设置的基础项，分析失败时又要分别看Scanner侧和Server侧的日志；如果网络链路里还有代理、HTTPS或自签名证书，排查顺序还会再往网络层延伸。把这些层次分开看，扫描失败这件事通常会比一上来就反复重跑更容易收住。
一、SonarQube扫描失败怎么办
扫描失败时，不要一上来就把所有参数都重写一遍。更稳的做法，是先把最基础的“能不能连上服务器、有没有带齐必填参数、Scanner本身有没有先报出明显错误”这三层先看清。官方参数文档明确写到，`sonar.token`、`sonar.host.url`和`sonar.projectKey`属于必须在CI/CD主机上设置的关键参数，其中`sonar.token`用于认证，`sonar.host.url`指向你的SonarQube实例地址，`sonar.projectKey`则是项目唯一标识。只要这几项缺一项或写错，后面的分析就很难正常落下去。
1、先把基础连接参数查完整
真正高频的失败点，往往先出在最基础的几项。`sonar.token`是认证必填项，`sonar.host.url`是服务器地址，`sonar.projectKey`是项目键值，这三项都属于官方定义的必填参数，而且都要求在CI/CD主机上提供。先把这三项查对，再去看更细的扫描范围和排除规则，会更稳。
2、内存类报错先看Scanner进程本身
如果日志里已经出现`java.lang.OutOfMemoryError:GC overhead limit exceeded`这类错误，官方建议的方向不是继续改项目属性，而是先给运行分析的Java进程更大的堆内存，或者缩小分析范围，减少不需要扫描的文件和目录。也就是说，这类失败更接近Scanner资源不足，不是SonarQube规则本身出了问题。
3、HTTPS报PKIX时先查证书信任链
如果失败信息里出现`PKIX path building failed`，Sonar官方给出的解释很明确：这通常说明SonarQube服务器跑在HTTPS后面，而且用了自签名证书，但Scanner所在机器的JVM不信任这个证书。真正该处理的，不是把地址改回HTTP，而是把服务器证书导入Scanner侧JVM使用的truststore，或者正确指定客户端truststore。
4、看起来“扫描结束了但结果没更新”时别急着重跑
官方排障页提醒，分析报告提交后还会进入后台队列顺序处理，所以日志里显示分析完成，并不等于项目页面已经立刻更新。如果只是短时间看不到结果，先去项目页面的后台任务看处理状态，而不是马上再跑一遍同样的分析。这个判断特别适合排除“其实没失败，只是后台还没处理完”的误判。
二、SonarQube日志与网络配置怎么查
查日志时，最容易做反的地方，是只盯一份日志看。Sonar官方把日志分得很细，Server端至少有`sonar.log`、`web.log`、`ce.log`、`es.log`和`access.log`，它们各管一层；网络配置这一侧又单独涉及代理参数、超时参数和TLS配置。更稳的做法，不是把所有问题都往同一份日志上靠，而是先按“Scanner到Server的连接问题”和“Server内部处理问题”分开查。
1、先把Server端日志分工看清
官方文档说明，`sonar.log`主要看主进程启动和关闭的总体信息，`web.log`重点看数据库初始连接、数据库迁移、重建索引以及HTTP请求处理，`ce.log`看后台任务处理，`es.log`看搜索引擎运行状态，`access.log`则记录访问日志。也就是说，如果你怀疑是扫描报告提交不上去，更该先看`web.log`；如果是报告进来了但后台处理失败，则应当优先看`ce.log`。
2、Scanner侧先查连接、超时和代理
Sonar官方参数页里把网络类参数单独列了出来。连接服务器时可以看`sonar.scanner.connectTimeout`、`sonar.scanner.socketTimeout`和`sonar.scanner.responseTimeout`这些参数；如果CI/CD主机位于代理后面，则可以用`sonar.scanner.proxyHost`、`sonar.scanner.proxyPort`、`sonar.scanner.proxyUser`和`sonar.scanner.proxyPassword`设置代理连接。不过官方也明确提醒，SonarScanner for.NET不支持这一组代理属性键，所以用.NET扫描器时不能照搬这套写法。
3、TLS和自签名证书要看truststore
如果网络层已经走HTTPS，官方参数页还给出了`sonar.scanner.truststorePath`和`sonar.scanner.truststorePassword`这类TLS参数，专门用于让Scanner侧信任服务器证书。前面提到的PKIX错误，本质上也是这一层没配顺。也就是说，网络配置不只是“能不能通”，还包括“Scanner是否信任它连到的那个HTTPS端点”。
4、Server放在反向代理后面时先查代理链路
官方文档说明，SonarQube可以部署在反向代理后面，而且还可以通过`sonar.web.host`设成`127.0.0.1`，让实例只接受来自反向代理的流量。这意味着如果你前面已经接了Nginx、Apache、IIS或其他代理层，那么“扫描连不上”有时并不是SonarQube本体坏了，而是反向代理、转发头或端口链路先没接通。
三、SonarQube排查顺序先看哪里
真正把SonarQube扫描问题查顺，关键不在于知道多少参数名，而在于顺序别做反。明明是认证参数没带齐，却先去研究`ce.log`；明明是后台任务在处理，还以为扫描已经失败；明明是HTTPS证书不被信任，却反复改项目源码范围。更稳的做法，通常是先查Scanner与服务器之间的“能不能连、怎么连”，再查Server内部“有没有收到、怎么处理”，最后才回头看项目本身的分析配置。这个顺序和Sonar官方把分析参数、分析排障、日志分工、代理与TLS配置分开说明的逻辑是一致的。
1、第一步先查Scanner到Server的基础链路
先确认`sonar.host.url`能否到达、`sonar.token`是否有效、`sonar.projectKey`是否填对，再看是不是被代理、超时或证书拦住。只要这一层没过，后面的日志分析大多都只是绕圈。
2、第二步再查分析是不是已经排进后台
如果Scanner日志里已经没有明显报错，但页面结果没更新，就先去看后台任务，而不是马上重跑。官方排障页明确提醒，分析报告会进入后台队列顺序处理，这一步能先排掉一大类“其实没失败”的误判。
3、第三步最后查Server端对应日志
当连接、认证和后台状态都已经有方向以后，再按分工去看`web.log`、`ce.log`、`es.log`。这样查，最容易把“请求没进来”“报告没处理完”“搜索服务异常”这几类问题切开，不会在一堆日志里乱翻。
4、分析成功过的项目再看SonarScanner Context
官方排障页说明，项目里可以通过后台任务的三点菜单查看Show SonarScanner Context，用来回看当次分析的Scanner上下文；但如果分析报告本身失败了，这份上下文就不会生成。这个边界很重要，因为它能帮你区分“适合去项目页面查”和“必须回到CI日志查”的两类场景。
总结
SonarQube扫描失败这件事，真正该先拆开的，不是某一条报错，而是三层问题：基础连接层、后台处理层、Server内部处理层。先把`sonar.token`、`sonar.host.url`、`sonar.projectKey`这些基础项查清，再看代理、超时和证书；确认报告已经提交后，再去看后台任务；最后才按`web.log`、`ce.log`、`es.log`的分工去收日志。这样查下来，你看到的就不再是一个笼统的“扫描失败”，而是一条比较容易落到具体原因上的排查线。
