从零部署SonarQube：Docker Compose实战与中文汉化指南

SonarQube在研发团队里往往不是“要不要上”的问题，而是“什么时候上”的问题。代码量过了某个临界点以后，靠人肉 Code Review 根本盯不住那些“先记一下，以后再说”的坏味道。SonarQube 作为一款成熟的代码质量分析平台，核心价值就是把这套事情固化下来：让每次提交都过一遍机器审查，把重复率、复杂度过高、未处理异常、安全漏洞嫌疑这类问题摊开放在面板上。

这篇文章会以一个实际部署者的视角，讲清楚 SonarQube 社区版怎样从零开始部署，以及中文汉化插件怎么装、装完有哪些容易栽的坑。我也把部署过程中那些文档里不会写、只有自己动手才会遇到的细节一并整理出来。内容覆盖了部署思路、资源准备、Docker Compose 实战、插件汉化和 CI/CD 落地，读者可以按顺序操作，也可以直接把 compose 文件和命令抄走，在自己的环境里跑起来。

1. 项目思路拆解：先想清楚再动手

1.1 为什么是 SonarQube，而不是自己写脚本或选其他平台

我在给团队搭建这套平台之前，想法很简单：先找一批静态检查工具，比如 Checkstyle、PMD、ESLint，然后写脚本把检查结果汇总成报告。但很快发现这条路走不通。首先是规则分散在各工具里，报告格式五花八门；其次是没有一个统一的“质量门禁”概念，检查结果只能给人看，没法自动拦截代码合并；最后是历史数据不沉淀，今天改没改好、趋势是变好还是变差，完全看不出来。

SonarQube 把这些问题一次解决了。从 7.x 到 9.9 LTS 再到 10.x，它已经不是一个单纯的静态分析工具，而是一个完整的代码质量分析平台。它对 20 多种主流语言提供内置分析规则，覆盖 Java、Python、JavaScript、C#、Go 等；支持重复代码率、单元测试覆盖率、复杂度、代码异味、漏洞密度等指标；提供 Quality Gate（质量门禁）机制。更重要的是，它有清晰的架构分层：扫描器负责采集数据，服务端负责汇总展示，团队可以用统一的入口管理所有项目的质量状态。

选型时我还对比过一些商业产品和自研方案。商业产品在报表和审计功能上确实做得更好，但价格对中小团队不友好。自研方案维护成本高，规则更新慢，而且很少有人愿意长期维护一个“内部质检系统”。社区版的 SonarQube 虽然少了分支分析、报告导出等企业功能，但对绝大多数研发团队来说，基础的质量管理能力已经完全够用。

1.2 一句话说清 SonarQube 的工作架构

很多第一次接触 SonarQube 的人会被“服务端 + 扫描器”这种架构绕晕。我常用一个“体检中心”的类比来解释。

SonarQube 服务端就是“体检中心档案室”。它不直接读代码，只负责接收扫描结果、存储数据、展示报告、配置规则。数据库（默认建议 PostgreSQL）存结果数据，Elasticsearch 存索引和分析数据。扫描器则是“出诊医生”，它跑到你的项目代码里去，按照规则逐行检查，把发现的问题整理成统一的中间结果，再提交给档案室。

这种“采集与分析分离”的设计是 SonarQube 能够同时支持几十种语言的根本原因。扫描动作在本地或者 CI 流水线里执行，服务端集中管理，二者通过网络通信。实际使用中你会发现，服务端挂了，不影响你跑扫描命令，只是扫描结果暂时传不上去。

1.3 “部署 + 汉化”这个任务的难点在哪里

只看标题，很多人觉得 SonarQube 部署很简单：拉个镜像，启动容器，完事。真上手之后才发现，主要难度集中在几个地方。

第一是数据库版本匹配。SonarQube 对 PostgreSQL 版本有明确要求，9.x 系列对应 PostgreSQL 13 左右，10.x 版本又有不同要求。版本不匹配的时候，容器能启动，但界面会报数据库连接错误，日志里全是 SQL 异常。

第二是 Elasticsearch 的系统参数要求。SonarQube 内置了 Elasticsearch，Elasticsearch 对 Linux 系统的vm.max_map_count有最低要求。如果不调整，启动后 ES 直接崩溃，SonarQube 容器反复重启。

第三是汉化插件的版本匹配。中文包不是随便下一个装上就能用，插件版本必须和 SonarQube 服务端版本对应。装错版本最典型的症状是：插件显示已安装，界面却死活不出中文。

这些坑都不是看官方文档就能直接避开的，尤其汉化这块，很多文章只写“下载 jar 放进去重启”，不提语言包和版本对应关系，也不提用户级语言切换。所以我决定把这些内容单独拉出来，逐条给读者讲清楚。

2. 部署前准备：版本、资源和数据库选型

2.1 版本选择：LTS 还是特性版

第一次部署容易在版本上犹豫不决。我的建议很直接：生产环境用 LTS，尝鲜才用特性版。

我这篇文章以 9.9.3-community 为例。原因是 9.9 是 LTS 版本，社区维护时间最长，汉化插件有对应的稳定版本。如果你用的是 10.x，操作思路完全一样，只是中文语言包要下载对应 10.x 的版本，docker-compose 里的镜像 tag 换成sonarqube:10.6.0-community即可。

2.2 硬件资源与系统参数：别在第一步就翻车

SonarQube 不是特别吃资源，但也不是随便一台 1G 内存的小机器就能跑起来的。官方推荐最低 2 核 4G 内存，我自己实测，2G 内存跑一次全量扫描会明显卡顿，多个团队同时使用时会频繁触发 GC，甚至直接 OOM。

磁盘方面，代码库越大，历史数据涨得越快。建议给 SonarQube 的数据目录单独分一块空间，至少预留 20G 以上。Elasticsearch 的索引文件会随着项目数量线性增长，这个很多人没意识到，等到磁盘被占满的时候才发现问题。

Linux 系统上最关键的参数是vm.max_map_count。SonarQube 内置的 Elasticsearch 需要它至少达到 262144，生产环境建议设为 524288。查一下当前值：

sysctl vm.max_map_count

如果小于 262144，执行：

sudo sysctl -w vm.max_map_count=524288

这个命令只对当前会话有效，要永久生效，在/etc/sysctl.conf末尾加上一行：

vm.max_map_count=524288

然后执行sudo sysctl -p验证。这一步不做，SonarQube 容器会反复重启，日志里出现类似max virtual memory areas vm.max_map_count [65530] is too low的报错。这个问题在所有 SonarQube 部署场景里几乎都会遇到，属于第一优先级要处理的事项。

2.3 数据库方案：单独部署还是容器编排

SonarQube 必须搭配外部数据库才能稳定运行。它内置的 H2 数据库只适合评估试用，重启容器数据就会丢，团队使用绝对不能用。

生产上有两种主流方案：一种是数据库独立部署在物理机或云数据库上，适合公司已有数据库运维管理体系的情况；另一种是数据库和 SonarQube 一起用 Docker Compose 编排，适合快速搭建、不想单独维护数据库的环境。

我推荐第二种。用 Docker Compose 一次性把 PostgreSQL 和 SonarQube 启动起来，两个服务通过内部网络通信，不需要额外暴露数据库端口，安全性和易用性都兼顾了。数据持久化通过 Volume 实现，重启容器也不会丢数据。后面要升级版本，只改镜像 tag，重新执行 compose 命令就行。

3. Docker Compose 部署实操：一套能直接抄的配置

3.1 完整的 docker-compose 配置

下面是我实际使用的docker-compose.yml，可以直接复制使用。注意版本和参数我都做了注释，方便你根据自己的环境调整。

services: db: image: postgres:13 container_name: sonarqube-db restart: unless-stopped environment: POSTGRES_USER: sonar POSTGRES_PASSWORD: sonar POSTGRES_DB: sonar volumes: - sonar_db_data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U sonar -d sonar"] interval: 10s timeout: 5s retries: 5 sonarqube: image: sonarqube:9.9.3-community container_name: sonarqube restart: unless-stopped depends_on: db: condition: service_healthy ports: - "9000:9000" environment: SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar SONAR_JDBC_USERNAME: sonar SONAR_JDBC_PASSWORD: sonar volumes: - sonar_data:/opt/sonarqube/data - sonar_logs:/opt/sonarqube/logs - sonar_extensions:/opt/sonarqube/extensions volumes: sonar_db_data: sonar_data: sonar_logs: sonar_extensions:

这里有几个设计上的选择值得说明。

depends_on加上condition: service_healthy是关键细节。SonarQube 启动时如果连不上数据库，会直接报错退出。等 PostgreSQL 健康检查通过再启动 SonarQube，能避免第一次启动时的竞争条件。PostgreSQL 的 healthcheck 用的是pg_isready，这是官方镜像自带的工具，不需要额外安装。

环境变量SONAR_JDBC_URL的写法是jdbc:postgresql://db:5432/sonar，这里的db是 compose 服务名，而不是 IP。Compose 会自动创建一个内部网络，服务之间可以通过服务名互相访问。sonar既是数据库名，也是数据库用户名和密码，这三个值在 PostgreSQL 初始化阶段由POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB定义，保持一致可以避免认证问题。

有一个参数我没有在 compose 里写：SONAR_ES_BOOTSTRAP_CHECKS_DISABLE=true。网上不少教程会建议加这个环境变量来跳过 Elasticsearch 引导检查，但这是治标不治本。ES 的 bootstrap check 是为了保护它不在不满足要求的系统上运行，你把它禁了，ES 照样会因为vm.max_map_count过低而崩溃。正确做法是调好宿主机参数。

3.2 启动前的目录和镜像检查

执行docker compose up -d之前，我习惯先做三项检查：

第一，确认 Docker 和 Compose 版本。如果你用的是 Docker Desktop，通常 Compose 已经集成在里面。服务器上安装的 Docker Engine 需要单独安装 compose 插件，执行docker compose version检查。

第二，确认 9000 端口没被占用。SonarQube 默认监听 9000，如果服务器上已经有别的应用占了，容器会一直显示 “port is already allocated”。这时把 compose 里的端口映射改成9001:9000，访问的时候用http://ip:9001。

第三，把当前目录整理干净。执行 compose 命令时，所有卷数据都会带上项目名作为前缀，比如/var/lib/docker/volumes/sonarqube_sonar_db_data/。项目名默认是当前目录名，如果你在不同目录下执行过同一份 compose 文件，会产生多个孤立的卷，占用磁盘空间。我通常把项目文件放在/opt/sonarqube目录下，保持项目名固定。

三项检查没问题，执行：

docker compose up -d

第一次启动会拉取两个镜像，时间取决于网速。拉完后观察日志：

docker compose logs -f sonarqube

看到类似SonarQube is up或者访问日志中出现 200 响应，就说明启动成功了。

3.3 第一次登录和初始化配置

浏览器访问http://服务器IP:9000，不要加/sonar路径，除非你在 compose 里配置了SONAR_WEB_CONTEXT。默认管理员账号是admin，密码也是admin。9.9 版本第一次登录会要求修改密码，改成管理员的强密码后保存。

登录后建议按这个顺序做初始化：

创建管理员 Token。点击右上角头像，选择 “My Account”，再进 “Security”，生成一个 Token。这个 Token 相当于扫描器的认证凭证，后面跑sonar-scanner或者 Maven 插件时要用到。Token 只有生成时显示一次，建议复制保存到本地密码管理器。

配置项目的质量配置文件。如果你的项目主要是 Java，进入 Administration 后在 Quality Profiles 里把 Java 的默认规则集激活。社区版自带 Sonar way 规则集，一般不需要手动调整。

确认系统日志没有异常。在 Administration 的 System 页面可以看到各组件状态，正常情况全是绿色。

3.4 创建项目并完成第一次真实扫描

初始化完成后，我建议立刻拿一个真实项目跑完整流程，验证服务端和扫描器链路是通的。这里用 Java 的 Maven 项目举例。

在 SonarQube 页面点击 “Create Project”，填项目名称和项目标识。项目标识（Project Key）是唯一标识，例如my-service。创建完成后选择 “Locally”，页面会提示你用哪种方式执行扫描。

如果你用 Maven 项目，项目所在目录执行：

mvn clean verify sonar:sonar \ -Dsonar.projectKey=my-service \ -Dsonar.host.url=http://服务器IP:9000 \ -Dsonar.login=刚才创建的Token

第一次执行会比较慢，因为 Maven 需要下载 sonar-maven-plugin 以及相关的分析器。扫描完成后，日志会输出结果：

INFO: ANALYSIS SUCCESS

回到 SonarQube 页面，刷新项目，就能看到代码分析结果：Bug、Vulnerabilities、Code Smells、Coverage、Duplications 等指标全部展示在面板上。这个瞬间你会直观明白 SonarQube 这个代码质量分析平台到底在干什么。

到这里，部署和服务端到扫描端的链路已经全部打通，接下来是汉化。

4. 汉化操作：让整个平台说中文

4.1 中文语言包的正确获取方式

SonarQube 官方没有内置中文，需要安装社区维护的中文语言包插件。名气最大的插件是sonar-l10n-zh，作者是社区志愿者。获取方式有两个：在 SonarQube 管理后台的 Marketplace 里搜索 “Chinese Pack” 在线安装；或者从官方仓库的 Release 页面手动下载 jar 文件。

我在生产环境部署时推荐第二种方式。原因很简单：在线安装依赖服务器能访问外网插件仓库，很多内网环境的服务器根本连不上。而且手动下载 jar 可以根据 SonarQube 版本精确选择对应插件版本，避免装错。

最关键的一点：插件版本必须和 SonarQube 服务端版本匹配。官方仓库的 Release 版本命名是sonar-l10n-zh-plugin-9.x.jar，9.9 LTS 就选 9.x 系列，10.x 版本就选 10.x 系列。你去网上搜汉化包，可能会搜到一些来源不明的聚合包，我劝你别用。第三方魔改包可能植入了恶意逻辑，同时也可能因为版本不匹配直接导致插件加载失败。

下表是常见的版本对应关系，复制到你的笔记里：

4.2 插件安装与重启验证

拿到 jar 文件后，安装过程只需要两步：把 jar 放进插件目录，重启容器。

Docker 环境下的插件目录是容器内的/opt/sonarqube/extensions/plugins。我在 compose 文件里挂了sonar_extensions这个卷，也就是说容器重启后插件文件不会丢。传文件有两种方式。

第一种是直接复制进容器：

docker cp sonar-l10n-zh-plugin-9.9.jar sonarqube:/opt/sonarqube/extensions/plugins/ docker restart sonarqube

第二种是把插件目录从卷里拿出来，放到宿主机挂载。这种方式在需要经常更换插件时更灵活。先找到卷的挂载信息：

docker inspect sonarqube --format='{{range .Mounts}}{{.Source}}{{end}}'

然后把 jar 放到宿主机对应的 SonarQube extensions 目录里，再重启容器。

重启后稍等一两分钟，等容器完成初始化。再刷新浏览器页面，正常情况下整个界面就变成中文了。包括项目列表、质量配置、规则详情、问题面板里的各项标签，全部汉化。

这里有一个很多人不知道的细节：SonarQube 的语言偏好是用户级的。也就是说，即使管理员装了中文语言包，不同用户登录时还可能看到英文。解决方法是在个人账号设置里切换语言。点击右上角头像，进入 “My Account”，找 “Language” 选项，选择 “Chinese (zh-CN)”，保存即可。

4.3 汉化不生效的五个排查方向

汉化装完但界面没变化，是出现频率最高的求助问题。我总结过五个排查方向，按顺序检查能快速定位。

第一，插件是否真的加载成功。进入 Administration -> Marketplace -> Installed，如果插件列表里没有 “Chinese Pack”，说明 jar 没放对目录或者没加载。再查看日志文件logs/sonar.log，搜索Chinese或者l10n，看是否有加载成功的记录。

第二，浏览器缓存。SonarQube 前端资源会做缓存，装完插件后页面可能还是旧版本。强制刷新（Ctrl+F5）或开一个无痕窗口验证。

第三，是否每个用户都做了语言设置。上面说过，语言偏好是用户级的。管理员设置了中文，不代表普通用户也自动是中文。让用户在自己的账号设置里切换。

第四，插件和服务端版本不匹配。这是最隐蔽的情况。插件加载成功，界面却还是英文，多半是 jar 版本对应的语言包不兼容当前服务端版本。检查 jar 文件名里的版本号，和服务端版本比对。以 9.9.3 为例，jar 应该是 9.x 系列，不能用 10.x 的包。

第五，插件 jar 损坏。下载过程中断或文件被压缩软件破坏，会导致插件加载失败。重新下载，校验文件大小是否和 Release 页面一致。

4.4 IDE 端 SonarLint 的中文体验

平台汉化完成之后，团队成员常用的 IDE 插件 SonarLint 会自动连接 SonarQube 服务端。这里有一个概念需要厘清：IDE 插件的菜单文字是跟着 IDE 语言包的，比如 VSCode 装中文插件后菜单是中文，IntelliJ 同理。SonarLint 插件本身的操作界面不一定全中文，但它连接 SonarQube 服务端后，从服务端拉取的规则名称、问题描述会自动按服务端语言返回。所以平台装好中文包后，你在 IDE 里看到的 SonarLint 提示信息，大概率是以中文为主。

这也就是为什么很多团队把 “SonarQube 汉化” 当成一个整体优化方案，平台汉化只是第一步，IDE 端配合设置后，从代码编写到服务端扫描，整条链路都会变成中文体验。

5. 常见问题排查：部署中踩过的坑

5.1 vm.max_map_count 引发容器反复重启

现象：docker compose up -d后，SonarQube 容器状态一直在 “restarting”，日志里出现bootstrap checks failed。

原因：Elasticsearch 需要宿主机虚拟内存映射数量上限，默认 65530 不够。

解决：

sudo sysctl -w vm.max_map_count=524288 echo "vm.max_map_count=524288" | sudo tee -a /etc/sysctl.conf docker restart sonarqube

这里我强调过，不要用SONAR_ES_BOOTSTRAP_CHECKS_DISABLE=true跳过检查。跳过之后 ES 虽然没有启动失败，但运行中可能因为内存映射不足而崩溃，这类问题更难排查。

5.2 数据库认证失败或者版本不匹配

现象：SonarQube 日志中出现PSQLException: FATAL: password authentication failed for user "sonar"。

原因：主要有两个。一是 compose 文件里POSTGRES_*变量和SONAR_JDBC_*变量不一致；二是 PostgreSQL 容器初始化时用了旧的环境变量，把数据库删了重建。

解决：确认四个变量值全部一致。如果数据库卷是之前用其他密码初始化过的，需要清掉重建：

docker compose down -v docker compose up -d

注意-v会把所有命名卷删除，包括 SonarQube 的数据。如果已经有历史扫描结果，删库前要谨慎操作。

5.3 中文语言包装好，界面仍然是英文

现象：插件显示已安装，但页面还是英文。

解决：先把第一个用户的语言设置检查一遍；然后确认插件版本对应；最后看日志里插件有没有实际加载。这个问题有个很隐蔽的点：SonarQube 10.x 版本在插件加载机制上有调整，有的浏览器缓存了旧版静态资源，需要强制刷新。

5.4 Elasticsearch 内存不够导致 SonarQube 反复退出

现象：服务器内存明明有 8G，但容器运行一段时间后自动退出，日志里出现unable to allocate memory或 GC overhead。

原因：Docker 默认不限制容器内存，JVM 和 Elasticsearch 在容器里同时吃内存，一旦超过宿主机可分配量，进程会被 OOM Killer 杀掉。

解决：限制 JVM 堆内存。在 compose 文件的sonarqube服务里加环境变量：

environment: SONARQUBE_CE_JAVA_OPTS: -Xmx1g -Xms512m -XX:MaxMetaspaceSize=512m SONARQUBE_WEB_JAVA_OPTS: -Xmx1g -Xms512m -XX:MaxMetaspaceSize=512m

同时给容器加内存上限：

mem_limit: 4g

这套配置在 4G 内存的服务器上实测稳定，单项目扫描完全没有问题。

5.5 插件离线导入后提示不兼容

现象：通过 Marketplace 上传 jar，提示plugin X is incompatible with this version of SonarQube。

原因：插件元数据里的sonar.plugin.api.version和目标 SonarQube 版本不一致。这种情况多发生在从网上下载了旧版本插件或者来源不明的包。

解决：去官方仓库 Release 页面重新下载，严格按版本对应表选择。如果确实找不到匹配版本，考虑升级 SonarQube 服务端到插件支持的版本，但升级前务必备份数据卷。

5.6 端口占用检查

现象：Compose 启动不报错，但网页无法访问。

原因：9000 已经被其他进程占用，容器端口映射冲突。执行：

docker ps

看容器状态是否 Up。再用ss -lntp | grep 9000检查端口。如果被占用，改 compose 的端口映射为9001:9000。

6. 汉化完成后的落地建议：把质量平台用起来

6.1 把 SonarQube 扫描接入流水线

部署完成只是第一步，真正产生价值的是让每个项目的每次提交都自动跑扫描。以一次典型的 Git 提交为例，团队里最基础的落地方式是：在 CI 脚本中加入 SonarQube Scanner 步骤。

Jenkins 流水线的关键片段：

stage('SonarQube Analysis') { steps { withSonarQubeEnv('SonarQube') { sh 'mvn clean verify sonar:sonar -Dsonar.projectKey=my-service' } } }

GitLab CI 的.gitlab-ci.yml关键片段：

sonarqube-check: stage: test script: - mvn clean verify sonar:sonar -Dsonar.projectKey=my-service -Dsonar.host.url=$SONAR_HOST_URL -Dsonar.token=$SONAR_TOKEN

扫描命令本身很简单，关键是把 Token 和服务器地址通过环境变量注入，不要把密钥写死在代码仓库里。

接入 CI 以后，每次 MR 触发的流水线都会自动分析代码，分析结果直接关联到 MR 页面。提交代码的人可以在一小时内看到问题清单，而不是等到代码评审时才被人指出。

6.2 质量门禁怎么配置才有实际效果

质量门禁是 SonarQube 真正发挥强制约束力的地方。如果扫描结果只是给团队看，那和质量报告工具没区别。配置了门禁之后，指标不达标就说明扫描不过关，整个合并流程被阻断，质量问题才会真正被重视。

我会为 Java 后端团队这样配置门禁：

配置位置在 Quality Gates 页面，默认的 Sonar way 是一个不错的起点，你可以在它的基础上复制一份，针对自己团队的技术栈调整阈值。需要提醒的是，门禁不是越严越好。刚开始可以把覆盖率要求设为 60%，跑一段时间让团队适应，再逐步收紧到 80%。如果一上来就要求 80%，团队会花大量时间写测试，而不是理解质量问题本身，效果反而不好。

6.3 从历史存量代码到增量控制的演进路线

搭好平台之后，最先要面对的现实是：存量代码问题一大堆，门禁一亮红灯，整个团队都傻眼。这种时候我的经验是：不要试图一次性清零存量问题，先把新增代码控制住。

SonarQube 的项目面板天然区分了 “新增代码” 和 “存量代码”。把质量门禁只卡在新代码上，存量问题单独建任务池，每周挑一类问题修复。这样团队的压力不会爆炸，平台的价值也能在第一个月就体现出来：新提交不会引入新的坏味道，存量问题逐步减少。

我在实际操作中的体会是，汉化做完之后，团队成员使用平台的意愿会明显提升。中文界面降低了一部分同事的使用门槛，至少他们能直接看懂 “提升了多少覆盖率” 而不是看到一个英文面板发懵。平台部署只是开始，真正改变研发习惯的是后续的质量门禁和自动化流水线。别急着把所有规则都打开，先跑通一条主流程，再慢慢加指标，这样整个平台才能在团队里稳扎稳打地落地。

最后再分享一个小技巧：SonarQube 数据卷记得定期备份。用一个简单的定时任务，晚上把数据目录打成 tar 包上传到备份服务器，别等到数据丢失了才想起备份这件事。我见过太多团队把质量平台搭得漂漂亮亮，结果一次服务器迁移丢了全部历史分析数据，项目趋势线一夜回到解放前。