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

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

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

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

很多人装SonarQube时，前面把压缩包解开了，后面一启动就报错，于是第一反应是怀疑安装包有问题。其实SonarQube官方文档把安装链路写得很清楚，真正高频的失败点通常集中在三层，也就是Java版本不对、数据库配置没接好，以及Linux主机没有满足Elasticsearch启动前置条件。只要把这三层顺着排下来，大多数安装问题都能比较快收住。

部署SonarQube时，先不要急着选安装包，更关键的是先把运行方式想清楚。SonarSource官方文档现在把这条线写得很明确，服务端部署主线就是先检查服务器要求和Java版本，再准备数据库，然后按ZIP或Docker方式完成基础安装；如果只是测试，可以先用内置H2，但生产环境不建议这样做，而且官方明确建议生产库与SonarQube主机分离部署。

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

很多团队把安全热点当成漏洞去清单式消灭，结果要么误修一堆本来就安全的写法，要么把真正的漏洞淹没在噪声里。围绕SonarQube安全热点怎么用，SonarQube安全热点与漏洞问题怎么区分，抓住一个原则就够了：热点先人工复核再定性，漏洞确认即刻修复并纳入门禁。

SonarQube在网页里看趋势很方便，但到了里程碑评审、对外交付、审计留档，就需要把同一时间点的报告与数据“固化”为文件，并且能说清楚分支口径、筛选条件与拉取时间。否则很容易出现今天导出的数据和下周再看不一致，最后只能靠截图解释，证据强度不够。下面按导出与归档两条线，把操作路径与常见坑一次讲透。

SonarQube质量门禁不通过，先别直接翻全量Issue列表，最快的办法是先确认失败条件属于新代码还是全量代码，再沿着失败条件跳转到对应的证据页。因为质量门禁的每个条件都绑定到新代码或全量代码，两者口径不同，定位路径也不同。