本地搭建SonarQube静态扫描环境：Docker Compose与sonar-scanner实战

我在本地跑 SonarQube 静态扫描代码环境搭建起因特别朴素某个内部管理后台项目的代码到了三四万行以后我越来越清楚一件事——人工 Code Review 根本盯不住空指针、资源未关闭、字符串拿 比较这类底层问题它们藏在具体执行路径里靠肉眼看不出来。于是我把 SonarQube 的服务端、数据库和扫描器在本地环境整套跑了一遍用它给这个仓库做了一次全量代码体检。这篇文章就是把整个流程摊开讲清楚组件怎么配合、环境怎么准备、Docker Compose 怎么编排、扫描器怎么接、报告怎么看以及我踩过的几个坑希望对打算在本地跑代码质量扫描的人有点帮助。1. 先搞清楚本地这套 SonarQube 的组件到底怎么配合1.1 为什么静态扫描能补上人工 Review 的盲区人工 Code Review 的价值在于逻辑、架构、可读性这些需要判断力的地方但一个三四万行的 Java 项目里真正高频出现、又最容易漏掉的往往是另一类问题。比如某个方法可能收到 null 却在第一行就解引用打开的文件流在异常路径上没关闭两个字符串用 比较判断是否相等。这些问题的共同点是单看一行代码根本看不出来需要跨方法、跨分支地做数据流分析而人的短期记忆和精力根本覆盖不过来。静态扫描工具恰好擅长这类检查。SonarQube 的分析规则大致分三类Bug 表示可能影响程序正确性的缺陷漏洞表示安全层面的风险坏味道则表示维护性问题比如方法过长、复杂度过高、命名不规范。扫描器会把这四类问题按严重程度打上标签再顺势算出技术债务——一个用时间刻度量化代码维护成本的口径。代码质量从碰巧被 Reviewer 发现变成每次扫描都被机器拦一道这是静态扫描最核心的价值。我在本地搭这套环境就是想先把这个机器检查的入口跑通后面再谈怎么进门禁、怎么接流水线。1.2 服务端、数据库、扫描器的三角色分工很多第一次接触的人会以为 SonarQube 只是一个软件装完就能扫实际上它是三个进程协作的架构。服务端SonarQube Server负责管理规则、质量门禁、项目配置和报告展示所有分析结果最终都在这里看。数据库官方推荐 PostgreSQL服务端所有元数据、项目快照、历史记录都存在这里。扫描器sonar-scanner运行在项目目录里的独立 CLI负责实际读取源码、执行分析插件、生成结果并上传给服务端。可以用一个体检的类比来理解扫描器是体检医生服务端是病历系统数据库是档案柜。医生做完检查Scanner 扫源码把报告录入病历系统上传给 Server病历系统再把历史数据归档写入数据库。这三个角色缺一个整个链路都跑不通。只装 Server 不装 Scanner你永远拿不到新报告只装 Scanner 没 Server分析结果没地方存放窗口界面也看不到Server 没有数据库直接启动失败。所以本地搭建的顺序应当是先跑数据库再跑服务端最后用扫描器去对接。这也是下面第三章用 Docker Compose 一次性编排两个容器的原因。1.3 本地搭建和流水线搭建的核心差异标题里特别标了本地环境是因为本地搭建和团队流水线搭建的目标完全不同。对比项本地搭建流水线搭建主要目的快速验证、学习、摸清规则团队统一入口MR/PR 自动触发数据存储本机 Docker 卷服务器或云存储扫描触发手动执行 sonar-scannerCI 钩子自动执行试错成本极低删卷重来较高涉及权限与权限本地环境最大的好处是试错成本低改配置、删卷、换版本都很容易笔记本上只是多了几个容器而已。但这里有个现实问题这台电脑同时还要跑 IDE、数据库、微服务内存分配一定要预留好如果你用的是 Docker Desktop默认资源常常不够后面第三章会细说。我个人很推荐从本地开始而不是一上来就折腾 CI因为先把本地链路跑通这份 docker-compose 配置后来基本可以直接搬到团队内网服务器只改端口和资源上限改动量很小。2. 环境准备JDK、Docker 资源与默认账号2.1 版本选型与 JDK 前置条件先明确本机需要什么。SonarQube 服务端本身跑在官方 Docker 镜像里容器内自带 JDK所以服务端一侧你不需要额外装 Java。但扫描器是直接跑在宿主机上的 CLI它依赖本机 Java。版本对应关系大概是这样的组件版本要求说明SonarQube 10.xJDK 17容器内自带宿主无需单独装sonar-scanner CLIJDK 17本机需要配置 JAVA_HOMESonarQube 9.xJDK 11老版本本地学习不建议再用PostgreSQL1215太老版本和新版 Server 可能不兼容镜像标签建议直接用sonarqube:lts-community或者固定到一个明确的版本号比如10.x-community。用 LTS 系列省心避免某天启动后发现 API 字段变了。数据库镜像用postgres:15就够。如果你本机 JDK 是 21扫描器一般也能跑但万一遇到兼容问题优先检查版本跨度。2.2 Docker 资源分配与 vm.max_map_countSonarQube 内部内置了 Elasticsearch 作为搜索引擎和索引组件启动时非常吃内存。官方容器默认堆是 2GB加上 PostgreSQL、操作系统、你本机同时开着的 IDEDocker Desktop 默认分配的 2GB 内存基本不够用。我建议至少给 Docker 3.54GB。打开 Docker Desktop 的设置Resources → Memory 往上调然后 Apply Restart这一步先做否则后面很可能卡在容器起不来。如果你在 Linux 里跑或者 Docker Desktop 用的是 WSL2 内核且版本偏旧大概率会碰到一个经典错误max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]。这个参数是 Linux 内核允许的虚拟内存映射区数量Elasticsearch 对它有硬性要求。修复方式很直接sudo sysctl -w vm.max_map_count262144想永久生效把vm.max_map_count262144写进/etc/sysctl.conf再执行sysctl -p。macOS 的 Docker Desktop 新版一般会自动处理但如果你改过自定义内核还是可能遇到。我建议提前把这条命令记在备忘录里等报错时直接拿出来用。2.3 默认账号与首次登录所有容器启动并完成初始化之后浏览器访问 http://localhost:9000默认账号是 admin/admin。第一次登录系统会强制要求修改密码改完才会进入主界面。这里有个小坑我遇到过同事改完新密码后忘记保存再也登录不进去。由于这是本地环境最省事的做法不是去数据库里折腾密码而是直接把容器和卷删掉重新起一套docker compose down -v docker compose up -d本地环境的卷删掉重来很划算但前提是里面还没有值得保留的扫描数据。已经扫了一堆项目的话记得先导出配置或报告再动-v参数不然数据就没了。3. 用 Docker Compose 把数据库和服务端一次性编排起来3.1 完整的 docker-compose.yml 与逐行拆解我在项目根目录放了一个docker-compose.yml内容如下services: postgres: image: postgres:15 container_name: sonar-postgres environment: POSTGRES_USER: sonar POSTGRES_PASSWORD: sonar POSTGRES_DB: sonar volumes: - pg_data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U sonar] interval: 10s timeout: 5s retries: 10 sonarqube: image: sonarqube:lts-community container_name: sonarqube depends_on: postgres: condition: service_healthy ports: - 9000:9000 environment: SONAR_JDBC_URL: jdbc:postgresql://postgres:5432/sonar SONAR_JDBC_USERNAME: sonar SONAR_JDBC_PASSWORD: sonar volumes: - sonar_data:/opt/sonarqube/data - sonar_extensions:/opt/sonarqube/extensions - sonar_logs:/opt/sonarqube/logs volumes: pg_data: sonar_data: sonar_extensions: sonar_logs:逐个字段拆开看。postgres 服务的三个环境变量对应 PostgreSQL 初始化时的账号、密码、数据库名和后面 SonarQube 的 JDBC 环境变量必须一一对应。healthcheck 是关键新版 SonarQube 容器启动时需要数据库先就绪用depends_on的condition: service_healthy比无脑 sleep 更可靠PostgreSQL 就绪后 SonarQube 才会开始初始化。SonarQube 的环境变量三件套是 JDBC URL、用户名、密码注意 URL 里的postgres:5432是 Docker 网络内的服务名和端口不是本机的 localhost。端口 9000 是 Web 界面的默认入口不需要改。最后的 volumes 映射了 SonarQube 的数据、插件、日志三个目录这个下面单独讲。如果你在旧教程里看到 docker-compose.yml 开头带着version: 3这种字段可以忽略新版 Docker Compose 已经不需要它了直接按上面的结构写就行。3.2 数据卷映射为什么容器删了结果还在如果不配 volumes容器一旦删除所有分析数据、插件、日志都会一起消失之前扫过的项目记录全没了。配了卷之后无论镜像怎么升级、容器怎么重建数据都持久化在 Docker 卷里不会受影响。三个目录的职责不一样/opt/sonarqube/data放的是项目元数据和扫描快照/opt/sonarqube/extensions放插件比如后面要装的汉化包、各语言插件/opt/sonarqube/logs放运行日志。我特意把日志也单独拎出来是因为排错的时候只需要看 logs 目录里最新的文件不用翻整个容器文件系统排查内存、插件加载问题的效率会高很多。有一点要牢记docker compose down不会删卷但docker compose down -v会连卷一起删除。如果只是想升级镜像别加-v只有确实要推倒重来的时候才用带-v的命令。另外可以用docker system df看卷占用的磁盘大小本地磁盘吃紧时这个很有用。3.3 启动后的等待与冒烟验证配置文件准备好之后在 docker-compose.yml 所在目录执行docker compose up -d docker compose ps第一次启动会比较慢服务端要做数据库迁移、创建索引、加载插件我在机器上等过接近 3 分钟。不要看到日志一直滚动就以为是死循环等就完事了。可以用下面命令看实时日志docker compose logs -f sonarqube当日志里出现类似 SonarQube is up 或者 HTTP server started on port 9000 的信息时基本就绪了。此时打开浏览器访问 http://localhost:9000如果看到正在初始化的提示页面刷新几次直到登录框出现。也可以用 curl 快速验证 API 是否可用curl -I http://localhost:9000返回 200 或 302 都说明 Web 服务在工作。到这里服务端和数据库这半边就完成了。4. 从创建项目到拿到第一份扫描报告4.1 在 Web 界面创建项目与生成令牌服务端页面能正常打开后第一步是在服务端创建项目。登录后点右上角的选择手动创建项目填一个全局唯一的项目标识比如internal-admin-backend显示名称可以写中文分析方式选择本地。接下来系统会引导你创建访问令牌也就是 token创建好后务必复制保存这个 token 只在弹出窗口里显示一次关掉就再也看不到原值丢了只能重新生成。令牌在 SonarQube 里的地位比账号密码更实用。API 虽然也支持账号密码直接认证但令牌可以独立生成、独立过期、只绑定对应项目权限想撤销某个扫描入口时直接删令牌不需要动主账号。扫描命令里用 token 也比把密码明文写在历史记录里干净得多。这里给个安全提醒token 属于敏感信息不要提交到 git也不要写进sonar-project.properties。后面触发扫描时用-Dsonar.tokenxxx或者设置环境变量SONAR_TOKEN两种方式都行。4.2 安装配置 sonar-scanner扫描器是独立的 CLI 工具不需要在本机再装一遍服务端。去官方开发者页面下载和你系统匹配的 sonar-scanner 压缩包解压到某个固定目录然后把bin目录加进 PATH。Windows 上对应的是sonar-scanner.batmacOS/Linux 上是sonar-scanner。安装完验证一下sonar-scanner -v如果提示找不到 Java先确认JAVA_HOME指向 JDK 17。扫描器进程跑在宿主机服务端在 Docker 容器里它们通过 HTTP 9000 端口通信所以只要本机能访问 localhost:9000链路就是通的。我强烈建议你第一次扫某个小目录而不是直接扫整个仓库。可以先找一个干净的目录放一个最小的sonar-project.properties跑通配置 → 扫描 → 上传 → 出报告整个闭环再扩大到真实项目。一次就把全仓库几万行投进去如果配置有问题排查周期会被拉得很长。4.3 配置 sonar-project.properties 并触发第一次扫描在项目根目录创建sonar-project.properties这是扫描器读取配置的入口sonar.projectKeyinternal-admin-backend sonar.projectNameInternal Admin Backend sonar.projectVersion1.0.0 sonar.sourcessrc/main/java sonar.java.binariestarget/classes sonar.sourceEncodingUTF-8字段的含义方面sonar.projectKey必须和 Web 界面创建项目时填的标识一致sonar.sources指向要分析的源码目录sonar.java.binaries指向编译后的 class 文件目录sonar.sourceEncoding一般用 UTF-8避免中文注释乱码。对 Java 项目来说触发扫描前必须先编译这一步非常重要mvn clean compile sonar-scanner -Dsonar.host.urlhttp://localhost:9000 -Dsonar.token你的token看到 ANALYSIS SUCCESSFUL 或 INFO: EXECUTION SUCCESS 之类的日志就说明扫描结果已经上传到服务端了回到项目页面刷新就能看到报告。如果只配置了sonar.sources没有编译产物target/classesSonarJava 的很多语义规则是不会触发的。我一开始就吃过这个亏报告里整整少了一级分析看起来项目特别干净实际上规则根本没生效。没有字节码扫描器只能做文本和语法层面的有限分析数据流追踪基本失效。4.4 第一份报告怎么看扫描完成后进入项目首页顶部一排指标映入眼帘Bugs、Vulnerabilities、Code Smells、Coverage、Duplications旁边还有质量门禁状态。各自含义如下Bugs可能影响程序正确性的缺陷比如空指针、资源未关闭。Vulnerabilities安全角度的问题比如 SQL 注入风险。Code Smells维护性问题比如复杂度过高、命名不规范。Coverage 和 Duplications需要额外接覆盖率工具或在规则里开启本地纯静态扫描默认拿不到准确覆盖率。质量门禁是这套系统里最有用的机制之一。默认的 Sonar Way 门禁盯的是新代码新增代码里不允许有 Bug 和漏洞覆盖率有下限坏味道数量也有限制。也就是说老代码里的历史债务先不冻结但新写的东西不能继续恶化这正好符合团队逐步整改的节奏。点击某个具体问题会看到源码片段、规则说明、严重级别和修复建议。修复问题后重新扫描相关条目会自动消失项目门禁状态也会跟着更新。从这一步开始SonarQube 就从扫描工具变成了持续的质量反馈机制。5. 验证链路可靠性埋几个典型坏味道看扫描器抓不抓得到5.1 为什么要专门验证一遍扫描成功和规则真的生效是两件事。我第一次搭完环境的时候扫描跑了二十多秒报告页面干干净净我当时真以为项目质量还不错后来检查才发现是缺编译产物语义规则全没触发。所以如果你也刚搭完我建议先别急着给项目下结论专门做一轮埋雷验证。具体做法是找一个测试模块或新建一个临时目录写一个故意包含典型问题的类丢给扫描器看它能不能准确报出来。这个验证的价值有两个一是确认服务端、扫描器、规则库整条链路真的在工作二是给自己建立报告可信度的直觉。以后你看到报告里的空指针告警就不会心里犯嘀咕是不是误报。5.2 埋雷样例与预期结果我准备的样例类长这样刻意包含三个典型问题import java.io.BufferedReader; import java.io.FileReader; import java.io.IOException; public class DemoIssues { private static final String OK OK; public String check(String status) { if (status OK) { return good; } return bad; } public String readFile(String path) throws IOException { BufferedReader reader new BufferedReader(new FileReader(path)); return reader.readLine(); } public int length() { String s null; return s.length(); } }三个问题分别对应三种典型场景样例代码预期规则问题类型status OK字符串字面量不应使用 比较坏味道BufferedReader未关闭资源应当被关闭Bug局部变量赋 null 后调用方法空指针不应被解引用Bug这段代码是我故意写得糟糕的演示样例实际开发中千万不要这么写。5.3 扫描结果对照与规则触发逻辑把上面的类放进一个独立目录配置好sonar-project.properties后跑一次扫描预期的报告大概是Bugs 数量为 2Code Smells 数量为 1Vulnerabilities 为 0。如果三个问题都被准确识别说明链路没有问题。扫描器能识别这些问题依赖的是语法树和字节码指令分析再叠加数据流追踪。以空指针为例扫描器构建出变量 s 在赋值处已为 null之后.length()调用越过了空值检查这个路径然后才判定为可疑。未关闭流则是字节码层面的资源跟踪凡是打开了可关闭资源却没有在 try-with-resources 或 finally 中关闭的都会被记录。字符串比较则是典型的规则匹配一看到两侧是字符串字面量就直接标记。如果报告里没有出现预期问题从三个方向排查第一确认target/classes下确实有.class文件没有就重新编译第二确认sonar.sources路径指到了包含这个类的目录第三看扫描日志里有没有no bytecode found之类的警告。这三步排查基本能覆盖 90% 的规则失效场景。6. 本地环境最常见的故障排查与经验沉淀6.1 内存不足导致服务起不来这是本地环境遇到概率最高的故障。现象是docker compose up -d之后SonarQube 容器反复重启日志里出现 Elasticsearch 相关错误。常见报错有两种一种是 max virtual memory areas vm.max_map_count 太低另一种是 insufficient memory for the Java Runtime Environment。排查链路按顺序走docker compose ps看哪些容器没有正常启动docker compose logs sonarqube | tail -50看真实报错宿主机执行free -h确认内存余量如果是 max_map_count 问题执行sudo sysctl -w vm.max_map_count262144如果是内存不够把 Docker Desktop 的 Memory 调高或者停掉不用的容器释放资源。错误类型解决方案vm.max_map_count 太低调高内核参数容器内存不足加大 Docker 资源分配Java Heap 溢出本地一般不需要动先查前两项核心思路是先判断是内核参数限制还是物理内存真的不够前者修参数后者调配置不要一上来就改 SONAR_JAVA_OPTS本地环境往往轮不到那一步。6.2 端口冲突第二个常见问题是 9000 端口被占用。本地同时跑的东西太多端口冲突迟早遇到。启动时报 address already in use就是这个原因。排查方式很简单macOS/Linux 上执行lsof -i :9000Windows 上执行netstat -ano | findstr 9000确认哪个进程占用了端口后要么杀掉它要么改 docker-compose.yml 的端口映射比如9001:9000。改了端口之后浏览器访问 localhost:9001扫描命令里的-Dsonar.host.url也要跟着改成 http://localhost:9001。我个人的习惯是固定用 9000其他本地服务刻意避开这样扫描命令可以一直复用不用每次改地址。6.3 扫描器连不上服务端执行 sonar-scanner 时出现 Fail to request and parse http://localhost:9000/api/... 之类的报错基本就是扫描器和服务端的通信问题。排查链路如下先确认服务端页面能打开如果页面都不行回到前面修容器用 curl 测试 API 是否正常curl http://localhost:9000/api/system/status能返回 JSON 说明服务端 API 正常问题出在扫描器侧参数3. 检查-Dsonar.host.url有没有写错协议比如误写成 https或者多了尾斜杠4. 检查 token 有没有复制多余的空格或换行5. 如果 docker-compose.yml 端口映射是9000:9000默认会绑定到 0.0.0.0局域网内其他机器也能访问本地环境要注意这一点。还有一个隐藏坑是版本跨度老版本的 scanner 连新版服务端API 字段对不上也会握手失败。建议都用 LTS 系列镜像和对应版本的 scanner尽量减少不必要的变量。6.4 从本地走向团队环境的迁移经验虽然这篇文章的主题是本地环境但大多数人搭这套东西最终是想让团队用起来。根据我自己的经验本地跑通之后往团队环境迁移时改动其实不大把同一份 docker-compose.yml 放到一台内网常驻机器调大容器内存与磁盘服务端用固定 IP 或域名token 换成专用服务账号的令牌scanner 不装在个人电脑放进 CI 里统一下载固定版本有需要时配置 Webhook 或者质量门禁回调让提交被自动拦截。本地环境最大的价值不是替代线上而是让你在一个可以反复推倒重来的沙盒里把组件关系、配置含义、规则逻辑全部摸透。这一轮摸完之后后面接流水线还是接其他平台都只是换入口核心架构没有变。最后分享一个小习惯本地每搭成功一次我都会把 docker-compose.yml 和示例 sonar-project.properties 存进工作笔记备注当时用的镜像标签和 scanner 版本。几个月后你大概率会忘记当时用的是哪个 LTS 标签重新翻文档的成本比顺手写一行备注高得多。本地环境本来就是拿来折腾的但折腾完之后把经验沉淀下来这套环境的价值才算真正落到了自己的技能树上。