SonarQube的安装与配置核心在于选择正确的版本、配置JDK与数据库，并通过Docker或传统包管理器完成部署，然后进行中文显示和代码质量门禁设置。
为什么你需要搞懂SonarQube安装配置
很多团队在代码质量管控上栽跟头，不是工具不行，而是卡在安装环节，业内专家指出，超过七成的SonarQube部署失败源于环境兼容性问题，作为一个长期用的代码扫描平台，SonarQube本身不复杂，但它的安装链路长：JDK版本、数据库选型、系统参数、插件体系,每一步都互相牵连。
我见过不少开发同学直接拿apt安装，结果启动报错找不到类，然后折腾一下午，其实只要理清依赖关系，半小时就能跑起来，下面这套配置方式,覆盖了从零到能扫描项目的完整路径。
先回答最关键的三个选择难题
在动手前，你需要做三个决定,这三个坑踩了基本就要重来。
- 版本选社区版还是开发者版？ 社区版免费，支持Java、C#、JavaScript等主流语言，但对Python、Go等语言的深度规则有限，如果你只是做基础检查，社区版够用，想用分支分析和更多语言规则，得花钱升级，这个价格不便宜,小团队不建议。
- 数据库用内置的还是外接的？ SonarQube 7.9以后，默认内置H2数据库，但只适合测试，生产环境必须接PostgreSQL或MySQL，行业共识认为，PostgreSQL 13以上版本是当前最稳妥的搭配。
- 用Docker还是传统安装？ 如果你管理过Linux服务器，Docker是省事首选；但很多企业内网环境不允许用容器，那就得走压缩包部署,下面两条路我都会讲。
环境准备：JDK和系统参数的坑
SonarQube从9.x开始，强制要求JDK 17，这里说的JDK不是JRE，而且需要的是OpenJDK或Oracle JDK，不能用自带的最新的JDK 21/23碰运气,很多老插件不兼容。
检查你的Java环境
登录Linux服务器后,第一件事就是确认版本：
java -version
如果输出是Java 8或11，先升级到17,以Ubuntu为例：
sudo apt install openjdk-17-jdk
装完记得修改默认版本：
sudo update-alternatives --config java
系统文件句柄和虚拟内存限制
这一步特别关键，但经常被忽略，SonarQube启动时会检查vm.max_map_count和文件句柄数，不设的话,Elasticsearch组件起不来。
临时生效直接执行：
sysctl -w vm.max_map_count=262144
永久生效需要编辑/etc/sysctl.conf,加入一行：
vm.max_map_count=262144然后刷新：
sysctl -p
同时把/etc/security/limits.conf
里加上：
sonar - nofile 65536
sonar - nproc 4096注意，这里sonar是稍后要创建的专用用户，千万别用root跑SonarQube,它明确拒绝root启动。
传统方式安装配置SonarQube：一步步来
这个方法适合内网环境,不依赖外部镜像。
下载并解压发行包
到SonarQube官方下载页（sonarsource.com）找到社区版压缩包，现在最新稳定版本是10.x系列，但9是LTS版本，维护时间长,企业内更常见。
wget https://binaries.sonarsource.com/Distribution/sonarqube/sonarqube-9.9.8.100196.zip unzip sonarqube-9.9.8.100196.zip -d /opt mv /opt/sonarqube-9.9.8.100196 /opt/sonarqube
然后创建专用用户：
useradd sonar chown -R sonar:sonar /opt/sonarqube
配置数据库连接
以PostgreSQL为例,先建库建用户：
CREATE DATABASE sonar; CREATE USER sonar WITH ENCRYPTED PASSWORD 'sonarpass'; GRANT ALL PRIVILEGES ON DATABASE sonar TO sonar;
然后修改SonarQube的配置：
vim /opt/sonarqube/conf/sonar.properties
找到这几行,去掉注释并改值：
sonar.jdbc.username=sonar
sonar.jdbc.password=sonarpass
sonar.jdbc.url=jdbc:postgresql://localhost/sonar记得把内置的H2配置注释掉,不然它会优先用H2。
启动和访问
用sonar用户启动：
su - sonar -c "/opt/sonarqube/bin/linux-x86-64/sonar.sh start"
查看日志确认无报错：
tail -f /opt/sonarqube/logs/sonar.log
看到SonarQube is operational就说明成了，浏览器输入http://服务器IP:9000，默认管理账号是admin/admin,第一次登录会让你改密码。
用Docker安装配置SonarQube：更省心的选择
如果你服务器上有Docker环境，我推荐用官方镜像,省去JDK和数据库的麻烦。
用docker-compose一键编排
创建docker-compose.yml文件：
version: '3'
services:
postgres:
image: postgres:13
container_name: sonar-postgres
environment:
- POSTGRES_USER=sonar
- POSTGRES_PASSWORD=sonarpass
- POSTGRES_DB=sonar
volumes:
- postgres_data:/var/lib/postgresql/data
restart: always
sonarqube:
image: sonarqube:9.9-community
container_name: sonarqube
depends_on:
- postgres
ports:
- "9000:9000"
environment:
- SONAR_JDBC_URL=jdbc:postgresql://postgres:5432/sonar
- SONAR_JDBC_USERNAME=sonar
- SONAR_JDBC_PASSWORD=sonarpass
volumes:
- sonar_data:/opt/sonarqube/data
restart: always
volumes:
postgres_data:
sonar_data:
然后一条命令搞定：
docker-compose up -d
这种方式的好处是，不用管系统参数，因为镜像里已经做了优化，但要注意，如果宿主机的/etc/sysctl.conf里vm.max_map_count小于262144，Docker容器里的Elasticsearch照样起不来,所以这条命令还是得执行。
Docker方式的常用维护命令
查看启动日志：
docker logs -f sonarqube
停止和重启：
docker-compose stop docker-compose start
升级版本时，先备份sonar_data卷，然后改镜像版本号，再docker-compose up -d即可。
配置中文界面与插件：让团队更容易上手
老外做的工具，默认英文界面，很多测试和产品同学看着费劲，SonarQube官方有中文语言包,通过Administration里的Marketplace就能装。
在线安装中文包
登录后，点击顶部导航的Administration，选择Marketplace，在搜索框输入Chinese，找到Chinese Pack，点击Install按钮,装完会提示重启服务。
重启后界面就变成中文了，这个操作也让代码扫描结果里的规则描述显示中文,对非程序员团队特别实用。
离线安装的场景
内网环境装不了插件怎么办？去官方插件库下载对应的jar包，放到/opt/sonarqube/extensions/plugins/目录，然后重启。注意版本必须和SonarQube主版本匹配，9.9版本不能用10.x的插件,否则直接加载失败。
配置代码扫描和规则集：让安装成果落地
装完只是第一步，没人愿意用配置复杂的工具,下面我把扫描流程简化到最小。
创建项目和生成令牌
在SonarQube界面右上角点“+”，创建新项目，项目Key建议用团队名_项目名的格式，比如devops_ordercenter，创建后会让你选择分析方式，选“Local”或“命令行”都行。
接着生成一个令牌（Token），这个令牌相当于你的访问凭证，只在生成时显示一次,要记下来。
在Maven项目里直接扫描
如果你用Maven管理Java代码，在pom.xml的build节点里加入：
<plugin>
<groupId>org.sonarsource.scanner.maven</groupId>
<artifactId>sonar-maven-plugin</artifactId>
<version>3.9.1.2184</version>
</plugin>
然后执行：
mvn sonar:sonar -Dsonar.host.url=http://localhost:9000 -Dsonar.login=你的令牌
扫描结束后，刷新SonarQube界面，就能看到项目的代码异味、Bug数和坏味道分布图。
设置质量门禁
最后做个质量门禁，防止带着问题代码合并，在“质量门禁”设置里，把新增代码覆盖率低于50%和新增代码严重问题数大于0设为红色预警条件，这样CI/CD流水线里可以调用API判断构建是继续还是中断。
调用接口示例：
curl -u 你的令牌: http://sonar地址/api/qualitygates/project_status?projectKey=项目Key
返回"status": "ERROR"时，构建脚本里让它exit 1即可。
SonarQube安装配置常见错误排查
这里列几个我踩过和大家问得最多的坑。
启动报错Caused by: java.lang.IllegalStateException: max virtual memory areas vm.max_map_count [65530] is too low
这就是没调整系统参数，按上文执行sysctl -w vm.max_map_count=262144，并写入/etc/sysctl.conf。
访问9000端口超时
先看防火墙：
sudo ufw allow 9000/tcp
如果跑了nginx做反向代理，记得配置client_max_body_size,不然上传插件时报413。
扫描时连接不上SonarQube
确认SonarQube所在机器的端口没有被安全组拦截,并在扫描端检查连通性：
telnet 服务器IP 9000
如果用的是自签名HTTPS，需要在扫描命令里加-Dsonar.scanner.truststorePassword等参数，但内网环境建议直接走HTTP,别自找麻烦。
SonarQube的安装配置，如果把JDK版本、数据库选型和系统内核参数这三关都过了，后面就是一马平川，Docker方式适合快速验证，传统方式更贴近生产环境的合规要求，装完后优先设置中文包和简单的质量门禁，让团队每天看到扫描结果,慢慢形成习惯。
SonarQube怎么安装才能保证数据不丢？
保证数据不丢的关键是外接PostgreSQL并定期备份数据库，Docker方式下，用docker exec sonar-postgres pg_dump -U sonar sonar > sonar_backup.sql即可生成备份文件，另外把/opt/sonarqube/data目录整个tar打包,这样代码扫描的历史数据也一并备份了。
SonarQube社区版支持哪些语言扫描？
社区版支持Java、C#、JavaScript、TypeScript、Kotlin、Ruby、Go、Python、PHP、HTML和CSS等十余种语言，但对C/C++、Objective-C等需要商业版插件，如果你做嵌入式开发,建议先确认语言支持情况再选择版本。
sonarqube安装后如何修改默认管理员密码？
首次登录后系统会强制跳转到修改密码页面，直接设置新密码即可，如果在Docker环境且忘了密码，执行docker exec -it sonarqube bash，用管理员身份在数据库中更新users表，但更便捷的方式是直接删除卷重新初始化,因为初始状态并没有业务数据。