很多朋友第一次在 Windows 上搭 SonarQube 代码质量管理平台都会以为只是“下载、启动、点一点”这么简单。但实际动手后会发现问题一个接一个服务起不来、数据库连不上、扫描器报了看不懂的错、中文乱码、端口被占用……我当年也在这个流程里卡了很久。今天这篇主要是围绕 SonarQube 7.4 sonar-scanner-cli JDK8 MySQL 这套经典组合来写把完整安装部署过程、关键配置、以及我踩过的坑全部摊开讲适合刚接触代码静态分析、需要在内网快速搭一套平台的开发者也适合准备从零开始学习 SonarQube 的测试或运维同学。1. 版本组合拆解为什么是 7.4、JDK8 和 MySQL1.1 SonarQube 7.4 在版本历史中的特殊位置SonarQube 的版本演进很快7.4 并不是最新版但它却是个非常微妙的版本。7.4 发布时仍然完整保留了对 JDK8 和 MySQL 的官方支持而在后续版本里官方开始逐步收窄运行环境7.9 LTS 之后服务端基本告别 MySQL8.x 之后对 JDK8 的支持也越来越不友好。所以如果你手头是一批存量项目技术栈还停留在 JDK8 MySQL那么 SonarQube 7.4 几乎就是最顺手的版本。加上很多企业内网的开发标准化程度不一新的 SonarQube 版本往往需要配套更高版本的数据库和 JDK对老项目的扫描并不友好。从兼容性和稳定性角度看7.4 完全可以支撑常规的代码质量检查需求项目的增量扫描和每日定时任务都能稳定跑起来。我碰到过不少项目组目标只是跑一次静态分析、出报告、追踪问题并不需要新版本那些花哨的智能分析能力。用 7.4 的好处是官方文档齐全、中文社区资料多、插件生态里大部分版本都能找到对应包遇到问题搜索一下基本能解决。而且这个版本以后端计算为主不强行依赖 Docker、K8s 这类现代基础设施简单一台 Windows 机器就能落地。1.2 服务端与扫描器的两层架构SonarQube 的部署形态可以拆成两层理解一层是 SonarQube Server负责存储、索引、分析任务调度、Web 界面展示另一层是各种扫描器比如 sonar-scanner-cli、Maven 插件、Gradle 插件等负责真正去读取源码并执行分析然后把结果上传给服务端。在 7.4 版本中服务端本身内置了 Elasticsearch所以不需要额外安装 ES这一点挺省事。但内置也意味着服务端对运行环境更敏感Windows 下最容易踩坑的就是内存、路径、权限这三件事后面我会逐个说。扫描器这边sonar-scanner-cli 是最通用的一种客户端它不挑构建工具直接扫描项目目录。很多新手容易把“扫描器”和“服务端”搞混以为只有一个工具就能完成全部工作其实必须两边配合先启动服务端再用扫描器上传结果。1.3 这套组合的适用场景这套组合适合没有容器化环境的传统项目、内网隔离环境、以及只需要基础代码质量反馈的团队。举例来说一个 Java Web 项目部署在某公司的 Windows 服务器上代码只放在本地 Git 仓库没有持续集成流水线这时候你搭一个单机 SonarQube 7.4配合 sonar-scanner-cli 手动扫描是最现实、最可控的方案。我也建议新人在自己的开发机上先跑通这套流程理解了服务端和扫描器怎么配合再往团队环境里推广思路会清晰很多。2. 前置环境准备JDK8 与 MySQL 的避坑配置2.1 JDK8 安装与环境变量配置SonarQube 7.4 的启动进程本质上是 Java 程序所以 JDK 版本必须选对。官方网站明确要求 JDK8我这里实测过用 JDK11 或 JDK17 启动 7.4 会直接报 UnsupportedClassVersionError根本起不来所以没必要在这个地方死磕“新版本”。安装 JDK 时我建议把路径选得简单一点比如 C:\Java\jdk1.8.0_202避免带空格和中文。如果你机器上装了多个 JDK请注意系统环境变量顺序确保 java -version 输出的是 1.8。配置环境变量时重点配置两个项JAVA_HOME指向 JDK 安装目录例如 C:\Java\jdk1.8.0_202Path追加 %JAVA_HOME%\bin配完后开一个新的命令行窗口分别执行 java -version 和 javac -version两条命令都显示 1.8 才算通过。很多人只验证了 java、没验证 javac后面遇到一些编译相关的问题才想起来环境没配全。另外不推荐设置 CLASSPATH现代 JDK 编译运行并不需要它设置错了反而容易干扰其他项目。2.2 MySQL 5.7 建库授权与字符集设置数据库这块官方支持矩阵里SonarQube 7.4 对应的是 MySQL 5.6/5.7其中 5.7 是最稳妥的选择。建议直接装 MySQL 5.7 系列不要去尝试 MySQL 8.0虽然也能硬跑但需要额外处理驱动和认证插件完全没有必要开头就给自己增加难度。登录 MySQL 后我习惯用以下一组 SQL 完成建库建用户CREATE DATABASE sonar DEFAULT CHARACTER SET utf8 COLLATE utf8_bin; CREATE USER sonarlocalhost IDENTIFIED BY sonar; GRANT ALL PRIVILEGES ON sonar.* TO sonarlocalhost; FLUSH PRIVILEGES;这里有几个容易忽略的细节。第一数据库字符集建议使用 utf8排序规则用 utf8_bin这样可以减少后续中文乱码问题。第二用户主机限定为 localhost 就够了因为 SonarQube 和 MySQL 在同一台机器上没必要开远程访问。如果确实要跨机器部署可以把账号改成 sonar%同时还要注意 MySQL 的 bind-address 配置。第三密码尽量别设太复杂的符号因为 sonar.properties 里的 URL 中如果有特殊字符解析起来可能会有意外的问题。2.3 如果被迫使用 MySQL 8.0 怎么办我知道有的环境装好了 MySQL 8.0不想换回 5.7。这种情况下你需要做三件事第一把 MySQL 的账号认证插件改成 mysql_native_password第二把 SonarQube 7.4 自带的 JDBC 驱动替换成 8.x 版本第三在连接 URL 里去掉旧驱动专属的参数例如 useConfigsmaxPerformance并增加 allowPublicKeyRetrievaltrue 和 serverTimezoneAsia/Shanghai。即使这样也仍然可能出现一些未知兼容问题所以我个人的态度是能用 5.7 就别在 8.0 上折腾这条路径只适合娱乐和临时环境。3. SonarQube 7.4 安装与启动目录、配置、初始化3.1 下载解压与目录结构说明从官方历史版本渠道下载 SonarQube 7.4 的安装包后解压到一个纯英文、无空格、无中文的路径例如 D:\sonarqube-7.4。这里绝对不推荐解压到 C:\Program Files\因为内置 Elasticsearch 对路径中的空格很敏感启动会直接报错而且提示信息晦涩难懂。解压完成后你会看到核心目录理解它们的作用对排查问题很有帮助conf所有配置文件都在这主要改 sonar.propertieslogs服务端日志目录排错时第一优先看这里data内置数据库文件、索引缓存重置环境时可以删extensions插件目录汉化包、自定义插件都放这lib依赖的 jar 包包括数据库驱动bin启动脚本Windows 下在 bin/windows-x86-64 目录这些目录里最值得关注的是 logs 和 extensions。每次启动失败我都建议先看 logs 里的 sonar.log 和 web.log而不是靠猜。3.2 修改 sonar.properties 数据库连接配置打开 conf/sonar.properties 文件找到数据库相关配置项把最前面的井号去掉改成类似下面的内容sonar.jdbc.usernamesonar sonar.jdbc.passwordsonar sonar.jdbc.urljdbc:mysql://localhost:3306/sonar?useUnicodetruecharacterEncodingutf8useSSLfalse这个 URL 里useUnicodetrue 和 characterEncodingutf8 是为了保证中文字符正确存储useSSLfalse 是为了避免本地连接时做 SSL 握手节省时间也减少莫名报错。数据库端口保持 3306 不变如果 MySQL 改过端口记得同步修改。在这个版本里数据库驱动不用额外下载lib/jdbc/mysql 目录下已经带了对应版本的连接器所以只需要保证这份配置和实际数据库一致。除了数据库还有一个地方建议顺手配好就是 JVM 内存参数。默认配置在内存比较小的机器上可能不够用你可以找到 sonar.web.javaOpts 和 sonar.search.javaOpts 这两个配置项取消注释并调整为sonar.web.javaOpts-Xms512m -Xmx1024m sonar.search.javaOpts-Xms512m -Xmx1024m如果你机器是 4G 内存这个配置跑起来问题不大。但如果 2G 内存还想跑完整分析建议不要强行上 SonarQube至少加内存再继续。3.3 启动、日志排查与首次登录在命令行切到 D:\sonarqube-7.4\bin\windows-x86-64 目录执行 StartSonar.bat就会看到一个控制台窗口开始滚动日志。首次启动因为要初始化数据库、创建索引通常会持续两三分钟这个阶段不要频繁强制关闭窗口也不要重复点击启动脚本。判断是否启动成功不要只看控制台最可靠的是访问 http://localhost:9000。如果页面能正常打开说明服务端已经起来了。如果访问不了就去 logs 目录翻文件我遇到的大多数异常在 sonar.log 里都有直接线索比如端口被占用、ES 启动异常、数据库连接拒绝等。还有一种更省心的方式是注册成 Windows 服务用命令sonar-service.bat install sonar-service.bat start服务方式的好处是系统重启后可以自动拉起不用每次手动开窗口。卸载服务时用 sonar-service.bat remove 即可。首次打开页面会进入欢迎界面默认账号是 admin/admin。登录后 7.4 版本会引导你修改管理员密码这一步建议直接改掉不要继续用默认密码。改完之后顺手看下系统信息确认“数据库”“搜索引擎”这些状态都是正常的再进入下一步配置扫描器。4. sonar-scanner-cli 配置与项目扫描实战4.1 下载版本与全局配置sonar-scanner-cli 是和服务端配套的客户端版本选择很重要。服务端是 7.4我建议使用 Scanner 2.8 或者 3.0 系列不要盲目下载最新版本。新版扫描器对服务端 API 版本有要求直接连老版本会出现不兼容典型的报错会提到 API 不匹配。这个问题在安装阶段不容易发现往往等你高兴地执行第一次扫描时才冒出来非常浪费时间。扫描器解压到 D:\sonar-scanner-cli 后需要改 conf/sonar-scanner.properties 文件核心配置只有两行sonar.host.urlhttp://localhost:9000 sonar.login你的_认证令牌认证令牌需要在 Web 界面生成登录后点击右上角头像进入 My Account找到 Security 菜单生成一个 Token起个自己能认出来的名字比如“local-scan”复制下来。这里额外提醒Token 只显示一次最好立刻粘贴到配置文件里别关了页面才想起来。接着配置环境变量把 D:\sonar-scanner-cli 配置为 SONAR_SCANNER_HOME并在 Path 里追加 %SONAR_SCANNER_HOME%\bin。完成后新开一个命令行窗口执行 sonar-scanner -v能看到版本信息就说明配置成功。如果提示不是内部或外部命令十有八九是 Path 没生效或者没开新窗口。4.2 项目级 sonar-project.properties 配置扫描器如何知道项目的基本信息答案是通过项目根目录下的 sonar-project.properties 文件。这是很多新手容易漏掉的一步直接在任意目录执行 sonar-scanner扫描器会提示找不到项目配置文件或者干脆扫出一个空项目。以常见的 Java Maven 项目为例我会在项目根目录放这样一份配置sonar.projectKeymyapp sonar.projectNameMy App sonar.projectVersion1.0.0 sonar.sourcessrc sonar.java.binariestarget/classes sonar.sourceEncodingUTF-8每个字段的作用需要理解清楚。sonar.projectKey 是项目的唯一标识在 SonarQube 后台看项目列表时就是用它区分不同项目sonar.projectName 是显示名称sonar.sources 告诉扫描器源码目录在哪sonar.java.binaries 指定编译后的 class 文件路径。这个 binaries 参数在扫描 Java 项目时是强制的如果缺失扫描会直接报错错误信息会明确告诉你没有设置 sonar.java.binaries。之前我看到有人分析 Python 项目也抄了一份 Java 的配置连 sonar.java.binaries 都写上了结果 Python 项目根本不生成 class 文件扫描结果自然就不对。所以要根据语言来配置Java 项目需要 binariesPython、JavaScript 这类动态语言不需要。4.3 实际扫描流程与结果阅读配置完成后在项目根目录执行sonar-scanner正常情况下控制台会输出 Scanner configuration、Project configuration、Base dir 等信息然后开始分析最后出现INFO: Analysis report generated INFO: ANALYSIS SUCCESSFUL BUILD SUCCESS看到 BUILD SUCCESS 并不意味着问题都检查完了而是分析任务已经提交给服务端。服务端还会异步做后续处理所以页面上的数据可能要等十几秒才刷新出来。刷新后进入项目主页能看到代码的 Bug、漏洞、坏味道等统计信息以及技术债务、覆盖率这些指标。我第一次扫描时以为扫完立刻就有报告结果页面一直显示 pending后来才明白是异步执行。这里分享一个实际操作技巧如果你只想快速验证环境是否通可以先在一个非常小的 Demo 项目上执行扫描比如只有五六个源码文件的项目。这样服务端处理快问题定位也快。等整个流程熟练了再扫真实的中大型项目否则一上来就扫一个几万行代码的老项目第一次必须分析几分钟中途一旦报错你很难判断是环境问题还是项目问题。5. 高频故障与解决方案速查5.1 服务起不来日志定位、内存、端口SonarQube 启动失败是最高频的问题我遇到过的场景基本可以归纳为三类。第一类是路径问题。解压路径带空格或中文启动过程中内置 Elasticsearch 很可能直接崩掉日志里会看到与 path 相关的异常。解决方式很粗暴重新解压到纯英文路径别嫌麻烦。第二类是内存问题。日志里如果出现 OutOfMemoryError 或者 Could not reserve enough space说明 JVM 分配的内存超出了机器可用范围。这时去 sonar.properties 里把 sonar.search.javaOpts 的内存值调小比如改成 -Xms256m -Xmx512m能启动成功就行。我见过有人一上来就按教程写 -Xms4g -Xmx4g结果机器只有 2G 内存服务根本起不来。第三类是端口占用问题。SonarQube 默认使用 9000 端口查询页内置 ES 也会占用 9300。如果你机器上已经跑了其他服务就会出现端口冲突。排查命令是 netstat -ano | findstr :9000找到占用进程后要么停掉它要么改 sonar.properties 里的 sonar.web.port。5.2 数据库连接失败与中文乱码数据库报错集中在几个常见类型。一种是 Access denied for user这通常是账号密码错误或者账号主机限制不对回到 MySQL 里重新授权即可。一种是 Unknown database sonar说明数据库名创建错了检查建库语句里的库名和 sonar.properties 里的 URL 是否一致。还有一种是连接超时或连接拒绝检查 MySQL 服务有没有启动、端口是不是 3306。中文乱码问题比较隐蔽可能出现在 SonarQube 界面本身也可能出现在扫描结果里。界面乱码通常是数据库字符集设置不对建库时务必指定 DEFAULT CHARACTER SET utf8。扫描结果里代码中文乱码则大概率是项目文件编码问题需要在 sonar-project.properties 里设置 sonar.sourceEncodingUTF-8同时保证源码本身就是 UTF-8 编码。还有一类比较难发现就是 Windows 命令行执行扫描器时命令行窗口的活动代码页导致参数里的中文路径解析异常这类问题可以先把项目目录改成英文名来排除。5.3 扫描器各种报错扫描器执行时报错我总结出三条高频线索。第一条提示 sonar-scanner 不是内部或外部命令99% 是环境变量没配置好重新检查 SONAR_SCANNER_HOME 是否指向了解压目录Path 里有没有追加 bin 路径。第二条报错包含 API 不匹配或 unsupported version说明扫描器版本和服务端版本差太远直接换旧版扫描器。第三条报错提示 sonar.java.binaries 缺失但你已经配了这说明属性位置写错了。注意sonar-project.properties 必须放在项目根目录并且扫描时要在同一目录下执行 sonar-scanner否则扫描器读不到配置这个看起来简单的问题踩过的人不在少数。6. 汉化、集成与日常维护建议6.1 安装中文语言包与常用插件虽然极客觉得英文界面无所谓但团队成员使用起来中文界面明显降低培训成本。7.4 版本可以安装对应版本的语言包插件。上网搜索“SonarQube 7.4 中文语言包”找到对应 jar 文件放到 D:\sonarqube-7.4\extensions\plugins 目录下重启服务端即可。这里特别强调一定要找匹配版本的插件包拿新版本语言包硬塞进老服务端大概率起不来或者界面错乱。插件管理的基本思路就是先看版本兼容矩阵再放 jar最后重启看日志。其他常用插件包括 Checkstyle、PMD、FindBugs 等都扔到 extensions/plugins 目录。装完之后进入 Web 界面在 Administration 的 Marketplace 里可以看到已安装插件状态。7.4 自带的 Marketplace 可能没法直接在线下载因为版本太老所以本地离线安装才是主流方式。6.2 与 Maven、IDEA 集成的实际操作如果项目用 Maven 构建可以不用 sonar-scanner-cli直接在 pom.xml 所在目录执行mvn clean verify sonar:sonar -Dsonar.host.urlhttp://localhost:9000 -Dsonar.login你的TokenMaven 方式的好处是自动收集测试覆盖率、依赖信息还能在构建阶段就完成代码扫描。不过要注意Maven 项目在执行分析前必须已经编译完成否则 class 文件不存在Java 分析照样报错。IDEA 的话可以装 SonarLint 插件连接服务端一边写代码一边看到实时问题提示也可以在插件配置里连接 SonarQube 服务端拉取规则配置。6.3 个人经验备份、重置与日常维护这套单机环境真正的维护重心不是功能配置而是数据备份和环境还原。SonarQube 的分析结果、项目配置都存在 MySQL 里所以我建议定期备份两个部分一是 MySQL 里的 sonar 数据库二是 D:\sonarqube-7.4\extensions 目录。真正迁移到另一台机器时把数据库导过去、把插件目录带过去再改一下 sonar.properties 里的 IP 就能恢复。data 目录反而可以清掉重启后会重新构建索引。如果遇到环境完全玩坏的情况最简单的重置思路是停服务删 data 和 logs 里的缓存再用 sonar-scanner 重新扫描没必要重新装系统。我个人实际操作用下来SonarQube 7.4 这套组合的定位就是“稳定够用”。只要你记住版本匹配大于一切路径纯英文数据库建库用 utf8扫描器版本别太新这套环境几乎不会遇到解决不了的难题。等跑通一次完整的扫描闭环后面再做质量门槛、规范规则调整这些事都会顺手很多。