企业官网建设流程全解析

Docker部署SonarQube这事，看起来就是一个docker compose up -d的事，真正跑起来才会发现坑不少。SonarQube作为代码质量管理的利器，能做静态扫描、Bug检测、坏味道识别、安全漏洞排查，还能直接对接CI/CD做质量门禁，是很多团队代码评审之外的自动化质量防线。但传统部署方式要先起数据库、再装服务端、配Java环境、调Elasticsearch参数，一套下来半天就没了，中途任何一个版本对不上都能让人抓狂。所以我这次用Docker来搭，并且把整个踩坑过程完整记录下来，从编排文件到初始化配置，从本地扫描到接入流水线，一次性讲透。

这篇文章适合谁？想快速在自己机器或服务器上把SonarQube跑起来的开发者、刚接手代码质量平台建设的测试或运维同学，以及准备在团队里推进代码扫描但还不太熟悉容器化方案的人。看完之后，你能照着操作把服务搭起来，并且知道为什么这么配，遇到问题也知道去哪排查。

1. 为什么用Docker跑SonarQube

1.1 传统部署的痛点

SonarQube本身是一个Java Web应用，底层还嵌了一个Elasticsearch节点用于索引和搜索。自己下载安装包部署的话，要处理的依赖非常多：先装JDK（不同版本要求的JDK版本还不一样，9.x要JDK11，10.x要JDK17），再装PostgreSQL，然后还要调整Elasticsearch的系统参数，比如vm.max_map_count、文件句柄数、线程数限制。如果你是第一次搞，光看官方文档里那页操作系统配置就能头大。

而且升级也麻烦。SonarQube小版本升级还好，大版本升级涉及数据库迁移、插件兼容性检查，稍不注意就可能迁移失败。我见过不少同事在本地环境直接装完，过了几个月系统提示版本过旧，要升级时一脸愁容。

1.2 容器化方案有哪些实际优势

用Docker之后，JDK、ES、SonarQube主程序全打进镜像里，应用运行时依赖就统一了，不再需要自己在宿主机折腾JDK版本。数据库用单独的PostgreSQL容器，数据量小的话直接挂volume就能持久化。

迁移和复制环境也方便。测试环境搭一套，把compose文件和volume目录拷到生产环境，启动参数一致，跑出来的行为基本一致，不会出现“在我机器上是好的”这种尴尬。

另外版本回滚容易。镜像tag一旦锁定，比如sonarqube:9.9.6-community，以后想退回去换tag就行，不用重新安装一个老版本安装包再迁移数据。

1.3 需要准备的硬件和基础环境

SonarQube官方建议最低2GB内存，但我实际用下来，如果同时扫描大项目，2GB跑得很吃力。建议4GB起步，2核CPU以上。数据库和SonarQube都在同一台机器上时，内存要预留更多。磁盘方面，挂载数据的目录建议留出10GB以上空闲空间，因为扫描结果、项目快照、插件包都会慢慢堆积。

宿主机系统我用的Debian/Ubuntu系列。需要提前安装Docker Engine和Docker Compose插件。安装完后可以用docker --version和docker compose version确认环境可用。

2. docker-compose.yml 这样写才对

2.1 镜像版本选择

选镜像版本前先想清楚需求。当前很多团队还在用9.9 LTS版本，这是社区版的一个长期支持版本，稳定且文档齐全，官方支持到2025年10月。如果你只是做基础代码扫描，这个版本足够了。新版本10.x功能更新多，但部分功能也把社区版和商业版划分得更清晰，有些高级能力Community版用不了，选的时候心里要有数。

我这次用的是sonarqube:9.9.6-community。数据库镜像选postgres:13。很多教程用postgres:12，但9.9本身支持PostgreSQL 13，13版本也维护得比较久，所以选13更稳。

2.2 compose 文件逐行拆解

下面是我实际使用的docker-compose.yml，每条配置后面我会讲为什么这么写。

services: sonarqube: image: sonarqube:9.9.6-community container_name: sonarqube depends_on: - db environment: SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar SONAR_JDBC_USERNAME: sonar SONAR_JDBC_PASSWORD: sonar_pass TZ: Asia/Shanghai volumes: - sonar_data:/opt/sonarqube/data - sonar_extensions:/opt/sonarqube/extensions - sonar_logs:/opt/sonarqube/logs ports: - "9000:9000" ulimits: nofile: soft: 65536 hard: 65536 restart: unless-stopped db: image: postgres:13 container_name: sonar_db environment: POSTGRES_USER: sonar POSTGRES_PASSWORD: sonar_pass POSTGRES_DB: sonar volumes: - db_data:/var/lib/postgresql/data restart: unless-stopped volumes: sonar_data: sonar_extensions: sonar_logs: db_data:

我解释几个关键点。

depends_on只是控制容器启动顺序，不保证数据库已经完全就绪。SonarQube启动时如果连不上数据库，会自动重试，所以写这个依赖就够了，不用额外搞healthcheck。当然，如果不想看到启动日志里一堆连库失败重试的记录，也可以给db加healthcheck，SonarQube那边用condition: service_healthy，但实际效果差别不大，重试几次也就连上了。

SONAR_JDBC_URL里的db是compose服务名，Docker内置DNS会把它解析到db容器的IP，所以这里不能写localhost。如果你在宿主机上访问数据库，那才是localhost，但容器之间必须走服务名。

TZ: Asia/Shanghai这个很多人不写。如果不设置，容器默认时区是UTC，扫描出来的问题和定时任务的时间看起来会比北京时间差8小时，排查问题时总感觉对不上。

ulimits里的nofile限制是关键中的关键。Elasticsearch要求文件句柄数至少65536，如果这个不设置，SonarQube里的ES节点启动时大概率报错，告诉你“max file descriptors is too low”。这个在宿主机上要改/etc/security/limits.conf，在Docker里直接写ulimits就可以了。

数据卷我分了三块：data、extensions、logs。data存的是运行数据，extensions存插件，logs存日志。很多人只挂data，结果插件一重启容器就被清空，中文包每次都要重装。分三个volume是经验之谈，升级和迁移的时候也方便。

2.3 启动前的系统参数调整

在拉镜像、启动之前，先做两个系统层面的调整。

Elasticsearch需要mmap计数大于等于262144，否则ES会拒绝启动。临时生效用：

sudo sysctl -w vm.max_map_count=262144

永久生效写入sysctl配置：

echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

这个配置在一些云服务器上默认值只有65530，不调的话SonarQube起来后ES会反复挂，表现就是容器在运行，但访问9000端口一直转圈或者连接被拒绝，看日志才定位到ES没起来。

再有就是swappiness，建议设置为10左右，避免系统频繁使用Swap导致ES性能下降。这个不是必须，但我在性能调优时会顺手改掉。

3. 首次启动和初始化配置

3.1 启动、日志排查、健康检查

先检查compose文件语法：

docker compose config

没有问题后启动：

docker compose up -d

启动后马上看日志：

docker compose logs -f sonarqube

日志里最典型的进度是这样的：开始是Spring Boot的启动信息，中间有一大段ES启动日志，然后出现“SonarQube is operational”字样，就说明服务已经可用了。第一次启动因为要初始化数据库和ES索引，大概需要2到5分钟，耐心等。

启动期间不要反复重启容器。我曾经因为看它半天没起来就docker compose restart，结果ES数据文件损坏，起来后还得手动清空重来。如果5分钟还没起来，优先看日志找原因，而不是无脑重启。

服务起来后，访问：

http://服务器IP:9000

如果访问不了，先确认宿主机防火墙有没有放行9000端口。云服务器的话还要检查安全组规则。这个问题我遇到不止一次，排查半天发现是安全组没加端口。

3.2 重置密码与安装中文包

首次访问页面会要求登录。默认账号是admin，默认密码也是admin，第一次登录后会强制要求修改密码。在这里建议直接换一个强密码，并且不要和别处复用。SonarQube里保存了项目的代码分析结果和令牌，如果被非授权人员登录，令牌泄露意味着能读取仓库里的代码信息。

接着干的第一件事是装中文包。虽然界面全英文也能用，但团队推广的时候，中文界面能降低不少抵触情绪。打开Administration -> Marketplace，搜索Chinese Pack，找到“SonarQube Chinese Pack”插件，点击Install。安装完成后，系统会提示需要重启，确认重启即可。实际装好的效果是界面全部变成中文，但扫描规则说明这些还是保留英文。

需要注意，部分网络环境从Marketplace下载插件会非常慢，甚至直接失败。如果反复失败，不用硬等，可以换一个思路：去插件官方仓库下载对应的jar包，放到/opt/sonarqube/extensions/plugins目录下或者对应volume目录里，然后重启容器。这里多说一句劝告：不要图方便下载来源不明的插件包，扩展名jar的文件一旦被恶意注入，影响的是整个平台。

3.3 创建项目并生成扫描令牌

中文界面切好之后，点首页右上角的“创建项目”。项目Key必须全局唯一，比如order-service这种；显示名称可以更友好一点。

项目创建好之后，系统会引导生成一个令牌。这个令牌是后续扫描器认证用的，形如squ_一串字母数字。令牌只显示一次，关掉页面就再也看不到了，所以一定要当场复制保存好。如果忘了也没关系，到账号信息里重新生成一个，旧令牌作废即可。

这里还涉及一个选择：项目可见性。如果是团队公共平台，默认Private就行，避免其他项目的扫描数据互相可见。如果只是个人测试，选Public也可以省去到处配置权限的麻烦。

4. 代码扫描实操：本地扫描与CI/CD集成

4.1 用 sonar-scanner 扫描本地代码

服务搭好之后，扫描代码靠的是客户端工具sonar-scanner。这和大多数人的认知有点出入，很多人以为SonarQube自带扫描能力，其实服务端只负责接收分析结果和展示，分析动作要由独立扫描器执行。

准备sonar-scanner：

wget https://binaries.sonarsource.com/Distribution/sonar-scanner-cli/sonar-scanner-cli-5.0.1.3006-linux.zip unzip sonar-scanner-cli-5.0.1.3006-linux.zip mv sonar-scanner-5.0.1.3006-linux /opt/sonar-scanner export PATH=$PATH:/opt/sonar-scanner/bin

在项目根目录创建一个sonar-project.properties文件：

sonar.projectKey=order-service sonar.projectName=order-service sonar.sourceEncoding=UTF-8 sonar.sources=src sonar.java.binaries=target/classes

如果你的项目是Java项目，sonar.java.binaries指向编译后的class目录，如果没有编译产物，扫描时关于类型推断和依赖分析的规则就会失效。如果项目是纯Python或JavaScript，不需要binaries，直接指定sources路径即可。

然后执行扫描：

cd /path/to/order-service sonar-scanner \ -Dsonar.host.url=http://localhost:9000 \ -Dsonar.token=squ_你的令牌

扫描过程会看到很多输出，最后一行通常有EXECUTION SUCCESS或EXECUTION FAILURE。成功之后，回到SonarQube界面刷新项目页面，就能看到分析报告了。

4.2 质量门禁与质量规则配置

分析报告里会按Bug、漏洞、坏味道、覆盖率、重复率这几个维度展示。默认的质量门禁叫“Sonar way”，它定义的规则是“不新增Bug、不新增漏洞、不新增坏味道”就算通过。实际团队推行时，这个门槛往往不够用。

比如可以新增“覆盖率不低于80%”或“重复代码少于3%”这类条件。进入Quality Gates配置页，复制内置的“Sonar way”创建一个自定义门禁，再添加条件。这里的数值别一次定得过高，我见过团队上来就要求100%覆盖率，结果所有人都开始写无意义的测试，数字是漂亮了，代码质量并没有实质提升。建议先用默认门禁跑两个星期，看看基线情况，再逐步收紧。

质量规则（Quality Profiles）也可以按语言调整。默认的Java规则集对老项目来说会比较严格，扫出来的坏味道可能成百上千。团队刚接入时，建议先以“不新增问题”为目标，存量问题统计出来由负责人分批消解，而不是要求一次性清零。

4.3 在GitLab CI中集成SonarQube

代码扫描从本地手工执行走向流水线自动执行，才能真正坚持下来。下面是一个简化的GitLab CI配置片段，加入项目的.gitlab-ci.yml即可。

sonarqube-check: stage: test image: name: sonarsource/sonar-scanner-cli:latest entrypoint: [""] variables: SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar" GIT_DEPTH: "0" cache: key: "${CI_JOB_NAME}" paths: - .sonar/cache script: - sonar-scanner -Dsonar.host.url=$SONAR_HOST_URL -Dsonar.token=$SONAR_TOKEN allow_failure: true only: - merge_requests - main

在GitLab项目设置里的CI/CD Variables中配置SONAR_HOST_URL和SONAR_TOKEN两个变量。allow_failure: true是建议，这样即使质量门禁挂了，也不会阻断流水线。真正要阻断，可以把这行去掉，让不够质量标准的合并请求直接失败。但上线这种严格模式前，要先确保团队所有成员对质量门禁规则达成一致，否则很容易变成“每周开会扯皮”。

这里补充一点：Community版SonarQube的GitLab集成比较基础，只能做到整体分析状态同步。想在合并请求里显示每一行的Inline Comment，那是Developer版及以上的功能。选型时要有预期，别等接完了发现差别再叹气。

4.4 多语言项目支持

SonarQube社区版对Java、JavaScript/TypeScript、Python、PHP、HTML、CSS这些常见语言原生支持较好。但遇到Go、C/C++这类语言，社区版默认并不包含对应的分析插件，这部分是商业插件覆盖的。

如果你的团队项目恰好是这些语言，可以先让服务端正常跑起来，再用官方文档确认具体哪些分析器对你开放。很多时候，尽早确认语言支持范围，比辛辛苦苦部署完才发现核心项目扫不了，要省心得多。

关于处理多模块Java项目，扫描时建议配置sonar.modules或者分别对每个模块单独扫描，不要直接在父工程下指定sources，否则SonarQube会把每个模块都当成独立项目来看待，报告数据会很乱。

5. 常见问题排查与性能调优

5.1 高频故障速查表

我把自己和身边同事遇到过的高频问题整理成了表格，排查的时候可以直接对着看。

每一条我都实际踩过。最坑的是vm.max_map_count，它报错时不是直接告诉你“需要调整”，而是大段ES日志中间夹着一行“Max virtual memory areas vm.max_map_count is too low”，不仔细看日志很容易忽略。

5.2 内存配置与性能优化

SonarQube容器内存分配主要影响的是内嵌ES和Web服务。如果机器内存只有4GB，建议给SonarQube容器适当限制内存，防止占用过多影响数据库容器。可以在compose文件里加mem_limit: 3g。

ES的堆内存默认是按容器内存比例自动分配的。如果容器内存设了3g，ES默认Heap大概700MB左右，扫描大项目时不够用。可以在启动参数里增加SONAR_SEARCH_JAVAOPTS来做精细控制，比如：

environment: SONAR_SEARCH_JAVAOPTS: "-Xms1g -Xmx1g"

这里提醒一句：-Xmx不要超过物理内存的一半，也不要超过ES自身要求的限制，因为ES还要留一部分内存给堆外和系统缓存。如果宿主机只有4GB内存，把Xmx设到2g，系统大概率会觉得内存吃紧，结果就是容器被OOM杀掉。

日常维护方面，建议给SonarQube容器加上健康检查。写一个简单的test指令定期探测9000端口，并在compose里配置restart: unless-stopped，这样进程异常退出后能自动拉起。

5.3 备份、升级与日常维护

数据备份最核心的是PostgreSQL数据库。SonarQube的分析数据、权限数据、项目配置都在数据库里，extensions目录只是插件，data目录里是Elasticsearch索引和缓存，丢了大不了重建。所以备份重点备份数据库。

手动备份命令：

docker exec sonar_db pg_dump -U sonar -d sonar > sonar_backup.sql

定时备份可以写一个cron任务，每天凌晨执行一次，保留最近7天即可。恢复的时候，将备份文件导入一个新的PostgreSQL容器，再把SonarQube容器指到新库就行。

升级SonarQube版本时，我的建议顺序是：备份数据库，记下当前版本号，只跨一个中版本升级，不要从9.x一步跳到10.x。升级后先访问页面确认数据都在，再去看扫描报告是否正常。插件兼容性也得留意，大版本升级会让部分旧插件失效，Marketplace里的更新提示要看仔细。

另外，SonarQube的administrators账号可以定期检查系统信息页面，里面能看到各节点内存状态、磁盘使用率、ES健康状态，这个页面是我每次上服务器必查的地方。

最后再分享一个经验。第一次搭这玩意儿的时候，我在单台2GB的机器上硬启动，等了10分钟都没起来，后来看日志才发现ES一直因为内存不够被杀。换了4GB的机器后一次起来。玩SonarQube，本质上是玩内存和系统参数，把这两样伺候好，它就是个稳定的代码质量看板；伺候不好，它分分钟让你怀疑人生。如果你刚开始搭，建议从最小可用配置起步，扫描一个小项目验证全链路，再慢慢加规则、接流水线，一步一个脚印地落地。这样踩坑的时候，定位起来要快得多。