CentOS 上从零安装 SonarQube 9.9 LTS：环境配置与实操指南

SonarQube 9.9 LTS 这套东西我在 CentOS 上前后折腾过好几回从 7.x 一直用到 9.9踩过的坑攒了不少。这次专门把 9.9 LTS 的完整安装过程重新整理一遍从环境准备、JDK 选择、PostgreSQL 配置到内核参数调整、Systemd 托管、Nginx 反代一条龙走完。文章适合刚接触代码质量平台的运维、后端开发也适合准备在团队内部搭建统一扫描服务的技术负责人。整个流程照着做半小时内能把一个能用的 SonarQube 跑起来。1. 版本选型与安装前的关键决策1.1 为什么选 9.9 LTS 而不是最新版SonarQube 的版本策略很容易让人看花眼社区版、开发者版、企业版还有一堆带 DCEDataCenter Edition字样的版本。但真正适合在生产环境长期跑的还是 LTS 版本。9.9 LTS 是 SonarSource 官方推出的一个长期支持版本官方承诺的维护周期覆盖到 9.9 发布后的较长时间段bug 修复和安全补丁都会持续跟进。对比一下最新版和 LTS 版本的区别最新版往往第一时间带了新功能比如新的分析规则、新的语言支持但升级节奏偏快大版本之间迁移可能会遇到 API 变动或者插件不兼容。而 9.9 LTS 的优势在于稳定插件兼容性经过验证社区讨论多出问题容易搜到解决方案。对于企业场景代码质量平台属于基础设施稳定压倒一切。所以我个人建议除非你有必须用新功能的需求否则直接选 9.9 LTS 准没错。1.2 9.9 LTS 对运行环境的硬性要求安装之前先把官方文档里的环境要求看清楚这一步能帮你少走一半弯路。Java 版本SonarQube 9.9 LTS 要求 JDK 17不能再用 Java 8 或 Java 11 了。这里说的 JDK 17是指运行 SonarQube 服务本身的 JVM 版本。数据库支持 PostgreSQL、Oracle、SQL Server但社区版最常用的是 PostgreSQL。9.9 LTS 对应支持的 PostgreSQL 版本有明确要求建议安装 PostgreSQL 13 或更高版本实测下来 13/14/15 都能正常用。操作系统CentOS 7、CentOS 8、Ubuntu 等主流 Linux 发行版都行。我本次演示用的是 CentOS 7.9这也是国内服务器存量比较大的版本。资源要求官方建议至少 2GB 内存实际跑起来刚启动时 JVM 加 Elasticsearch 进程很容易吃满 4GB所以生产环境建议内存不低于 4GB。磁盘上SonarQube 本体加 Elasticsearch 索引起步预留 10GB 比较稳妥。注意如果你的服务器内存只有 1GB跑 SonarQube 会非常吃力启动过程频繁 OutOfMemory建议直接加内存或者换一台配置高点的机器。1.3 整体架构与组件分工SonarQube 不是一个单进程应用它内部集成了多个组件理解这些组件对后续排查问题非常有帮助。核心组成包括Web 服务组件负责对外提供 Web 界面和 REST API默认监听 9000 端口。Elasticsearch 存储组件负责索引代码分析结果实现快速搜索。它在 SonarQube 内部作为独立服务运行对系统内核参数和文件句柄数敏感。计算引擎组件负责执行分析任务处理上传的扫描报告。初次接触的人容易忽略 Elasticsearch 的存在但很多安装失败的问题恰恰出在它身上。比如启动时提示max virtual memory areas vm.max_map_count [65530] is too low这就是因为 Elasticsearch 需要的 mmap 内存映射区域数量不满足要求。所以后面我们会专门调整内核参数。整个安装流程可以看作三步先把地基打好JDK、数据库、内核参数再装主程序SonarQube 本体最后做外部接入Nginx 反代、首次初始化。2. 系统环境准备与基础依赖安装2.1 CentOS 系统基础检查拿到一台新的 CentOS 服务器先别急着装东西盘点一下系统状态。我的习惯是依次检查这几项# 查看系统版本 cat /etc/redhat-release # 查看内存和磁盘 free -h df -h # 查看 CPU 核心数 nprocCentOS 7.9 是目前最常用的版本但如果你用的是 CentOS 8 或者 Stream 版本操作步骤基本一致只是软件源配置上可能有点差异。另外要注意CentOS 7 官方源已经停止维护了yum 安装时建议先换成可用的镜像源比如阿里云源或者清华源再把基础软件包装好。2.2 安装基础工具与系统更新系统更新这步看似简单但很关键。刚装好的系统可能存在各种安全漏洞先把内核和基础软件包升级到最新再开始部署应用环境。不过这里有个坑如果服务器上有正在运行的重要业务yum update 可能会导致内核升级后需要重启重启时间窗口要提前规划好。# 更换镜像源以阿里云为例 mv /etc/yum.repos.d/CentOS-Base.repo /etc/yum.repos.d/CentOS-Base.repo.backup curl -o /etc/yum.repos.d/CentOS-Base.repo http://mirrors.aliyun.com/repo/Centos-7.repo # 刷新缓存并更新系统 yum clean all yum makecache yum update -y更新完系统后把常用工具装上。这些工具在后续操作中会用到缺了会很不方便。yum install -y vim wget curl net-tools unzip zip lsof2.3 关闭防火墙或放行端口实操建议很多人在安装过程中发现服务起不来结果一看是防火墙把端口挡了。CentOS 7 默认防火墙是 firewalld如果你是在内网环境部署图省事可以直接关掉如果服务器有公网 IP还是建议按需放行端口安全第一。# 查看防火墙状态 systemctl status firewalld # 方式一直接关闭防火墙内网测试环境推荐 systemctl stop firewalld systemctl disable firewalld # 方式二放行 SonarQube 端口生产环境推荐 firewall-cmd --permanent --add-port9000/tcp firewall-cmd --reload还有 SELinux这个也是老生常谈的问题。SELinux 如果是 enforcing 模式可能会导致 SonarQube 读写文件权限异常。建议先把它调整为 permissive 模式排查完问题再考虑增强安全性。修改方式编辑/etc/selinux/config把SELINUXenforcing改为SELINUXpermissive然后重启系统生效。3. JDK 17 安装与内核参数调整3.1 安装 OpenJDK 17SonarQube 9.9 LTS 跑在 JDK 17 上这是硬性要求。CentOS 7 自带的 yum 源通常没有 JDK 17所以我们要从官网下载或者使用其他方式安装。我推荐安装 OpenJDK 17开源免费兼容性足够。# 查看系统中是否已有 Java java -version # 如果存在旧版本先卸载谨慎操作 yum remove -y java-1.8.0-openjdk* # 下载 OpenJDK 17以 Linux x64 版本为例 wget https://download.java.net/java/GA/jdk17.0.2/dfd4a8d0985749f896bed50d7138ee7f/8/GPL/openjdk-17.0.2_linux-x64_bin.tar.gz # 解压到指定目录 mkdir -p /usr/local/java tar -zxvf openjdk-17.0.2_linux-x64_bin.tar.gz -C /usr/local/java/ # 配置环境变量 cat /etc/profile EOF export JAVA_HOME/usr/local/java/jdk-17.0.2 export PATH$JAVA_HOME/bin:$PATH export CLASSPATH.:$JAVA_HOME/lib/dt.jar:$JAVA_HOME/lib/tools.jar EOF # 使环境变量生效 source /etc/profile # 验证安装 java -version执行java -version后如果看到openjdk version 17.0.2这样的输出说明 JDK 装好了。这一步是整个安装过程中最容易出错的环节之一很多人的 SonarQube 启动失败最后发现是 JDK 版本不对或者JAVA_HOME环境变量没配对。注意千万别只装一个 JRE 就想跑 SonarQube它需要完整的 JDK。另外JDK 版本不能高于 17 太多虽然高版本一般向下兼容但官方只对 JDK 17 做过完整验证。3.2 内核参数调整vm.max_map_count 与文件句柄数SonarQube 内置的 Elasticsearch 对系统参数有两个硬性要求不调整的话服务启动时直接报错。第一个是vm.max_map_count这个参数控制进程可以拥有的内存映射区域数量。Elasticsearch 默认需要 262144 以上而 CentOS 默认值是 65530差得很远。# 临时生效 sysctl -w vm.max_map_count262144 # 永久生效 echo vm.max_map_count262144 /etc/sysctl.conf sysctl -p第二个是文件句柄数限制。Elasticsearch 运行时会打开大量文件默认的 1024 限制不够用。需要修改/etc/security/limits.conf给专门运行 SonarQube 的用户提高限制。这里先把用户规划好后续会创建一个名为sonarqube的系统用户。提前把 limits 配置写进去省的后面再改。cat /etc/security/limits.conf EOF sonarqube - nofile 65536 sonarqube - nproc 4096 EOF还要修改/etc/sysctl.conf追加一个参数echo fs.file-max65536 /etc/sysctl.conf sysctl -p这两个参数调整完后最好重启一次系统确保所有配置都加载到内核中。如果不方便重启至少要让sysctl -p生效并在新终端中确认ulimit -n的值已经变化。4. PostgreSQL 数据库安装与初始化4.1 安装 PostgreSQL 13SonarQube 9.9 LTS 官方支持 PostgreSQL 12 到 15推荐使用 PostgreSQL 13 或 14。CentOS 7 自带的 PostgreSQL 版本比较老我们需要通过官方源安装较新的版本。# 安装 PostgreSQL 官方源 yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm # 安装 PostgreSQL 13 yum install -y postgresql13-server postgresql13-contrib # 初始化数据库 /usr/pgsql-13/bin/postgresql-13-setup initdb初始化这一步很重要它会在/var/lib/pgsql/13/data下生成数据库的数据文件。如果提示找不到postgresql-13-setup脚本检查一下安装路径不同版本可能略有差异。4.2 启动 PostgreSQL 并创建专用账号安装完成后启动 PostgreSQL 服务并设置为开机自启。systemctl start postgresql-13 systemctl enable postgresql-13 systemctl status postgresql-13PostgreSQL 默认会创建一个名为postgres的超级用户。接下来我们要创建一个名为sonarqube的数据库用户并创建一个名为sonarqube的数据库。这里有几个关键点要特别注意数据库编码必须是 UTF8SonarQube 对字符集敏感账号权限要最小化避免使用 postgres 超级用户直接运行。# 切换到 postgres 系统用户 su - postgres # 进入 psql 命令行 psql # 创建 sonarqube 用户密码自行替换 CREATE USER sonarqube WITH PASSWORD sonarqube_passwd; # 创建数据库并指定编码 CREATE DATABASE sonarqube OWNER sonarqube ENCODING UTF8 TEMPLATE template0; # 授权 GRANT ALL PRIVILEGES ON DATABASE sonarqube TO sonarqube; # 退出 \q exit4.3 修改 PostgreSQL 访问配置默认情况下PostgreSQL 只允许本机通过 Unix Socket 连接SonarQube 通过 JDBC 连接数据库时走的是 TCP 协议。因此需要修改pg_hba.conf文件允许本地 TCP 连接。编辑/var/lib/pgsql/13/data/pg_hba.conf找到类似下面这行host all all 127.0.0.1/32 ident把ident改成md5或者直接加上一行放行本地网络段host all all 127.0.0.1/32 md5修改完重启 PostgreSQLsystemctl restart postgresql-134.4 验证数据库连接在安装 SonarQube 之前先确认数据库能正常用 JDBC 方式连接。装一下 PostgreSQL 的客户端工具然后测试连接yum install -y postgresql13 # 测试 TCP 连接 PGPASSWORDsonarqube_passwd psql -h 127.0.0.1 -U sonarqube -d sonarqube -c SELECT version();能够正常输出 PostgreSQL 版本号说明数据库部分准备完毕。这里我用的是密码字符串生产环境建议把密码设置得复杂一点或者用配置管理工具统一管理。5. SonarQube 主程序安装与配置5.1 创建运行用户和目录结构一个原则不要用 root 用户直接跑 SonarQube。一方面是不安全另一方面 Elasticsearch 也明确拒绝以 root 身份运行。所以先创建一个专用用户。# 创建系统用户 useradd -d /opt/sonarqube -s /bin/bash sonarqube # 创建数据目录 mkdir -p /opt/sonarqube chown -R sonarqube:sonarqube /opt/sonarqube5.2 下载并解压 SonarQube 9.9 LTS去 SonarQube 官方下载页面找到 9.9 LTS 社区版的下载地址。在企业内网环境可以先下载到本地再上传到服务器如果服务器能访问外网直接用 wget 下载更快。cd /opt/sonarqube # 从官方仓库下载 wget https://binaries.sonarsource.com/Distribution/sonarqube/sonarqube-9.9.8.100196.zip # 解压 unzip sonarqube-9.9.8.100196.zip # 重命名目录便于管理 mv sonarqube-9.9.8.100196 sonarqube-9.9 # 创建数据目录并确保属主正确 mkdir -p sonarqube-9.9/data mkdir -p sonarqube-9.9/logs chown -R sonarqube:sonarqube /opt/sonarqube注意SonarQube 的安装目录结构里data和logs目录在首次启动时可能不存在提前创建可以避免权限问题。5.3 sonar.properties 核心配置项SonarQube 的配置文件位于conf/sonar.properties。打开这个文件按需修改几个关键项。先配置数据库连接信息。找到这些参数把注释去掉并修改# 数据库连接地址 sonar.jdbc.usernamesonarqube sonar.jdbc.passwordsonarqube_passwd sonar.jdbc.urljdbc:postgresql://127.0.0.1:5432/sonarqube接下来配置 Web 服务端口和监听地址。默认是 9000 端口如果端口被占用可以改成别的但后面 Nginx 反向代理也要对应修改。# Web 服务监听地址这里设置为本机所有 IP sonar.web.host0.0.0.0 # Web 服务端口 sonar.web.port9000还要配置一下 JVM 参数。默认的最小堆和最大堆大小是 1GB 和 1GB如果服务器内存比较充足可以调高一点提升性能。# 修改 conf/wrapper.conf 或者用环境变量 SONAR_JAVA_OPTS-Xms1g -Xmx1g不过 SonarQube 9.9 的 JVM 参数配置方式有些变化可以直接修改conf/wrapper.conf文件搜索wrapper.java.additional相关行然后加上内存参数。5.4 修改 Elasticsearch 配置可选SonarQube 内置的 Elasticsearch 配置文件在conf/elasticsearch.yml。大多数情况下不需要改动但如果你遇到 Elasticsearch 启动失败可以检查以下几个参数# 数据存储路径默认在安装目录下 path.data: /opt/sonarqube/sonarqube-9.9/data # 日志路径 path.logs: /opt/sonarqube/sonarqube-9.9/logs另外Elasticsearch 默认分配 JVM 堆大小是 512MB。如果一个节点上同时跑着 SonarQube 的多个实例可能需要调整。这个文件不用频繁动保持默认即可。6. 首次启动、Systemd 托管与 Nginx 接入6.1 手动启动并观察日志配置完成后先用 sonarqube 用户手动启动一次观察启动日志。这是排查问题最快的方式。# 切换到 sonarqube 用户 su - sonarqube # 进入安装目录 cd /opt/sonarqube/sonarqube-9.9/bin/linux-x86-64/ # 启动 ./sonar.sh start启动过程中会输出 PIDs表示进程已经拉起。然后查看日志# 切换回 root 或者用 root 权限查看 tail -f /opt/sonarqube/sonarqube-9.9/logs/sonar.log首次启动需要做一些初始化工作比如创建数据库表结构、生成索引这个过程可能需要 1-2 分钟。看到类似下面的日志说明启动成功SonarQube is up如果日志中出现ERROR或者FATAL把错误信息记录下来对照后面的常见问题章节排查。6.2 配置 Systemd 服务实现开机自启手动启动虽然能跑但服务器重启后服务不会自动拉起生产环境必须用 Systemd 管理。创建/etc/systemd/system/sonarqube.service文件[Unit] DescriptionSonarQube service Aftersyslog.target network.target postgresql-13.service [Service] Typeforking Usersonarqube Groupsonarqube ExecStart/opt/sonarqube/sonarqube-9.9/bin/linux-x86-64/sonar.sh start ExecStop/opt/sonarqube/sonarqube-9.9/bin/linux-x86-64/sonar.sh stop ExecReload/opt/sonarqube/sonarqube-9.9/bin/linux-x86-64/sonar.sh restart PIDFile/opt/sonarqube/sonarqube-9.9/bin/linux-x86-64/sonar.pid Restarton-failure RestartSec10 [Install] WantedBymulti-user.target注意After里面加上了postgresql-13.service确保 SonarQube 在数据库启动之后再启动。然后重新加载 Systemd 配置并启动服务systemctl daemon-reload systemctl start sonarqube systemctl enable sonarqube systemctl status sonarqube用 Systemd 管理后日常操作就统一了systemctl stop sonarqube停止systemctl restart sonarqube重启。6.3 Nginx 反向代理配置SonarQube 默认通过 9000 端口访问。如果服务器有公网 IP直接暴露 9000 端口存在安全风险而且不方便统一管理所以通常会在前面加一层 Nginx 反向代理用 80 或 443 端口对外提供服务。安装 Nginxyum install -y nginx创建配置文件/etc/nginx/conf.d/sonarqube.confserver { listen 80; server_name sonarqube.example.com; # 允许上传的分析报告大小 client_max_body_size 50M; location / { proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_pass http://127.0.0.1:9000; } }启动 Nginx 并设置开机自启systemctl start nginx systemctl enable nginx systemctl status nginx配置完成后访问http://sonarqube.example.com应该就能看到 SonarQube 的 Web 界面。如果用的是 IP 访问把 server_name 改成对应 IP 就行。6.4 首次登录和初始管理员账号SonarQube 首次启动后系统会自动生成一个管理员账号。这个账号不是我们自己创建的而是内置的默认用户名和密码是用户名admin密码admin首次登录后系统会强制要求修改密码。这里强烈建议改成强密码并妥善保管因为 SonarQube 的 Web 界面里有很多管理功能一旦被恶意利用后果很严重。登录成功后可以创建项目、配置质量规则也可以安装汉化插件。插件安装路径Administration → Marketplace搜索 Chinese Pack安装后重启服务即可切换为中文界面。不过要注意新版 Marketplace 里搜索不到汉化包的情况偶尔会出现这通常和网络有关。7. 实际安装中的高频问题与排查思路7.1 Elasticsearch 启动失败SonarQube 启动时报错最常遇到的场景就是 Elasticsearch 起不来。典型错误如下ERROR: [1] bootstrap checks failed [1]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]解决办法前面已经提过就是调大vm.max_map_count。还有一些情况是max file descriptors [4096] for elasticsearch process is too low这个就是 limits.conf 没配置好重新检查 sonarqube 用户的 nofile 限制。7.2 端口被占用启动时提示端口 9000 被占用或者 Web 页面一直打不开。排查方法lsof -i:9000 netstat -tlnp | grep 9000如果是端口被其他进程占用要么杀掉那个进程要么修改sonar.properties里的端口配置。改完端口后记得同步修改 Nginx 的proxy_pass地址和 Systemd 服务配置中的相关端口。7.3 数据库连接失败启动日志里出现类似Connection to 127.0.0.1:5432 refused的报错大概率是 PostgreSQL 没启动或者 pg_hba.conf 配置不对。先确认数据库服务状态systemctl status postgresql-13如果数据库已经启动再检查 pg_hba.conf 里的认证方式确认是 md5 而不是 ident。最后用第 4 节的连接测试命令验证 JDBC 连接是否通畅。7.4 权限不足导致启动失败如果用 root 用户直接启动 SonarQube会看到提示can not run elasticsearch as root。遇到这种情况必须先创建 sonarqube 用户然后切换到该用户启动。同时要注意安装目录的所有权确保sonarqube用户对/opt/sonarqube有完全控制权。chown -R sonarqube:sonarqube /opt/sonarqube7.5 常见问题速查表现象原因解决办法启动日志报 vm.max_map_count 不足内核参数未调整执行sysctl -w vm.max_map_count262144并写入 /etc/sysctl.conf启动日志报 max file descriptors 不足limits.conf 未配置在 /etc/security/limits.conf 中增加 sonarqube 用户 nofile 限制Web 页面无法访问防火墙拦截或 Nginx 未启动放行 9000 端口或启动 Nginx 并检查 proxy_pass 配置数据库连接 refusedPostgreSQL 未启动启动 postgresql-13 服务并设置开机自启页面提示数据库字符集错误数据库编码不是 UTF8删除数据库用ENCODING UTF8 TEMPLATE template0重建扫描时报错 no space left磁盘空间不足清理磁盘或扩容同时检查 data 目录占用8. 一些实操中的经验与补充建议这次安装过程中我踩得最深的坑是vm.max_map_count。第一次装的时候根本没注意这个参数结果 SonarQube 的 Web 进程起来了Elasticsearch 却一直没起来日志里全是bootstrap checks failed。后来才发现是内核参数的问题配置好之后启动就顺了。所以提前把内核参数、limits 配置这些前置条件一次性搞定能省大把排查时间。还有一个小技巧SonarQube 启动后要判断它是否真正可用别只看 9000 端口有没有监听要等日志里出现SonarQube is up。因为 Web 进程端口起得很早但 Elasticsearch 索引还需要时间初始化初始化完成前访问页面会报 503 或者一直转圈。日常使用中建议把 SonarQube 的日志文件接入到统一的日志收集系统比如 logstash 或者 filebeat这样出现问题可以第一时间收到告警不用天天去服务器上翻日志。另外守护进程配置了Restarton-failure之后也要注意监控服务是否进入不断重启的异常循环配合RestartSec参数控制重启间隔。代码扫描这块等 SonarQube 本身稳定了建议尽快配置好质量门禁Quality Gate把扫描结果和 CI 流程串起来。团队协作时提交代码后自动触发扫描不合格直接中断构建质量红线才能落实到位。这个后续有机会再单独写一篇实战教程先把安装这关过了后面的路就好走了。