在美国服务器部署SonarQube,如何配置运行环境并验证启动?
在美国服务器上部署 SonarQube,需要先把 Java、PostgreSQL、Linux 内核参数和进程权限配置完整,再验证 Web 服务、后台计算进程及内置搜索引擎是否正常启动。本文采用 Ubuntu Server 24.04 LTS x86_64、SonarQube Server 2025.1 LTA 系列、OpenJDK 17、PostgreSQL 16 的部署组合,使用 ZIP 安装包和 systemd 管理服务,最后通过 Nginx 提供 HTTPS 访问。
上线目标是:SonarQube 使用独立低权限账户运行,数据库仅供本机访问,9000 端口不对公网开放,用户通过域名访问管理界面,并能完成一次代码分析验证。美国机房的位置不会改变软件依赖,但会影响国内人员访问、CI 上传分析报告和下载安装包的链路表现,因此要分别检查服务器本机状态与外部访问结果。
A5数据提供美国物理服务器租用,覆盖常规Xeon与AMD EPYC平台,并配备不同内存、NVMe存储及CN2 GIA线路方案,可为SonarQube的Java应用、PostgreSQL数据库、搜索索引和CI分析任务提供独立硬件资源。针对代码规模、历史数据量及访问来源的差异,A5数据也提供多档CPU、存储与网络配置,支持美国用户访问和跨境分析链路的部署需求。
一、准备条件:先冻结版本、资源和网络边界
1. 明确版本与部署范围
本文使用的是 SonarQube Server 2025.1 LTA 系列,不是 SonarQube Community Build。不同产品线、不同版本的 Java 和数据库要求可能变化,不能只凭“SonarQube”这个名称套用同一套环境。
下载时应选择该系列的具体补丁版本,并核对对应版本的运行环境要求、发行说明和许可条件。商业版本还需准备对应许可证;安装包下载成功、服务启动成功,并不等于已经获得全部功能的使用权限。
本教程适用于单机部署,数据库与应用位于同一台服务器。不覆盖集群、跨主机数据库和既有实例升级。若服务器已经运行 SonarQube,应先完成应用配置、数据库和安装目录备份,不要直接执行下面的首次安装步骤。

| 对象 | 本文采用的配置 | 验证方法 |
|---|---|---|
| 操作系统 | Ubuntu Server 24.04 LTS,x86_64 | 查看系统版本和架构 |
| 服务端 Java | OpenJDK 17 | 指定 Java 路径执行 -version |
| 数据库 | PostgreSQL 16 | 查看版本并测试应用账户连接 |
| 安装方式 | ZIP 包、独立账户、systemd | 检查目录、运行身份和服务状态 |
| 外部入口 | Nginx HTTPS,域名示例为 sonar.example.com | 检查证书、响应及登录页面 |
| 内部监听 | SonarQube 仅监听 127.0.0.1:9000 | 使用 ss 检查绑定地址 |
文中的域名、路径和容量都是部署示例,终端输出也是用于判断状态的示例,不代表具体服务器的执行记录。
2. 准备服务器资源和访问条件
小型团队试运行可从 4 vCPU、8 GiB 内存、50 GB 可用 SSD 空间 起步,但这只是参考配置,不是所有项目的容量保证。项目数量、代码规模、历史分析记录和并发任务会影响实际资源需求。数据库与应用同机时,还要为 PostgreSQL、操作系统缓存及备份预留空间。
实施前应具备以下条件:
- 可以通过 SSH 管理服务器,并具备
sudo权限。 - 域名已解析到服务器的公网入口。
- 已取得该域名对应的有效 TLS 证书和私钥。
- 能访问 Ubuntu 软件源及所选版本的安装包下载地址。
- 云平台安全组只开放必要入口;SSH 限制来源地址,Web 使用 443,使用 HTTP 跳转时开放 80。
- 不向公网开放 9000、5432,以及 SonarQube 内置搜索组件的端口。
后续命令在 root shell 中执行:
sudo -i
cat /etc/os-release
uname -m
free -h
df -h / /opt /var/lib/postgresql
预期系统为 Ubuntu 24.04,架构为 x86_64。如果是 ARM 服务器,不要直接使用本文的 linux-x86-64 启动路径,应重新核对安装包支持范围。
防火墙调整前先保存原规则,并保留当前 SSH 会话。 不要为了“验证能否访问”而关闭整个防火墙,也不要在未放行管理端口时直接启用新的防火墙策略。
二、配置 Java、数据库与 Linux 运行限制
1. 安装依赖,并确认实际使用的 Java
以下命令适用于 Ubuntu 24.04 默认软件源。它们会安装软件并可能启动 PostgreSQL、Nginx,因此应在新服务器或经过维护批准的环境中执行。
apt update
apt install -y \
openjdk-17-jdk-headless \
postgresql-16 \
nginx \
unzip \
curl \
jq \
ca-certificates
验证:
/usr/lib/jvm/java-17-openjdk-amd64/bin/java -version
psql --version
nginx -v
systemctl status postgresql --no-pager
Java 输出应显示 17 系列,PostgreSQL 客户端应显示 16 系列。后面会在服务文件中明确指定 Java 路径,避免服务器默认 Java 被其他应用修改后影响 SonarQube。
Ubuntu 的 postgresql.service 可能只是管理数据库集群的入口服务,可进一步查看实际集群:
pg_lsclusters
预期 PostgreSQL 16 的集群状态为 online。如果没有集群或状态为 down,应先修复数据库服务,不要继续启动应用。
2. 创建专用数据库和账户
SonarQube 的内置测试数据库不适合作为正式上线数据库。本文使用独立 PostgreSQL 数据库,账户不授予超级用户权限。
进入管理终端:
runuser -u postgres -- psql
执行:
CREATE ROLE sonar LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE;
\password sonar
CREATE DATABASE sonarqube OWNER sonar ENCODING 'UTF8' TEMPLATE template0;
\q
\password 会交互式要求输入密码,避免把密码写进命令历史。建议使用密码管理器生成的长随机密码;本文配置示例可使用由字母和数字组成的长密码,减少 Java properties 文件中的转义问题。
这些操作只适用于新建实例。如果账户或数据库已经存在,先核对归属与用途,不要删除重建。
验证应用账户能否经 TCP 连接:
psql -h 127.0.0.1 -U sonar -d sonarqube -W \
-c "SELECT current_user, current_database();"
预期返回:
current_user | current_database
--------------+------------------
sonar | sonarqube
这一步同时验证了密码认证、数据库名称与账户权限,比仅看到 PostgreSQL 服务运行更有意义。
检查监听范围:
ss -lntp | grep ':5432'
本文要求数据库仅监听回环地址。如果发现 0.0.0.0:5432 或 [::]:5432,应备份 PostgreSQL 配置,核对 SHOW config_file; 返回的位置,再将 listen_addresses 限制为 localhost。修改后需要重启数据库,会影响现有连接;已有其他数据库业务的服务器不能直接照改。不要用 trust 认证规避密码错误。
3. 调整搜索引擎需要的系统参数
SonarQube 内置搜索引擎对内存映射数量、文件描述符和线程数量有要求。本文设置:
vm.max_map_count不低于524288。fs.file-max不低于131072。- 服务的
LimitNOFILE为131072。 - 服务的
LimitNPROC和TasksMax为8192。
先记录原值,便于撤销:
install -d -m 0700 /root/sonarqube-deploy-backup
sysctl vm.max_map_count fs.file-max \
> /root/sonarqube-deploy-backup/kernel-before.txt
下面会新增专用 sysctl 文件。若文件已存在,应先检查和备份,不要覆盖已有部署:
test ! -e /etc/sysctl.d/99-sonarqube.conf || {
echo "配置文件已存在,请先核对"
exit 1
}
MAP_COUNT=$(sysctl -n vm.max_map_count)
FILE_MAX=$(sysctl -n fs.file-max)
(( MAP_COUNT < 524288 )) && MAP_COUNT=524288
(( FILE_MAX < 131072 )) && FILE_MAX=131072
cat > /etc/sysctl.d/99-sonarqube.conf <<EOF
vm.max_map_count=$MAP_COUNT
fs.file-max=$FILE_MAX
EOF
sysctl -p /etc/sysctl.d/99-sonarqube.conf
验证:
sysctl vm.max_map_count fs.file-max
这两个参数是主机级设置,不只影响 SonarQube。撤销时应删除本次新增的配置文件,并根据备份恢复原值;仅删除文件不会立即恢复正在运行的内核参数。
三、安装应用并交给 systemd 管理
1. 创建运行账户、解压安装包
SonarQube 不应以 root 身份运行。先确认账户未被其他业务使用:
getent passwd sonarqube
新服务器上没有输出时,再创建账户:
useradd --system --user-group \
--home-dir /opt/sonarqube \
--shell /usr/sbin/nologin sonarqube
install -d -m 0755 /opt/sonarqube-releases
从可信发布渠道下载选定版本的 ZIP 包,放入 /root/packages/ 等受控目录。不要使用随机镜像站提供的安装包。若发布渠道提供校验值或签名,应按其说明验证;仅计算本地 SHA-256,只能记录文件指纹,不能独立证明来源可信。
检查后解压:
read -r -p "输入已核验的 ZIP 完整路径:" SQ_ZIP
unzip -l "$SQ_ZIP"
确认内容属于所选版本,且目标目录不存在同名安装后,再执行:
unzip "$SQ_ZIP" -d /opt/sonarqube-releases
find /opt/sonarqube-releases \
-mindepth 1 -maxdepth 1 -type d
根据实际解压结果输入安装目录,不猜测补丁版本名称:
read -r -p "输入本次解压后的完整安装目录:" SQ_HOME
test -f "$SQ_HOME/conf/sonar.properties" || exit 1
test -x "$SQ_HOME/bin/linux-x86-64/sonar.sh" || exit 1
test ! -e /opt/sonarqube && test ! -L /opt/sonarqube || {
echo "/opt/sonarqube 已存在,请勿覆盖"
exit 1
}
ln -s "$SQ_HOME" /opt/sonarqube
chown -R sonarqube:sonarqube "$SQ_HOME"
这里的递归属主变更仅针对本次安装目录,不能扩大到整个 /opt。保留版本目录和固定入口软链接,有助于后续维护,但软链接切换并不等于数据库可以随意回退版本。
验证:
readlink -f /opt/sonarqube
ls -ld /opt/sonarqube/data /opt/sonarqube/logs /opt/sonarqube/temp
相关运行目录应对 sonarqube 账户可写。
2. 配置数据库连接和本机监听
先备份原配置:
cp -a /opt/sonarqube/conf/sonar.properties \
/root/sonarqube-deploy-backup/sonar.properties.original
editor /opt/sonarqube/conf/sonar.properties
取消或补充以下配置,保证同一配置项只有一个生效值:
sonar.jdbc.username=sonar
sonar.jdbc.password=替换为前面设置的数据库密码
sonar.jdbc.url=jdbc:postgresql://127.0.0.1:5432/sonarqube
sonar.web.host=127.0.0.1
sonar.web.port=9000
sonar.core.serverBaseURL=https://sonar.example.com
数据库密码如果包含反斜杠等字符,应遵循 Java properties 的转义规则,不能直接把任意字符串原样粘贴。不要在文章截图、工单或聊天记录中展示完整配置。
限制配置文件权限:
chown sonarqube:sonarqube /opt/sonarqube/conf/sonar.properties
chmod 0600 /opt/sonarqube/conf/sonar.properties
核对非敏感配置:
grep -E '^(sonar.jdbc.url|sonar.web.host|sonar.web.port|sonar.core.serverBaseURL)=' \
/opt/sonarqube/conf/sonar.properties
先使用版本默认的 JVM 参数,启动后再根据内存与分析负载调整。不要把全部物理内存分配给单个 Java 进程,因为数据库、搜索引擎和文件缓存也需要资源。
3. 创建 systemd 服务
以下服务文件适用于本文的 ZIP 安装和 x86_64 启动脚本。首次安装时确认不存在同名服务,再创建 /etc/systemd/system/sonarqube.service:
[Unit]
Description=SonarQube Server
Wants=network-online.target
After=network-online.target postgresql.service
[Service]
Type=simple
User=sonarqube
Group=sonarqube
WorkingDirectory=/opt/sonarqube
Environment=SONAR_JAVA_PATH=/usr/lib/jvm/java-17-openjdk-amd64/bin/java
ExecStart=/opt/sonarqube/bin/linux-x86-64/sonar.sh console
Restart=on-failure
RestartSec=10
LimitNOFILE=131072
LimitNPROC=8192
TasksMax=8192
KillSignal=SIGTERM
KillMode=mixed
TimeoutStopSec=120
UMask=0027
[Install]
WantedBy=multi-user.target
这里使用前台 console 模式,让 systemd 跟踪主进程。不要把它直接改成后台 start 命令却保留 Type=simple。
加载并启动:

systemctl daemon-reload
systemctl enable --now sonarqube
systemctl status sonarqube --no-pager
journalctl -u sonarqube -n 100 --no-pager
服务显示 active (running) 只代表进程仍在运行,不代表应用已完成初始化。首次启动需要初始化数据库和搜索索引,应继续检查应用状态:
curl --silent --show-error \
http://127.0.0.1:9000/api/system/status | jq .
成功状态示例:
{
"status": "UP"
}
实际响应还可能包含版本等字段。若返回 STARTING,稍后再次检查;若出现数据库迁移相关状态,先核对是否误接了旧版本数据库,不要未经备份就确认迁移。
验证实际进程限制与监听地址:
PID=$(systemctl show sonarqube -p MainPID --value)
grep -E 'Max open files|Max processes' "/proc/$PID/limits"
ss -lntp | grep ':9000'
预期 9000 绑定 127.0.0.1,而不是所有网络接口。
四、配置 HTTPS,并分别验证入口与分析链路
1. 使用 Nginx 提供 HTTPS
本步骤以已有证书为前提,证书和私钥示例路径分别为:
/etc/nginx/tls/sonar.example.com/fullchain.pem/etc/nginx/tls/sonar.example.com/privkey.pem
请替换为实际路径,并确保私钥不对普通账户开放读取。如果尚未准备证书,先完成证书申请和部署,不要用关闭浏览器证书校验的方式作为上线验收。
创建独立站点文件 /etc/nginx/sites-available/sonarqube。若同名文件已存在,先备份和比较内容:
server {
listen 80;
server_name sonar.example.com;
return 301 https://sonar.example.com$request_uri;
}
server {
listen 443 ssl;
server_name sonar.example.com;
ssl_certificate /etc/nginx/tls/sonar.example.com/fullchain.pem;
ssl_certificate_key /etc/nginx/tls/sonar.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
client_max_body_size 100m;
location / {
proxy_pass http://127.0.0.1:9000;
proxy_http_version 1.1;
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_connect_timeout 10s;
proxy_read_timeout 300s;
proxy_send_timeout 300s;
}
}
100m 是本例的上传限制,应结合分析报告大小调整,不是 SonarQube 的通用容量上限。Nginx 超时也不代表后台分析必须在该时间内结束。
启用并检查:
ln -s /etc/nginx/sites-available/sonarqube \
/etc/nginx/sites-enabled/sonarqube
nginx -t && systemctl reload nginx
不要盲目删除其他站点配置。若 nginx -t 失败,不要执行重启,应先修复证书路径、语法或重复站点问题。对已有业务服务器,配置修改前应备份相关文件;回滚只撤销本次站点和链接,不影响其他站点。
2. 从本机和外部各验证一次
本机检查应用:
curl --fail --silent --show-error \
http://127.0.0.1:9000/api/system/status | jq .
从有权限访问该域名的外部终端检查 HTTPS:
curl --fail --silent --show-error \
https://sonar.example.com/api/system/status | jq .
两处都返回 UP,才能说明应用运行和公网入口均正常。不要在验收命令中添加 -k;否则证书错误会被掩盖。
随后打开浏览器完成以下检查:
- 域名与证书匹配,没有证书警告。
- 页面能进入登录流程。
- 首次登录后修改默认管理员密码,不保留默认凭据。
- 按团队策略限制匿名访问,并创建日常使用账户。
- 在系统信息中核对实际安装版本,在相应管理页面检查许可证状态。
3. 用一次代码分析确认后台处理正常
“页面能打开”仅证明 Web 服务可用,不代表后台计算链路正常。建议在已有兼容 SonarScanner 的 CI 执行器上,使用一个小型测试项目验证。
扫描器的 Java 要求可能不同于服务端 Java,必须单独核对所选扫描器版本。不要因为服务器使用 Java 17,就推断所有扫描器也采用相同运行环境。
创建权限受限的分析令牌,在测试项目根目录执行。以下示例要求项目内确实存在 src 目录:
export SONAR_HOST_URL="https://sonar.example.com"
read -r -s -p "输入测试项目分析令牌:" SONAR_TOKEN
echo
export SONAR_TOKEN
sonar-scanner \
-Dsonar.projectKey=deployment-check \
-Dsonar.sources=src
unset SONAR_TOKEN
令牌不要写入代码仓库或直接放进命令参数。CI 中应使用受保护的秘密变量,避免将调试输出公开。
扫描器显示提交成功后,还需到项目后台任务页面确认任务为成功状态,并检查项目页面是否生成分析结果。报告提交成功、后台任务成功、质量门通过是三个不同结果:质量门未通过可能只是代码规则未达标,不一定是部署故障。

美国服务器与国内 CI 之间的上传时间应独立观察。如果本机接口正常,而报告提交耗时明显增加,应检查 CI 所在网络、跨境链路、Nginx 请求记录和报告大小,不要先提高 Java 堆内存。
五、常见失败:先读证据,再修改配置
故障处理按低风险顺序进行:先查看状态和日志,再核对参数,最后才调整配置或重启服务。
journalctl -u sonarqube -n 200 --no-pager
tail -n 100 /opt/sonarqube/logs/sonar.log
tail -n 100 /opt/sonarqube/logs/web.log
tail -n 100 /opt/sonarqube/logs/es.log
tail -n 100 /opt/sonarqube/logs/ce.log
这几类日志分别帮助定位整体启动、Web 与数据库、搜索引擎、后台计算问题。

| 表现或日志线索 | 可能含义 | 处理与复验 |
|---|---|---|
| 搜索进程提示不能以 root 运行 | 服务身份错误 | 检查 systemd 的 User,修复后检查实际进程账户 |
| 提示内存映射或文件句柄不足 | 内核参数或服务限制未生效 | 核对 sysctl 与 /proc 限制,修改后重启应用 |
| 数据库提示密码认证失败 | 账户、密码或配置转义错误 | 用同一账户执行 psql -h 127.0.0.1,不要改成免密码认证 |
| 数据库连接被拒绝 | 集群未运行、监听地址或端口不符 | 检查 pg_lsclusters、ss 和 JDBC URL |
| 进程退出,内核记录 OOM | 主机内存不足或 JVM 分配不合理 | 检查内存、内核日志与其他进程,不要只反复重启 |
本机状态为 UP,外部出现 502 | Nginx 上游、配置或访问条件异常 | 检查 Nginx 错误日志及上游地址 |
| HTTPS 访问失败但本机正常 | DNS、安全组、证书或外部链路问题 | 分别验证域名解析、443 连通性和证书链 |
| 分析上传返回 413 | Nginx 请求体限制过小 | 根据报告大小调整限制,测试后重新加载 |
| 页面正常但后台任务失败 | 后台计算、插件或项目分析问题 | 查看任务详情及 ce.log,不要只检查 Web 日志 |
内存问题可进一步查看:
free -h
df -h /opt /var/lib/postgresql
journalctl -k --no-pager | grep -Ei 'oom|out of memory|killed process'
不要将删除 data 目录作为通用修复步骤。搜索数据的重建会带来停机、资源消耗和状态变化,应在确认版本适用性、备份数据库并安排维护窗口后按明确流程处理。
六、上线验收与回滚检查项
1. 上线验收
正式交付前,至少逐项确认:
- 环境:系统架构、SonarQube 补丁版本、Java 与 PostgreSQL 版本已记录。
- 身份:应用使用
sonarqube运行,数据库账户不是超级用户。 - 限制:内核参数、文件句柄和线程限制已生效。
- 监听:9000 和 5432 未向公网开放,外部访问只经过预期 Web 入口。
- 启动:本机和 HTTPS 入口的系统状态均为
UP。 - 安全:默认管理员密码已修改,匿名访问、许可证和令牌权限已核对。
- 功能:至少一个测试项目完成报告提交和后台处理。
- 恢复:数据库、应用配置及版本信息已有受控备份。
可在业务开始使用前安排一次受控服务重启,确认不是只在当前终端环境下能够运行。整机重启还会影响同机其他业务,只应在维护窗口内执行。
2. 建立数据库备份
首次部署完成后,可保存一个可恢复的数据库备份:
install -d -m 0700 /root/sonarqube-backup
pg_dump -h 127.0.0.1 -U sonar -d sonarqube -W \
-Fc \
-f "/root/sonarqube-backup/sonarqube-$(date +%F-%H%M%S).dump"
该操作读取数据库,不删除现有数据,但会产生磁盘和数据库负载。备份中包含项目、权限及其他敏感信息,应限制访问,并复制到受控的异机存储。pg_dump 成功退出只是第一步,还应定期在隔离环境演练恢复。
3. 首次部署失败时如何撤销
新建实例回滚应先阻止外部继续访问,再停止应用:
systemctl disable --now sonarqube
随后按影响范围撤销:
- 确认
sites-enabled/sonarqube确实是本次创建的链接,移除该链接,执行nginx -t后重新加载 Nginx。 - 保留日志、安装目录和数据库,先定位失败原因,不急于删除。
- 撤销本次新建的 systemd 服务文件,执行
systemctl daemon-reload。 - 移除本次新增的 sysctl 文件,依据备份恢复原值;恢复前确认没有其他应用依赖这些值。
- 按保存的规则撤销安全组或防火墙变更,保留必要的 SSH 管理入口。
不建议在回滚命令中直接删除数据库、递归删除安装目录或删除运行账户。只有确认无其他依赖,并且备份可恢复后,才安排清理。
4. 涉及旧实例时,应用与数据库必须成套回滚
如果后续升级已经修改数据库结构,仅把 /opt/sonarqube 指回旧安装目录通常不够,也可能导致旧程序无法读取新数据库。
可执行的回滚边界是:停止应用,恢复升级前的数据库备份,恢复对应版本的安装包、插件和配置,再启动验证。 建议先将备份恢复到独立数据库中验证,避免直接覆盖原库。还要评估升级后新增的分析结果和配置是否会丢失。
最终回滚检查不应停在“服务显示 running”,而应重新确认系统状态为 UP、管理员能够登录、项目和权限符合备份时间点,并能完成一项测试分析。只有这些检查通过,部署或恢复才算达到可用状态。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/3651.html



