SonarQube

一套SonarQube环境通常会接入多个代码仓库。项目名称可以相似，但项目密钥必须能够准确区分每个项目。密钥重复、大小写不一致，或者扫描任务读取了错误配置，都可能让结果进入其他项目，甚至直接中断分析。了解SonarQube项目密钥怎么设置SonarQube项目密钥冲突导致分析失败怎么办，可以帮助团队把网页项目、代码仓库和流水线配置对应起来。

SonarQube分支分析怎么开启，还有分支分析出来的结果为什么跟主分支对不上，这些是不少团队在把扫描接入CI之后都会碰到的问题。分支分析这件事，不是说把不同的分支挨个扫一遍再统统塞进同一个项目就行了的，它需要版本那边能支持、扫描时传的参数得对、代码基线要定好，还有对新代码的定义也要一起配合着来才行。另外有一件事得先弄清楚：SonarQube Server的分支分析功能是从Developer Edition才开始提供的，Community Edition一般只保留单个项目的分支视图，所以在动手之前得先确认好版本。

在给新项目接入扫描、迁移流水线、调整账号权限，还有令牌到期了以后，常常会碰到一类问题，那就是SonarQube的扫描令牌，到底应该怎么去配置它，还有，一旦那个令牌失效了，为什么项目就没法再继续分析了，SonarQube的扫描令牌，它可不是一串普普通通的字符串，这个东西，代表的是某一个用户，或者是某一个项目，它所拥有的分析权限，按照官方文档的说明，令牌是可以被拿来执行分析用的，用的时候，不需要把真实的账号密码给暴露出去；但是呢，在跑分析的时候，那个令牌所对应的用户，他必须得拥有，对这个项目的执行分析的权限。

如果不想让`target`、`dist`、`build`、`generated`、`node_modules`这类目录被当成手写的代码来分析，就得靠SonarQube的排除规则，它支持通过路径匹配的方式，去把那些文件给排除掉，这个设置，既可以在项目的页面上去完成，也可以写在CI/CD主机上的扫描参数里面；不过有一点要注意，要是同一个参数，在两个地方都设置了，那CI/CD里的参数，是会优先于页面上的设置的。

很多团队一上来就先往`.gitlab-ci.yml`里塞扫描命令，结果跑是能跑，后面要么MR不出结果，要么质量门禁没法拦合并，要么分支和MR参数还互相打架。SonarQube官方文档把这条链路拆得很清楚，GitLab CI集成至少有三步，先在SonarQube里把项目建好并和GitLab关联，再把分析任务接进GitLab CI/CD，最后再让MR分析和质量门禁结果回写到GitLab。真正稳的做法，不是先写脚本，而是先把项目绑定、扫描入口和MR触发条件摆顺。

团队使用SonarQube一段时间后，往往会根据项目语言、代码规范和风险要求调整检测规则。规则数量一多，如果仍直接修改默认配置，后续很难分清哪些规则被启用、哪些参数被改过。遇到扫描结果没有变化时，也容易把问题误认为扫描器失效。弄清SonarQube规则配置文件怎么管理SonarQube规则调整后扫描结果为什么不变，可以让规则维护、项目绑定和扫描验证形成一套清楚的流程。

在SonarQube里，误报这回事到底要怎么去处理，还有已经给它标上了误报之后，审查的记录又该怎么留下来，不能简单地理解成“工具报了，可我觉得没事，点掉就算了”。SonarQube里面可以把问题标成False positive或是Accepted，False positive更对路的用法，是分析出来的结果确实弄错了，Accepted就更偏着“问题是有的，但现在先这么接受，后面再找时间弄”。这两个状态要是混着用，后面做质量审查的时候，就不容易说清楚了。

在一条流水线被长期接入之后，经常会出现一类问题，就是SonarQube里面的历史分析记录，该怎么样去清理一下，还有它的数据库体积，要是变得太大了，又该怎么去处理，项目每天都在那跑扫描、分支被反反复复地创建、版本号也在不停地变化，这么一来，数据库就会慢慢地变大，SonarQube它自己，其实是有一套后台维护机制的，它会在新的分析被执行完了以后，去清理掉一部分旧的数据、旧的历史快照、PR的分析，还有分支的记录，靠着这个，来减缓数据库的膨胀，官方的文档里也说明了，那些旧的分析，是不会被完完整整地一直保留着的，不然的话，数据库就会变得臃肿不堪。

做SonarQube扫描时，很多人一看到失败就先去改项目配置，结果改了半天，真正的问题其实可能在令牌、服务器地址、证书、代理，或者服务器后台任务本身。Sonar官方文档把这件事拆得很清楚：分析参数里有一批必须在CI/CD主机上设置的基础项，分析失败时又要分别看Scanner侧和Server侧的日志；如果网络链路里还有代理、HTTPS或自签名证书，排查顺序还会再往网络层延伸。把这些层次分开看，扫描失败这件事通常会比一上来就反复重跑更容易收住。

SonarQube里与安全相关的告警，既有Vulnerability这类可被利用的漏洞，也有Security Hotspot这类需要人工复核的安全敏感点。处理时如果不先分清类型与口径，很容易把热点当漏洞硬修，或把真实漏洞当成可忽略项拖延。下面按“先处理再排序”的顺序，把日常可复用的操作路径写清楚。

SonarQube令牌怎么生成SonarQube令牌失效后构建任务怎么处理，这主要取决于令牌是用于个人本地扫描，还是挂在CI/CD构建任务中。按照SonarQube官方的解释，用户令牌能够用来做代码分析，在扫描时可以当作sonar.token参数传入，也可以搁在SONAR_TOKEN环境变量里；令牌一旦到了期限，就没办法再接着用了。

SonarQube里质量门禁要怎么去设，还有当这个门禁过不去的时候，应该先查哪些指标，很多团队把静态代码检查接进CI以后，都会撞上这个问题。质量门禁这个东西，它不单单是去看一下代码扫描成没成功，而是用事先定好的一组条件，去判断这回交上来的代码，到底够不够格合进去，或者能不能往外面发。它主要是拿来卡新代码的，也可以去卡整体代码，现在搞项目的人一般都会说，先把力气用在管好新代码上头，这么一来，就不会弄成老问题还没清掉，新问题又跟着跑进来的局面。

在企业想要统一账号体系的时候，有两件事是需要处理的，一件是怎么把SonarQube接入到LDAP的登录里去，另一件是用户和组的映射关系，又要怎么去配置好，SonarQube是可以把认证这件事，委托给LDAP或者是Active Directory去做的，当一个用户第一次登录成功了以后，SonarQube里面就会自动地给他建好一个账号，等到后面他再登录的时候，也都会去同步他的用户名、邮箱，还有一些可以选择的组的关系，按照官方文档给出的说明，去接入LDAP这件事，主要是靠在安装目录下面，去修改conf文件夹里面的配置文件来完成的，等改完了以后再去重启一下服务，然后通过看日志，来确认跟LDAP的连接是不是真的通了。

SonarQube的质量配置文件，它本质上就是决定了，某一种语言在跑代码分析的时候，到底会启用哪些规则，一个项目扫描出来的那些问题，也会受到它当前绑定的那个配置文件的影响，按照SonarQube的文档说明，质量配置文件，就是用来定义在分析代码的时候，要应用的那一套规则集合的，而且每一种语言，都可以有它自己专属的配置文件。

SonarQube扫描慢，很多时候不是服务器本身有问题，而是把三类事情混在了一起，一类是分析范围太大，一类是缓存没有真正用起来，还有一类是并发开法和语言插件本身的机制没对上。SonarSource官方文档写得很清楚，增量分析里的analysis cache是按分支管理的，扫描前会先下载缓存，扫描后再按规则回写；但并发并不是一个所有语言通用的总开关，而是由不同语言分析器分别控制。也就是说，先分清你慢在范围、缓存，还是线程，后面才调得准。

项目多次迭代后，相似的校验、转换、异常处理和接口调用可能分散在不同文件中。代码虽然还能运行，但后续修改同一条规则时，开发人员往往要同时处理多个位置，漏改一处就可能造成逻辑不一致。弄清SonarQube重复代码怎么查看SonarQube重复代码比例过高怎么降低，可以先找到重复集中的文件，再根据业务关系完成重构和验证。

SonarQube覆盖率报告怎么导入SonarQube覆盖率数据显示为空怎么办，很多团队在把代码质量平台搭起来以后，都会撞上这个问题。SonarQube这个工具自己是不会去生成覆盖率报告的，那串数据得先让JaCoCo、LCOV、coverage.py、dotnet-coverage或者gcov这类外部的测试覆盖率工具给跑出来，然后扫描器在分析的那一步，再把它们读到SonarQube里头，最后才在页面上亮出来。说白了，SonarQube干的活儿是接住这些数据然后展示出来，它可不替你跑测试，也不替你往外头吐覆盖率文件。

在SonarQube里面，扫描项目要怎么去配置，还有扫描的时候那些参数要是漏掉了、没给填上，会对最后出来的结果带来什么样的影响，这一块主要还是得去看项目用的是哪一种构建的方式，还有扫出来的结果要不要把分支、覆盖率，还有质量门禁这些个东西都给接进来。在SonarQube里头，那些拿来分析用的参数，一般都是照着sonar.这么一种样子去写的，有一部分参数，是能够在项目里面给写到一个配置文件里面去的，也可以通过命令行的方式，或者在CI的脚本里面，把它给传进去。

在代码扫描刚刚落地的时候，有两个问题是挺常碰到的，一个是SonarQube扫出来的问题，到底要怎么去分配给具体的人来处理，另一个是，这些问题它的状态变来变去，又要怎么去管，扫描出来的结果一多，要是没有个明确的负责人，那些问题就会长时间地挂在列表里面；可要是大家随便地就把状态给改成了已接受，或者是误报，那到了后面，再去搞质量门禁、版本复盘，还有审计说明的时候，就会很难说得清楚了。SonarQube在分析的时候，它会试着把新发现的问题，自动分配给，最后改过那一行代码的人，但这有个前提，就是代码提交时候用的那个账号，得能跟SonarQube里面的用户，关联得上；要是关联不上，那它就会去用项目里设好的那个默认处理人。

做SonarQube权限管理时，最容易乱的地方，不是按钮找不到，而是把全局权限、项目权限和令牌管理混成了一层。SonarSource官方文档把这条线分得很清楚，全局权限在【Administration】【Security】【Global Permissions】里管理，项目相关权限更多通过权限模板和项目级权限页来落地；而Token又是另一条独立链路，既有用户自己生成和轮换的分析令牌，也有管理员代用户生成或撤销的用户令牌。换句话说，权限和Token虽然都在安全域里，但真正稳的做法是分层治理。