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

　　一、扫描令牌要怎么配置

　　在SonarQube里去配置扫描令牌，首先就得想明白，到底是用那种只针对一个项目的令牌，还是用那种管着全局的令牌，要是只为了单个项目，那还是更推荐去用项目分析令牌，因为它的权限范围比较小，万一不小心被泄露出去了，那个影响也更容易被控制住。

　　1、去生成一个令牌

　　在登录进了SonarQube以后，进到用户的个人账户设置里，找到安全那一块，在令牌的区域里面，去创建一个新的令牌，在创建的时候，要选好合适的类型，还有它的有效期，令牌一旦被生成出来了，就要立刻把它给复制下来，好好地保存在一个地方，因为这个页面一旦被你关掉了，后面通常就再也看不到那个完整的令牌值了，官方的文档，也是明明白白地提示过的，令牌在被生成出来以后，是需要马上就去复制它的。

　　2、去确认一下权限

　　用来生成令牌的那个账号，一定得拥有，对目标项目的执行分析权限，要是你用的是那种全局分析令牌，那这个账号，就得要有全局的分析权限才行，可千万别拿着一个只用来看看东西的普通账号，去生成令牌，不然的话，在界面上倒是能登录进去，可是一跑扫描，还是有可能会失败的。

　　3、去把扫描的参数给配置好

　　在命令行的扫描器、Maven、Gradle，或者是持续集成的脚本里面，去把那个跟令牌有关的参数给写进去，同时呢，还得把服务器的主机地址，还有项目的唯一标识，也都一块儿给设置好，官方给出的分析参数文档里，是这么说明的，那个令牌的参数，就是让扫描器拿着它，去向SonarQube的服务端证明自己身份的，而且，它已经是用来替代，以前那种已经不被推荐使用的，账号和密码的登录方式了。

　　4、要避免把令牌，用明文直接写在代码仓库里面

　　那个令牌，可千万不要把它直接就给写进，代码仓库里面躺着的配置文件里去，一种更稳当的做法，是把它给放到CI/CD的环境变量、系统的环境变量，或者是密钥管理的配置里面，然后再在流水线的脚本里头，去引用它，这么做有一个好处，就是到了要换令牌的时候，只需要去改平台那边的变量就行了，用不着去动项目里面的代码。

　　二、令牌失效了以后，项目为什么就没法分析了

　　当SonarQube的令牌失效了以后，项目就没办法分析了，这从根本上来说，就是扫描器，它没办法通过服务端的认证了，扫描器那边，倒是可以正常地启动起来，也顺顺利利地读到了源代码，可就在往SonarQube上传分析数据的那一步，它就会被SonarQube给拒绝了。

　　1、令牌它自己已经过期了

　　要是当初在创建令牌的时候，给它设了一个到期的日子，那么一旦过了这个时间，它自然也就不能再被拿来用了，官方的文档里是这么写的，已经过了期的令牌，是没法再用的，但是呢，它还是会显示在你的个人账户安全设置的那个页面里面，你可以选择去手动把它给撤销掉。

　　2、令牌被人家给撤销掉了，或者干脆被换掉了

　　有些团队，是会定期去轮换令牌的，当一个新的令牌被生成了以后，要是流水线那边脚本里用到的变量，没有跟着同步去更新的话，那么在构建的日志里面，就会跑出来那种，认证失败了、没有被授权、或者是不被允许，这一类的提示信息。

　　3、令牌所对应的那些权限，被弄丢了

　　那个项目分析令牌，它跟生成者的权限，是有关系的，要是当初生成这个令牌的那个人，他自己丢掉了对这个项目的执行分析权限，那么这个令牌，它也就不能再被拿来跑分析了；全局分析令牌也是同样的道理，生成它的人一旦失去了全局的分析权限，这个令牌也就跟着一起失效了。

　　4、.NET的扫描器，它前后的令牌没有保持一致

　　在去用专门给.NET用的扫描器的时候，如果在开始的那一步，给它传进去了一个令牌的参数，那么在结束的那一步，也得把同样的那个参数，再给它传进去才行，官方的文档，是特别明确过的，在开始的那一步里，你要是加了那个参数，那么到了结束的那一步，也一定得要加上它。

　　三、扫描令牌失效了要怎么排查

　　在排查跟令牌有关的问题时，可不要只是去重新生成一个新的令牌，就觉得完事了，要回过头去，把权限、变量、流水线的缓存，还有扫描时候的命令，全都放在一起去检查，要不然的话，下一次，是很容继续在同样的地方报错的。

　　1、先去看一眼构建的日志

　　在CI/CD跑出来的日志里面，去搜一搜跟认证、令牌、是否被授权、还有执行分析，这些有关的词儿，要是那个错误，是集中在往上传分析结果的那个阶段出现的，那这通常，就是令牌本身，或者是权限上出了问题。

　　2、去核对一下，实际在起作用的是哪一个变量

　　要去看一看，流水线它当前正在读的那个令牌，到底是不是你刚刚才生成出来的那个新的，有些平台，它会把变量分成项目变量、组变量、还有全局变量，名字就算是一样的，也是有可能被别的地方给覆盖掉的，一种更推荐的做法，是统一只用一个名字，并且去确认一下，那个扫描的脚本，是真的引用了它的。

　　3、回到SonarQube里面，去检查一下令牌的状态

　　进到个人账户的安全设置里，去看一眼那个令牌，是不是已经过期了、还是不是好端端地待在那里，要是项目，是由一个专门用来跑自动化的机器人账号去分析的，那也得去登进那个机器人的账号里检查一下，可不要只是盯着管理员自己的个人账号去看。

　　4、先拿一个小范围的扫描，去验证一下

　　在你把令牌更新完了以后，最好是先挑一个小小的项目，或者是单独一条分支，去跑一次扫描看看，等确认了认证、项目的唯一标识，还有服务器的地址，这些全都是对的，然后再去把正式的那条流水线给恢复起来，这么做，就能避免那种情况，就是在一个很大的项目上，构建跑了好长好长的时间，最后却卡在了上传结果的那一步，给失败了。

　　总结

　　关于SonarQube的扫描令牌要怎么去配置，还有一旦令牌失效了，项目为什么就没法分析了，这里面最要紧的地方，就是把令牌、账号的权限，还有扫描时候的参数，这三样东西给它一一地对应起来，在做配置的时候，要进到个人账户的安全设置里去生成令牌，然后用那个专门的参数，把它传给扫描器，同时，还得把这个令牌，给放在一个安全的环境变量里面；等到令牌失效了以后，就要重点去排查，是不是过期了、被撤销了、权限给弄丢了、变量没有跟着更新，还有.NET扫描器那种，前后两步参数没保持一致的情况，只要把这些关键的点，都给查清楚了，那项目分析失败的问题，一般来说，就能比较快地被定位出来了。