企业官网建设流程全解析

简介：SonarQube 7.4 是一款开源代码质量管理工具的完整安装包，面向 Java、Python、C#、JavaScript 等多语言开发者与测试团队，用于在开发流程中检测代码漏洞、代码异味与复杂度问题，提升可维护性。压缩包为 rar 格式，体积约 161.38MB，内含 bin、conf、extensions、lib、web、libexec 等标准目录及 README、LICENSE 说明文件，分别承载启动脚本、配置项、插件扩展、运行库、前端界面资源与辅助工具，解压后即可按官方结构部署使用。该版本发布于 2018 年，在分析能力与用户体验上做了针对性优化，适合需要搭建本地代码质量平台或与 Jenkins、GitLab CI/CD 集成的团队参考。目前已有 637 人学习下载，可作为快速获取 7.4 版本、规避官网下载缓慢问题的实用资源，帮助读者省去等待时间，直接进入环境配置与代码扫描实践。

1. 从一台老版本 SonarQube 说起：sonarqube-7.4 到底能解决什么

很多团队第一次想给代码库加一道静态扫描门禁时，翻到的都是 SonarQube 这个老牌平台。而 sonarqube-7.4 这个版本，恰好卡在一个很微妙的位置：它比 5.x、6.x 稳定得多，又不像 8.x 之后那样强制要求 JDK 11 和一堆新依赖，对还在跑 JDK 8 的老项目特别友好。我见过不少公司内网里至今还挂着一套 7.4，专门给历史遗留系统做代码质量看板。它能干的事很实在——把 Java、JS、Python 等语言的坏味道、重复代码、潜在缺陷、覆盖率统一收进一个 Web 界面，再配合质量门禁卡住合并请求。适合谁？适合那些不想大动干戈升级基础设施、只想先把扫描跑起来的中小团队，以及需要离线部署、内网隔离环境的场景。这一篇就按我实际拆包、部署、接扫描器的顺序，把 sonarqube-7.4 从安装到出报告讲透。

2. 部署 sonarqube-7.4：环境、数据库与启动参数

2.1 为什么 7.4 对 JDK 和数据库这么挑

SonarQube 7.4 官方要求 JDK 8，注意是 8，不是 11。我试过用 JDK 11 启动，日志里会直接抛UnsupportedClassVersionError，因为它的启动脚本和部分字节码是按 52.0 编译的。数据库方面，7.4 支持 PostgreSQL 9.6～10、MySQL 5.7、Oracle 等，但内置的 H2 只能用于演示，生产环境必须换掉。这里有个血泪经验：如果你用 MySQL，一定要把sql_mode里的ONLY_FULL_GROUP_BY去掉，否则初始化建表时就会报错，而且报错信息很隐晦，只提示某条 SQL 语法问题，不查文档根本想不到是 sql_mode 的锅。

常见做法是直接上 PostgreSQL 10，兼容性最好，社区踩坑记录也最多。下面是我一般会用的初始化步骤，先建库建用户，再改 sonar.properties。

# 创建数据库和用户，注意编码必须是 UTF8 CREATE DATABASE sonar WITH ENCODING 'UTF8' OWNER sonar; CREATE USER sonar WITH PASSWORD 'sonar_pass'; GRANT ALL PRIVILEGES ON DATABASE sonar TO sonar;

# conf/sonar.properties 关键几行 sonar.jdbc.username=sonar sonar.jdbc.password=sonar_pass sonar.jdbc.url=jdbc:postgresql://127.0.0.1:5432/sonar sonar.web.host=0.0.0.0 sonar.web.port=9000 sonar.web.context=/sonar

逻辑说明：sonar.jdbc.url里的库名、地址、端口要和你实际环境一致；sonar.web.context设成/sonar是为了后面用 Nginx 反代时路径统一，不设也能跑，但反代时容易出静态资源 404。参数上，sonar.web.port默认 9000，如果被占用就改，但改完记得防火墙放行。启动前还要确认sonar.jdbc.username对应的用户有建表权限，否则第一次启动会卡在数据库迁移阶段，日志里能看到Fail to execute CREATE TABLE。

2.2 启动脚本与内存参数怎么调

7.4 的启动脚本在bin/下，Linux 用sonar.sh，Windows 用StartSonar.bat。我一般不会直接改脚本，而是通过环境变量SONAR_SCANNER_OPTS和SONAR_WEB_JAVAOPTS来调。默认堆内存对中小项目够用，但如果代码库超过 50 万行，Web 进程容易 OOM，表现是页面转圈然后 502。这时候把sonar.web.javaOpts里的-Xmx调到 2G 以上，同时sonar.ce.javaOpts也相应调大，因为计算引擎才是真正吃内存的。

# 启动前先确认没有残留进程 ps -ef | grep sonar # 启动 ./bin/linux-x86-64/sonar.sh start # 看日志确认启动成功 tail -f logs/sonar.log

启动成功的标志是日志里出现SonarQube is up。如果一直停在Process[web] is stopped，八成是数据库连不上或者 JDK 版本不对。这里有个玄学问题：有时候数据库明明能连，但 SonarQube 就是起不来，最后发现是sonar.jdbc.url里带了?useUnicode=true&characterEncoding=utf8这种 MySQL 参数，PostgreSQL 不认，直接解析失败。所以参数别乱抄，按数据库类型来。

3. 接入扫描器：从 Maven 项目到多语言混合仓库

3.1 Maven 项目用 sonar-maven-plugin 最省事

Java 项目接 SonarQube 7.4，最顺手的还是 Maven 插件。在pom.xml里加一段 plugin，然后命令行传 Sonar 地址和 token 就行。注意 7.4 时代 token 机制已经存在，但很多人还在用 admin/admin 默认密码，这在生产环境是大忌。先生成 token，再在命令里用-Dsonar.login传。

<plugin> <groupId>org.sonarsource.scanner.maven</groupId> <artifactId>sonar-maven-plugin</artifactId> <version>3.6.0.1398</version> </plugin>

mvn clean verify sonar:sonar \ -Dsonar.host.url=http://192.168.1.10:9000/sonar \ -Dsonar.login=你的token \ -Dsonar.projectKey=my-java-app \ -Dsonar.projectName="My Java App"

逻辑说明：sonar:sonar这个 goal 会先编译再扫描，所以clean verify不能省，否则字节码缺失会导致部分规则失效。sonar.projectKey是唯一标识，重复用同一个 key 会覆盖上次结果，想保留历史就换 key。参数上，sonar.host.url如果配了 context path，一定要带上/sonar，不然 scanner 会往根路径发请求，报 404。扫描完成后去 Web 界面看，如果覆盖率是 0，检查是否引入了 jacoco 插件并生成了jacoco.exec，7.4 不会自动帮你跑测试覆盖率。

3.2 非 Maven 项目用 sonar-scanner 命令行

前端、Python、Go 这些没有 Maven 的项目，就用独立的 sonar-scanner。下载对应平台的压缩包，解压后把bin加到 PATH，然后在项目根目录写一个sonar-project.properties。这个文件是扫描器的黑匣子，配错了它不会报错，只会默默少扫文件。

sonar.projectKey=my-web-app sonar.projectName=My Web App sonar.sources=src sonar.exclusions=**/node_modules/**,**/dist/**,**/*.min.js sonar.javascript.lcov.reportPaths=coverage/lcov.info sonar.sourceEncoding=UTF-8

逻辑说明：sonar.sources指定源码目录，多个目录用逗号隔开；sonar.exclusions必须写，否则 node_modules 会被扫进去，扫描时间从几分钟变成几小时。sonar.javascript.lcov.reportPaths指向前端覆盖率报告，7.4 对 JS 覆盖率的支持已经比较完善，但要求 lcov 格式，jest 和 karma 都能生成。参数上，sonar.sourceEncoding建议显式设成 UTF-8，不然中文注释可能乱码，导致规则误判。

sonar-scanner -Dsonar.host.url=http://192.168.1.10:9000/sonar -Dsonar.login=你的token

执行后如果提示Project not found，检查 projectKey 是否和 Web 上已有项目冲突；如果提示No files to analyze，检查sonar.sources路径是否写错，相对路径是相对于sonar-project.properties所在目录的。

3.3 多语言混合仓库怎么拆 projectKey

一个仓库里同时有 Java 后端和 Vue 前端，我一般会拆成两个 projectKey，分别扫描。因为 7.4 的规则集是按语言激活的，混在一起扫会导致某些语言规则不生效，而且覆盖率报告也难合并。常见做法是后端用 Maven 插件，前端用 sonar-scanner，两个 key 分别叫xxx-backend和xxx-frontend，在 Web 上通过同一个项目组视图关联起来。这样质量门禁可以分别设置，后端卡覆盖率，前端卡重复率，互不干扰。

4. 避坑与排查：7.4 版本特有的几个坑

4.1 启动报错AccessDeniedException或Unable to create database

现象：第一次启动，日志里出现AccessDeniedException或者Unable to create database，但数据库明明能连。 原因：SonarQube 7.4 初始化时会尝试建表，如果数据库用户没有 CREATE 权限，或者 PostgreSQL 的 schema 权限没给，就会失败。 解决：给 sonar 用户授予CREATE和USAGE权限，PostgreSQL 下执行GRANT ALL ON SCHEMA public TO sonar;，然后删掉data/目录重新启动。

4.2 扫描 Java 项目时提示Please provide compiled classes

现象：Maven 项目扫描后，代码规则跑了，但缺陷和复杂度全是 0。 原因：sonar:sonar没有拿到编译后的 class 文件，7.4 的 Java 分析器依赖字节码做部分规则。 解决：确保执行了mvn clean verify再跑sonar:sonar，或者显式指定-Dsonar.java.binaries=target/classes。如果是多模块项目，每个模块的target/classes都要包含进去。

4.3 Web 界面能打开但扫描结果不更新

现象：scanner 显示ANALYSIS SUCCESSFUL，但 Web 上还是旧数据。 原因：7.4 的计算引擎（Compute Engine）任务堆积，或者后台任务失败但没提示。 解决：用 admin 登录，进 Administration → Background Tasks，看有没有失败的任务。如果有，点开看日志，常见的是数据库连接超时或者内存不足。把sonar.ce.javaOpts的-Xmx调大，重启服务，再重新触发扫描。

4.4 质量门禁不生效，合并请求照样能过

现象：配了 Quality Gate，但 CI 里扫描失败后流水线还是绿的。 原因：7.4 的 scanner 默认不会因为质量门禁失败而返回非零退出码，需要额外加参数。 解决：在扫描命令后加-Dsonar.qualitygate.wait=true，这样 scanner 会轮询等待门禁结果，不通过就返回 1。注意这个参数在 7.4 上需要 scanner 版本 3.3 以上，太老的 scanner 不认。

4.5 中文乱码导致规则误报

现象：代码里的中文注释被识别成乱码，触发一堆“注释包含非法字符”的告警。 原因：scanner 所在环境的默认编码不是 UTF-8，或者sonar.sourceEncoding没设。 解决：在sonar-project.properties里显式写sonar.sourceEncoding=UTF-8，同时确认LANG环境变量是en_US.UTF-8或zh_CN.UTF-8。如果是 Windows 环境，还要在启动脚本里加-Dfile.encoding=UTF-8。

5. 进阶技巧：用 Web API 把扫描结果接进自己的看板

SonarQube 7.4 的 Web API 已经比较完整，我经常用它把数据拉到内部看板，而不是天天让人登录 Sonar 界面。最常用的两个接口：/api/measures/component拿指标，/api/qualitygates/project_status拿门禁状态。下面这段 Python 脚本是我一般会用的，先拿 token 换 session，再查指定项目的 bug 数和覆盖率。

import requests from requests.auth import HTTPBasicAuth SONAR_URL = "http://192.168.1.10:9000/sonar" TOKEN = "你的token" PROJECT_KEY = "my-java-app" # 拿核心指标 resp = requests.get( f"{SONAR_URL}/api/measures/component", params={ "component": PROJECT_KEY, "metricKeys": "bugs,vulnerabilities,code_smells,coverage,duplicated_lines_density" }, auth=HTTPBasicAuth(TOKEN, "") ) data = resp.json() for m in data["component"]["measures"]: print(m["metric"], m["value"]) # 拿质量门禁状态 gate = requests.get( f"{SONAR_URL}/api/qualitygates/project_status", params={"projectKey": PROJECT_KEY}, auth=HTTPBasicAuth(TOKEN, "") ).json() print("Gate status:", gate["projectStatus"]["status"])

逻辑说明：auth=HTTPBasicAuth(TOKEN, "")是 7.4 推荐的认证方式，token 当用户名，密码留空。metricKeys可以按需组合，完整列表在 Web 界面的/api/measures/search里能查到。参数上，component就是 projectKey，别传成项目名。如果返回 401，检查 token 是否过期或者被撤销；如果返回 404，检查 context path 是否拼错。

拿到数据后，我一般会写进内部 Grafana 或者直接发到群里，这样团队不用登录 Sonar 也能看到趋势。还有一个技巧：用/api/ce/task查后台任务状态，配合 CI 做重试。比如 scanner 提交后，轮询这个接口直到任务完成，再决定是否放行流水线。这比单纯等sonar.qualitygate.wait更可控，因为你能看到任务卡在哪个阶段。

从那以后我每次部署 sonarqube-7.4，都强制走一遍“先验 JDK 版本、再验数据库权限、最后验 scanner 参数”的流程，少一步都可能半夜被叫起来看日志。希望帮到你。

本文还有配套的精品资源，点击获取