简介SonarQube 7.4 是一款开源代码质量管理工具的完整安装包面向 Java、Python、C#、JavaScript 等多语言开发者及需要搭建代码质量检测平台的团队。针对官网下载速度缓慢的问题此压缩包提供已下载好的 7.4 版本方便开发者快速获取并部署本地代码分析环境。资源为 rar 压缩包整体约 161.38MB包内按标准目录组织包含 bin 启动脚本、conf 配置样例、extensions 插件目录、lib 依赖库、web 前端资源及 README、LICENSE 说明文件便于按模块查阅与二次配置。目前已有 636 人学习下载适合需要离线部署 SonarQube、研究其目录结构与配置方式的中高级开发者参考使用。1. 从一台老服务器说起sonarqube-7.4 到底能解决什么上周帮朋友看一台内网构建机JDK 8、MySQL 5.7、CentOS 7跑着一套 2018 年前后上线的老项目。代码能编译、能打包但每次发版前靠人肉 review谁改了什么、哪块逻辑有隐患全靠记忆。他问我有没有那种“装完就能扫、扫完能看报告”的东西我第一反应就是 sonarqube-7.4。这个版本在当下不算新但它的定位非常清楚一个自托管的静态代码分析平台把代码质量、重复率、潜在缺陷、覆盖率这些指标集中到一个 Web 面板里。sonarqube 本身不是编译器插件也不是 IDE 里的实时提示它更像一条独立的检查流水线——你给它源码它给你一份可追踪、可对比、可卡门禁的报告。sonarqube-7.4 适合谁适合还在维护 Java 8 技术栈、不想折腾新版 JDK 与数据库兼容性、又需要一套稳定可复现扫描环境的团队。它不追求最新规则库但胜在部署路径短、依赖明确、踩坑记录多对一线运维和测试开发来说是一个能快速落地的选择。2. 拆开 sonarqube-7.4架构、依赖与部署前的选型判断2.1 它由哪几块组成为什么不是“装个插件”那么简单sonarqube-7.4 的运行时结构可以拆成三层Web 服务层、计算引擎层、数据库层。Web 层负责页面展示和 API计算引擎负责分析报告的后处理数据库存配置、规则、历史快照。你下载到的压缩包里通常包含bin、conf、data、extensions、lib、logs、web这些目录。很多人第一次用会误以为它像 IDE 插件一样即插即用结果卡在数据库连接或者 Elasticsearch 启动失败上。原因在于 sonarqube 从 6.x 开始就把 Elasticsearch 内嵌进来了7.4 也不例外而 Elasticsearch 对系统参数、内存、文件句柄有硬性要求。所以部署前要先判断这台机器是只跑 sonarqube还是和构建任务混部如果是混部内存至少留 4GB 给 sonarqube 进程否则计算引擎会在分析大项目时被 OOM 杀掉。另一个选型点是数据库sonarqube-7.4 官方支持 MySQL 5.6/5.7、PostgreSQL 9.x/10.x、Oracle、SQL Server但不支持 MySQL 8 的默认认证插件。如果你手头只有 MySQL 8要么改认证方式要么换 PostgreSQL否则连初始化建表都过不去。2.2 部署前的参数核对JDK、数据库、系统限制在动手解压之前先把下面这张核对表过一遍。这不是官方文档的复述而是我实际部署时按顺序检查的项。检查项sonarqube-7.4 要求常见误判JDKJDK 8不支持 JDK 11以为高版本兼容启动报 UnsupportedClassVersionError数据库MySQL 5.6/5.7 或 PostgreSQL 9.x/10.xMySQL 8 默认 caching_sha2_password 导致连接失败内存至少 2GB 空闲建议 4GB混部构建机分析时被系统 OOM文件句柄至少 65536默认 1024Elasticsearch 启动报 too many open files虚拟内存max_map_count 至少 262144默认 65530ES 直接拒绝启动端口9000 默认需确认未被占用与 Nexus 或其它服务冲突这些参数里vm.max_map_count和ulimit -n是最容易被忽略的两个。我见过有人把 sonarqube 装好了Web 页面能打开但一提交分析任务就卡在计算引擎日志里反复刷max virtual memory areas vm.max_map_count [65530] is too low。解决办法不复杂在/etc/sysctl.conf里加一行vm.max_map_count262144然后sysctl -p生效。文件句柄则在/etc/security/limits.conf里给运行 sonarqube 的用户加上nofile 65536重新登录后ulimit -n确认。这些不是 sonarqube 本身的要求而是它内嵌 Elasticsearch 带来的连带约束理解这一点后面排查就不会跑偏。2.3 从零启动解压、改配置、初始化数据库假设你已经把 sonarqube-7.4 的压缩包放到了/opt下并且系统里有一个可用的 MySQL 5.7。下面是我常用的初始化流程每一步都对应一个具体目的。# 解压到指定目录注意不要用 root 直接跑 sonarqube 进程 cd /opt unzip sonarqube-7.4.zip chown -R sonar:sonar /opt/sonarqube-7.4 # 创建数据库和专用用户字符集必须是 utf8 mysql -uroot -p -e CREATE DATABASE sonar CHARACTER SET utf8 COLLATE utf8_general_ci; CREATE USER sonarlocalhost IDENTIFIED BY Sonar123; GRANT ALL PRIVILEGES ON sonar.* TO sonarlocalhost; FLUSH PRIVILEGES; 数据库建好之后编辑/opt/sonarqube-7.4/conf/sonar.properties把 JDBC 连接和 Web 端口写进去。这里有个细节sonarqube-7.4 的配置文件里默认所有连接都是注释状态你需要手动取消注释并改成自己的值。# conf/sonar.properties 关键片段 sonar.jdbc.usernamesonar sonar.jdbc.passwordSonar123 sonar.jdbc.urljdbc:mysql://localhost:3306/sonar?useUnicodetruecharacterEncodingutf8rewriteBatchedStatementstrueuseConfigsmaxPerformanceuseSSLfalse sonar.web.host0.0.0.0 sonar.web.port9000 sonar.web.javaOpts-Xmx1024m -Xms256m -XX:HeapDumpOnOutOfMemoryError sonar.ce.javaOpts-Xmx1024m -Xms256m -XX:HeapDumpOnOutOfMemoryErrorsonar.jdbc.url里的useSSLfalse在 MySQL 5.7 上通常需要显式加上否则驱动会尝试 SSL 握手然后超时。rewriteBatchedStatementstrue是官方建议的性能参数能明显加快大批量插入。sonar.web.javaOpts和sonar.ce.javaOpts分别控制 Web 和计算引擎的堆内存如果项目规模不大1GB 够用如果代码文件超过十万行建议调到 2GB 以上。改完配置后用非 root 用户启动# 切换到 sonar 用户启动避免 Elasticsearch 拒绝 root 运行 su - sonar cd /opt/sonarqube-7.4/bin/linux-x86-64 ./sonar.sh start # 查看日志确认启动状态 tail -f /opt/sonarqube-7.4/logs/sonar.log启动日志里看到SonarQube is up才算真正就绪。如果卡在Starting Elasticsearch超过两分钟多半是前面提到的系统参数没调。第一次访问http://服务器IP:9000默认账号密码都是admin登录后会强制改密码。到这里平台侧就完成了接下来才是把代码送进去。3. 把代码送进 sonarqube-7.4扫描器配置与第一次分析3.1 选扫描器sonar-scanner 与 Maven 插件怎么挑sonarqube 平台本身不直接读源码它靠扫描器把分析结果推过来。sonarqube-7.4 时代最常用的两种方式是sonar-scanner命令行工具和 Maven 的sonar-maven-plugin。如果你的项目是 Maven 构建的 Java 工程直接用 Maven 插件最省事因为依赖、源码目录、编译输出路径都是现成的。如果是多语言混合项目或者构建脚本不是 Maven那就用独立的sonar-scanner。我一般会先看项目根目录有没有pom.xml有就用 Maven 方式没有就下载对应版本的 scanner。注意 scanner 版本要和 sonarqube-7.4 兼容太新的 scanner 可能调用了新版 API导致推送时报 404。常见做法是选 sonar-scanner 3.x 或 4.x 的早期版本具体可以在 sonarqube 的 Web 界面里点“帮助”查看推荐版本。3.2 Maven 项目接入pom 配置与命令参数在 Maven 项目的pom.xml里加上插件配置指定 sonarqube 服务器地址。如果不想改 pom也可以在命令行直接传参。下面是我常用的命令行方式不改动项目文件适合临时扫描。# 在项目根目录执行指定 sonarqube 地址和登录令牌 mvn clean verify sonar:sonar \ -Dsonar.host.urlhttp://192.168.1.100:9000 \ -Dsonar.loginyour_generated_token \ -Dsonar.projectKeymy-java-app \ -Dsonar.projectNameMy Java App \ -Dsonar.java.binariestarget/classes \ -Dsonar.sourceEncodingUTF-8sonar.login推荐用 Web 界面生成的令牌而不是明文账号密码这样可以在 CI 里安全传递。sonar.java.binaries必须指向编译后的 class 目录否则 sonarqube 无法做字节码级别的规则分析只能做文本扫描很多缺陷规则会失效。sonar.projectKey是项目在 sonarqube 里的唯一标识第一次扫描会自动创建项目。如果执行时报You must define the following mandatory properties: sonar.projectKey说明参数没传进去检查命令换行符或者 Maven 版本是否把参数吃掉了。3.3 非 Maven 项目sonar-scanner 的配置文件写法对于前端项目或者 Python 脚本用sonar-scanner更直接。在项目根目录建一个sonar-project.properties把关键参数写进去。# sonar-project.properties sonar.projectKeyweb-frontend sonar.projectNameWeb Frontend sonar.projectVersion1.0 sonar.sourcessrc sonar.exclusions**/node_modules/**,**/dist/**,**/*.min.js sonar.sourceEncodingUTF-8 sonar.host.urlhttp://192.168.1.100:9000 sonar.loginyour_generated_tokensonar.sources指定要扫描的源码目录sonar.exclusions用来排除第三方库和打包产物。如果不排除node_modules扫描时间会从几分钟变成几十分钟而且报告里全是第三方库的告警没有参考价值。配置写好后在项目根目录执行sonar-scanner即可。如果提示sonar-scanner: command not found需要把 scanner 的bin目录加到PATH里或者用绝对路径调用。扫描完成后Web 界面会自动刷新出项目报告第一次分析通常需要等计算引擎处理完状态从PENDING变成SUCCESS后才能看到完整数据。4. 避坑与排查sonarqube-7.4 部署和扫描中的五个血泪经验4.1 启动报 max_map_count 过低Web 页面打不开现象执行./sonar.sh start后日志停在Starting Elasticsearch端口 9000 无法访问。原因内嵌 Elasticsearch 要求vm.max_map_count至少 262144而 CentOS 7 默认是 65530。解决echo vm.max_map_count262144 /etc/sysctl.conf sysctl -p然后重启 sonarqube。这个坑几乎每个新环境都会遇到建议部署前就改好。4.2 数据库连接失败日志报 Access denied现象启动时日志出现Access denied for user sonarlocalhost。原因MySQL 用户权限没给全或者密码里包含特殊字符导致配置文件解析出错。解决确认sonar.jdbc.password没有用引号包裹特殊字符用反斜杠转义同时用mysql -usonar -p手动登录验证。如果 MySQL 是 8.x还要检查认证插件必要时执行ALTER USER sonarlocalhost IDENTIFIED WITH mysql_native_password BY Sonar123;。4.3 扫描成功但报告里没有代码规则告警现象分析任务显示成功但项目面板里只有重复率和复杂度没有 bug 和漏洞。原因sonar.java.binaries没配置或路径错误sonarqube 拿不到字节码只能做文本级分析。解决确认 Maven 项目先执行了mvn compile并且-Dsonar.java.binariestarget/classes指向真实存在的目录。如果是多模块项目每个模块的 class 目录都要列进去用逗号分隔。4.4 分析大项目时计算引擎崩溃日志出现 OutOfMemoryError现象扫描任务提交后计算引擎进程消失Web 界面一直显示PENDING。原因sonar.ce.javaOpts堆内存不足或者系统物理内存被其它进程占满。解决把sonar.ce.javaOpts的-Xmx调到 2048m 或更高同时用free -m确认系统还有足够空闲内存。如果机器内存实在紧张可以限制并发分析任务数在conf/sonar.properties里设置sonar.ce.workerCount1。4.5 中文乱码源码编码与数据库字符集不一致现象报告里的中文注释显示为问号或乱码。原因源码文件是 GBK 编码但sonar.sourceEncoding设成了 UTF-8或者数据库字符集不是 utf8。解决统一用 UTF-8 保存源码扫描参数里显式加-Dsonar.sourceEncodingUTF-8数据库建库时确认CHARACTER SET utf8 COLLATE utf8_general_ci。如果历史数据已经乱码只能清库重新扫描。5. 让 sonarqube-7.4 真正融入日常质量门禁与增量分析技巧平台跑起来、扫描能出报告这只是第一步。真正让 sonarqube 产生价值的是把它变成发版流程里的一道门禁。sonarqube-7.4 支持质量门禁Quality Gate你可以定义一组条件比如“新增代码覆盖率不低于 60%”“新增代码零严重缺陷”当扫描结果不满足时CI 任务直接失败。配置入口在 Web 界面的Quality Gates菜单里新建一个门禁把条件绑到项目上。然后在 Jenkins 或 GitLab CI 里调用扫描命令后加一步检查任务状态。常见做法是用 sonarqube 的 Web API 查询api/qualitygates/project_status根据返回的status字段决定是否继续后续部署。另一个实用技巧是增量分析。sonarqube-7.4 本身没有“只扫变更文件”的开关但可以通过sonar.inclusions参数限定扫描范围。比如在 CI 里用git diff --name-only拿到本次提交改动的 Java 文件列表拼成逗号分隔的路径传给sonar.inclusions。这样每次只分析变更部分速度会快很多报告也聚焦在本次改动上。不过要注意增量分析会导致整体覆盖率数据不完整所以质量门禁里最好用“新增代码”维度的指标而不是全量指标。还有一个我踩过的坑sonarqube-7.4 的默认规则集里有些规则对老代码过于严格一开通就报几百个问题团队直接失去信心。我的习惯是先把质量门禁设成“只卡新增代码”让历史债务暂时挂起等新代码质量稳定后再逐步收紧。规则集也可以在Quality Profiles里复制一份默认配置关掉那些和当前技术栈不匹配的规则比如对 Java 8 项目关掉 Java 11 才有的语法检查。从那以后我每次部署 sonarqube 都强制走一遍“先调系统参数、再验数据库连接、最后用一个小项目试扫”的流程确认整条链路通了再接入正式工程。希望帮到你。本文还有配套的精品资源点击获取
