1. 方案选型与基础环境准备1.1 为什么锁定 SonarQube 7.4 JDK8 MySQL大概两年前我在Windows上给模拟项目X搭代码质量检查环境第一个要求就是“别用太高版本稳定优先”。当时团队里既有Java 8的老项目也有刚入职的实习生大家统一用MySQL协作。所以我选了SonarQube 7.4来落地原因很直接它和JDK8的兼容性非常干净7.x版本的配置逻辑也比后来8.x、9.x清晰得多。很多人上来就装最新版SonarQube结果遇到Elasticsearch内存分配失败、OpenJDK版本不支持、插件市场断连等问题反而劝退了。7.4虽然不算新但对于一个固定迭代、不追求新语法分析场景的中小型开发组来说完全够用。选MySQL也有讲究。SonarQube 7.4官方支持的是MySQL 5.6 / 5.7并不支持MySQL 8.0。如果你机器上已经装了MySQL 8.0直接用8.0去连SonarQube 7.4启动时会报加密认证相关的错误实际排查很痛苦。所以我当时专门在本地保留了一个MySQL 5.7实例专门给SonarQube用。这个决定在后续运行过程中省了很多事。如果业务上必须用MySQL 8.0那就别纠结7.4直接选SonarQube 8.9 LTS会顺畅很多。还有一个容易被忽略的点SonarQube 7.4自带一个嵌入式数据库H2默认配置下就是H2在跑。如果你只是本地体验一下不改配置也行。但既然要连接团队共享的MySQL就必须把默认数据源切换掉。这个切换过程并不复杂但要注意顺序——先改配置文件再启动服务否则库里连表都建不出来。1.2 下载清单与环境变量配置先把需要的安装包都准备好。我的习惯是单独建一个D盘工具目录比如D:\toolchain里面再分jdk8、mysql、sonarqube、sonar-scanner四个子目录。这样后面写配置时路径固定不会因为到处移动导致启动脚本找不到文件。需要准备的东西JDK 8建议用1.8.0_202或更高的小版本不要用JDK 9/10/11来跑SonarQube 7.4。MySQL 5.7Windows安装版或解压版都行我推荐解压版配合命令行安装方便控制数据目录和端口。SonarQube 7.4官方zip包不要下载source包。Sonar Scanner CLI这里我们用兼容性较好的sonar-scanner-cli 3.0.3版本它是独立命令行扫描器不依赖Maven/Gradle。安装完JDK后配置环境变量。系统变量里新增JAVA_HOME值为C:\Program Files\Java\jdk1.8.0_202。然后编辑Path在末尾追加%JAVA_HOME%\bin。验证方式是在新的命令行窗口执行java -version。注意如果你的机器之前装了其他JDK版本一定要确认命令输出的是1.8。MySQL安装好后确保服务启动。可以在服务管理器里找到MySQL57或者手动执行net start mysql。然后用root账号登录验证一下能正常连接。SonarQube解压后的目录结构大概是这样的D:\toolchain\sonarqube\ ├─ bin\ │ ├─ windows-x86-64\ │ │ └─ StartSonar.bat ├─ conf\ │ └─ sonar.properties ├─ extensions\ │ ├─ plugins\ │ └─ jdbc-driver\ └─ logs\不需要修改bin下的启动脚本配置工作集中在conf\sonar.properties。同理Scanner解压后目录里有bin、conf、lib后面配置都围绕conf\sonar-scanner.properties和项目根目录的sonar-project.properties来做。另外我强烈建议在path里增加一个SONAR_SCANNER_HOME环境变量值为D:\toolchain\sonar-scanner再把%SONAR_SCANNER_HOME%\bin追加到Path。这样可以在任意目录下直接执行sonar-scanner命令不用每次切到Scanner目录。2. MySQL 初始化与 SonarQube 配置2.1 创建数据库与授权账号SonarQube需要一个空数据库自己会在第一次启动时创建表结构实际上它在启动初始化阶段会自动执行DDL。所以MySQL这边我们只需要手动创建数据库名和账号并授权。我用MySQL 5.7的root账号登录执行下面这些语句CREATE DATABASE sonar CHARACTER SET utf8 COLLATE utf8_general_ci; CREATE USER sonarlocalhost IDENTIFIED BY sonar_password; GRANT ALL PRIVILEGES ON sonar.* TO sonarlocalhost; FLUSH PRIVILEGES;注意几点。第一字符集建议用utf8不要用utf8mb4因为SonarQube内部很多表的结构在7.4版本上按utf8设计用utf8mb4可能会触发索引长度问题。第二授权对象尽量限制成sonar.*而不是*.*避免生产环境过度授权。第三如果SonarQube和MySQL不在同一台机器需要把localhost改成%或具体IP同时确认MySQL的bind-address允许远程访问。创建完成后可以用另一个命令行窗口测试mysql -u sonar -psonar_password -h 127.0.0.1 sonar能连进去就说明授权成功。如果这里失败SonarQube启动时必然报连接错误没必要继续往后走。2.2 sonar.properties 关键参数现在开始改D:\toolchain\sonarqube\conf\sonar.properties。文件默认大量配置被注释我们要做的是找到对应行去掉注释修改值。先找到JDBC相关段落。默认的H2配置大概是#sonar.jdbc.urljdbc:h2:tcp://localhost:9092/sonar这里要注释掉。然后在它下面加上MySQL连接信息sonar.jdbc.usernamesonar sonar.jdbc.passwordsonar_password sonar.jdbc.urljdbc:mysql://localhost:3306/sonar?useUnicodetruecharacterEncodingutf8rewriteBatchedStatementstrueuseConfigsmaxPerformance这段URL里几个参数的作用是useUnicodetruecharacterEncodingutf8保证中文字符能正确存入和读取避免扫描代码注释里的中文变成乱码。rewriteBatchedStatementstrue让MySQL批量插入语句更高效SonarQube初始化时会写大量数据这个参数能显著提升导入速度。useConfigsmaxPerformance使用MySQL驱动里的性能优化配置减少初始化和分析时的不必要开销。如果你用的是MySQL驱动8.x版本但SonarQube 7.4自带的是5.1.x驱动不要强行混用。我这里建议就用SonarQube自带的驱动位置在SonarQube\lib\jdbc\mysql目录下。那个驱动和7.4的代码是匹配的。再把Web服务端口设置好。默认是9000如果你的9000被占用可以改sonar.web.port9000不要随便改因为后面Scanner配置里要用同一个端口。如果改成9001Scanner连的时候也要同步改。另外我建议把日志级别先保持默认不需要动sonar.log.level。等后面出错时再临时调成TRACE能减少瞎改导致的问题。2.3 启动 SonarQube 并初始化确认配置无误后双击运行D:\toolchain\sonarqube\bin\windows-x86-64\StartSonar.bat。Windows下启动和Linux有点区别这个bat脚本会打开一个新控制台窗口Java进程直接在窗口前台运行。千万不要关掉这个窗口否则SonarQube会直接停掉。如果你想让它后台运行可以用Windows服务的方式但7.4的服务安装脚本在Windows上偶尔会遇到权限问题我建议前期调试阶段直接用bat运行。启动过程不会瞬间完成。7.4初次连接MySQL时要创建几百张表通常在20秒到1分钟左右。你会在控制台看到类似SonarQube is up的提示。这个提示出现后还不能立刻关窗口。打开浏览器访问http://localhost:9000看到登录页才算真正完成。如果窗口一闪而过说明启动失败。去D:\toolchain\sonarqube\logs目录看日志。重点看sonar.log以及最新的es.log。常见的错误我在第4章单独讲。第一次访问成功后用默认账号admin/admin登录。登录后系统会提示是否修改密码如果这是团队共用环境立刻改成强密码。但为了后续命令行Scanner方便我建议另一种做法在管理后台的My Account - Security里生成一个Token用Token代替密码做扫描认证。7.4版本支持Token方式这个Token就是一个随机字符串例如a1b2c3d4e5f6g7h8i9j0。生成后复制保存好下面Scanner配置会用到。3. Sonar Scanner CLI 安装与项目扫描3.1 安装并验证 ScannerScanner这边的安装相对简单。把sonar-scanner-cli-3.0.3.zip解压到D:\toolchain\sonar-scanner确认bin目录下有sonar-scanner.bat和sonar-scanner脚本。然后修改D:\toolchain\sonar-scanner\conf\sonar-scanner.properties。这个文件是Scanner的全局配置只要涉及多项目扫描都可以在这里统一设置服务器地址、Token、编码方式。sonar.host.urlhttp://localhost:9000 sonar.sourceEncodingUTF-8 sonar.logina1b2c3d4e5f6g7h8i9j0如果你不想把Token写在这里也可以在每个项目的sonar-project.properties里配置。我习惯把sonar.host.url和sonar.sourceEncoding放在全局Scanner配置里因为每个项目都一样避免重复维护。Token也放这里因为同一个扫描账号统一负责所有项目更便于管理。配置好后打开新的命令行窗口执行sonar-scanner -h正常会输出Scanner的版本、帮助信息。如果提示找不到命令检查Path环境变量是否配置了Scanner的bin目录。如果输出中提示Java版本不对回去检查JAVA_HOME是否被其他工具改动了有些安装程序会把Path里Java路径强制改成自己的版本这个坑真的很常见。3.2 在项目根目录编写 sonar-project.propertiesScanner不会自动识别项目结构必须在项目根目录放一个sonar-project.properties文件告诉Scanner项目叫什么、代码在哪、编译输出在哪。以模拟项目X一个Maven的Java Web项目为例项目结构大概是D:\projects\demo-x\ ├─ pom.xml ├─ src\ │ └─ main\ │ ├─ java\ │ └─ resources\ └─ target\ └─ classes\在项目根目录创建sonar-project.properties内容如下sonar.projectKeycom.demo.x sonar.projectNameDemo X sonar.projectVersion1.0.0 sonar.sourcessrc/main/java sonar.java.binariestarget/classes sonar.java.source1.8 sonar.sourceEncodingUTF-8解释几个关键项sonar.projectKey全局唯一的项目标识建议用Maven的groupIdartifactId例如com.demo.x。一旦这个Key在SonarQube里生成项目以后想改名比较麻烦最好一开始就定好。sonar.sources指向源码目录。如果是多模块项目可以写成sonar.sourcesmodule1/src/main/java,module2/src/main/java。sonar.java.binaries这是Java项目的必填项指向编译后的class文件目录。如果这个值不写或写错Scanner会报No files or directories matching target/classes或者分析时看不到任何代码指标。sonar.java.source1.8告诉SonarQube源码遵循Java 8语法避免因为语法解析失败而中断。还有一个小技巧如果项目里包含前端JS、CSS、HTML可以额外设置sonar.sources包含这些目录或者用sonar.exclusions排除掉不需要扫描的资源。比如sonar.exclusionssrc/main/resources/static/vendor/**避免扫描第三方库导致噪音。3.3 执行扫描并读报告执行扫描前强烈建议先构建一次项目确保target/classes存在。比如使用Mavenmvn clean compile这一步很多人会漏掉。直接用Scanner扫描没有编译的源码即使Java代码语法正确也会因为缺少字节码文件而分析失败。有的项目已经有target\classes但不是最新代码最好重新编译一次。然后在项目根目录执行sonar-scannerScanner会打印一大堆信息开头会显示连接的SonarQube地址、项目Key、Token校验结果。中间部分是文件解析进度最后几行会显示INFO: Analysis report generated... INFO: ANALYZE SUCCESS如果看到EXECUTION FAILURE后面多半跟着具体错误比如连接服务器失败、Token无效、找不到源码目录。这些常见问题我在第4章统一列出来。分析成功后打开http://localhost:9000/dashboard?idcom.demo.x就能看到项目质量看板。7.4版本的首页默认展示Bug、漏洞、坏味道的数量和类型还能点进代码详情查看具体行号。比如Bugs会标出可能存在空指针、资源未关闭的问题Code Smells提示哪些地方存在重复代码、过长的复杂度。我第一次扫描模拟项目X时抓到了30多个漏洞和80多个坏味道其中有不少是历史遗留代码的SQL注入风险。这些信息可以直接下发到开发任务里。注意7.4的规则集比现在新版少不少但针对Java 8项目它能覆盖大部分常见问题。4. 常见问题与实战排查4.1 启动失败与日志定位SonarQube启动失败最让人头疼的就是控制台一闪而过。我的建议是不要双击StartSonar.bat而是先打开一个CMD窗口然后手动执行:D:\toolchain\sonarqube\bin\windows-x86-64\StartSonar.bat这样窗口即使退出屏幕上的错误信息还在。但更可靠的是直接看日志目录。我遇到的几个高频问题及解决方式如下现象可能原因处理方式启动时提示Error occurred during initialization of VM内存参数过大或JDK版本不匹配检查conf\wrapper.conf里的wrapper.java.additional调低默认-Xms和-Xmx确认JAVA_HOME指向JDK8日志显示Unable to obtain connection from databaseMySQL网络不通、账号错误、密码错误先用命令行mysql -u sonar -p手动连接确认能连后再检查sonar.properties中的URL和账号日志里出现Access denied for user sonarlocalhost授权位置不是localhost或密码不匹配重新执行GRANT语句注意MySQL5.7的密码策略必要时先重置密码日志提示Unsupported JVM version使用了JDK9彻底卸载/屏蔽高版本JDK把JAVA_HOME改回JDK8并确保Path中所有Java相关路径都指向1.8端口被占用9000端口被其他程序占用换sonar.web.port比如9001记得同步改Scanner配置文件日志里还有一种比较容易忽略的情况es.log显示max virtual memory areas vm.max_map_count [65530] is too low。这是Elasticsearch的Linux系统限制问题Windows上一般不会遇到但如果你用WSL跑也可能会遇到。在Windows上跑的7.4用的内嵌ES通常没有这个问题。4.2 扫描时报连接错误Scanner执行时报SonarQube server can not be reached先看机器能不能访问http://localhost:9000。如果浏览器能打开但Scanner连不上多半是Scanner配置里的sonar.host.url写错比如多写了/sonarqube路径或者端口不对。还有一类特别容易遇到用了Token但没写进配置文件。Scanner在7.x版本默认不接受匿名访问你必须在sonar-scanner.properties里写sonar.login或者在命令行后面加参数sonar-scanner -Dsonar.login你的Token这个参数优先级高于配置文件适合临时替换Token。如果项目很多建议统一放在全局配置文件里这样省事。另外扫描过程中报Project X is already being analyzed说明上次扫描被中断了SonarQube还在分析队列里。解决方式是等几分钟让后台超时或者重启SonarQube再重新扫描。这个坑在7.4里比较明显尤其是Scanner断网时经常出现。4.3 插件与规则分析中的典型坑SonarQube 7.4默认自带Java插件可以分析基础问题。但它的插件版本比较旧如果你用新写的Java 11语法就完全解析不了。所以项目必须保持sonar.java.source1.8否则Scanner会报语法错误。有时候还会遇到扫描成功但页面上没有任何代码指标的情况。大概率是sonar.sources配置错了。比如源码在src/main/java你写成了srcScanner会把非源码文件也算进扫描范围反而没读取到Java文件。另一个可能是sonar.java.binaries指向的目录不存在。这会导致代码定位失败Scanner报告成功但仪表盘里全是零。7.4版本的插件市场已经不太友好在线下载经常超时。如果你需要额外的规则集比如C、Python不要依赖SonarQube内置的在线更新直接去官方仓库找到对应版本的插件jar包放到D:\toolchain\sonarqube\extensions\plugins目录下然后重启SonarQube。注意插件版本要和7.4兼容通常下载页面会标注适配的SonarQube版本范围。4.4 数据库连接稳定性与编码问题MySQL连接本身没问题但SonarQube启动后运行一两天就出现数据库连接断开或者在扫描时出现Communications link failure。这是因为MySQL默认的wait_timeout值太大连接空闲过长时间被服务端断开。解决方式有两种在MySQL里把wait_timeout调大更稳妥的方式是给sonar.jdbc.url增加自动重连参数sonar.jdbc.urljdbc:mysql://localhost:3306/sonar?useUnicodetruecharacterEncodingutf8rewriteBatchedStatementstrueuseConfigsmaxPerformanceautoReconnecttrue关于编码问题如果你在仪表盘上看到中文全部变成“”那基本是数据库的字符集不对。确保建库用的utf8不要用latin1。同时看看sonar.properties里的URL是否带着characterEncodingutf8。Scanner全局配置里的sonar.sourceEncodingUTF-8也不能漏。这些设置都对了扫描出来的中文注释才能正常显示。5. 我的实战心得与后续建议这套SonarQube 7.4环境我给模拟项目X前后调了大概两天。最难的部分其实不是安装而是理解各个配置之间如何联动。比如改错一个数据库URL启动后日志在后台快速滚动很多新人不知道去看logs目录然后就卡在那。其实所有问题都有迹可循日志和端口是最直接的切入点。我个人强烈建议第一次搭建时把MySQL、SonarQube、Scanner三个部分分开验证一步一步排错。不要一次把所有配置全改掉再想一次性跑通。先在SonarQube控制台能登录再去调Scanner。这样一旦有问题你能立刻定位是哪一层的问题。顺带说一个容易被忽略的小技巧sonar-scanner.bat的执行目录很重要。如果你在非项目目录下执行sonar-project.properties读取不到Scanner会报project directory is not empty之类的错。所以尽量先cd /d D:\projects\demo-x再执行sonar-scanner。另外如果后续要接到持续集成环境不要再用bat手动执行Scanner可以用Maven插件sonar-maven-plugin来替代。原理一样但能自动识别Maven项目路径省去手写sonar-project.properties的麻烦。不过从学习角度先跑通命令行Scanner会更容易理解整个分析链路。最后再分享一个体会SonarQube只是发现问题不要把它当作代码规范的工具而忽略人工走查。我们当时用7.4扫出来很多“坏味道”比如过长的if-else、可疑的异常捕获这些确实是New Gate里定义的问题但盲目修复也可能引入新的回归。建议每次扫描后组织团队按优先级来看报告先从Bug和Vulnerability里面的高严重度问题开始处理。这样这套环境才算真正发挥作用而不是变成一个每天产生电子垃圾的分析台。