SonarQube 8.3.1 与 PostgreSQL 9.6 生产级部署实践

1. 项目概述：为什么是 SonarQube 8.3.1 搭配 PostgreSQL 9.6 这个组合？

SonarQube 8.3.1 + PostgreSQL 9.6 这个组合，不是随便凑的版本号，而是特定历史阶段下一套经过大量企业级验证、稳定性与兼容性高度平衡的技术栈。我最早在某高校实验室做代码质量平台迁移时接触这个组合，后来在某中型软件公司的持续集成流水线改造项目里又完整复现了三遍——每次都不是为了“怀旧”，而是因为真实业务场景卡在几个关键约束上：既要满足老旧生产环境对 JDK 11 以下版本的强依赖（SonarQube 8.3.1 是最后一个官方支持 JDK 8 的 LTS 版本），又要规避 MySQL 在高并发扫描任务下的锁表风险，同时还得让 DBA 团队能用熟悉的运维工具链接手数据库维护。PostgreSQL 9.6 正好踩在这个交点上：它原生支持并行查询、BRIN 索引和逻辑复制，对 SonarQube 那种高频小事务+偶发大对象写入（比如分析报告快照）的混合负载非常友好；而它的 WAL 归档机制和 pg_dump/pg_restore 流程，又比当时主流 MySQL 5.7 的主从切换方案更可控。很多人一看到“9.6”就皱眉，觉得太老，但实际跑下来，只要避开已知的 CVE-2018-1058 权限绕过漏洞（需打补丁或升级到 9.6.24+），这套组合在日均 200+ 次代码扫描、单库承载 15 个以上 Java/Python 项目的环境下，连续稳定运行超过 27 个月。它解决的核心问题很实在：不是追求最新特性，而是用最低的运维成本守住代码质量门禁的可用性底线。适合谁？适合那些技术栈尚未全面容器化、CI/CD 流水线仍以 Jenkins 为主、且 DBA 团队对 PostgreSQL 有成熟备份恢复 SOP 的中小团队。如果你正被 SonarQube 升级后插件不兼容、MySQL 主从延迟导致质量报告滞后、或者 JDK 版本锁死等问题反复折腾，这个组合就是一条被踩实的退路。

2. 整体架构设计与选型逻辑：为什么不用 Docker、为什么坚持 9.6、为什么跳过 8.4+

搭建 SonarQube 8.3.1 + PostgreSQL 9.6，表面看是装两个软件，背后其实是三重权衡：基础设施约束、数据生命周期管理、以及长期可维护性。先说为什么没选 Docker。我试过用官方 sonarqube:8.3.1-community 镜像搭配 postgres:9.6-alpine，启动倒是快，但两周后就暴雷——Docker 容器内嵌的 JVM 参数无法动态调整堆内存，而 SonarQube 在分析大型前端项目（比如含 Webpack SourceMap 的 Vue 项目）时，ES 嵌入式节点会因 GC 频繁触发 OOM Killer，容器直接退出。更麻烦的是日志落盘问题：容器默认 stdout/stderr 日志轮转策略和 SonarQube 自身的 access.log、ce.log 分离机制冲突，导致审计日志丢失。最终我们退回裸机部署，用 systemd 管理服务，配合 logrotate 按大小+时间双维度切割，日志可追溯性提升一个量级。再说 PostgreSQL 9.6 的坚守逻辑。官方文档明确标注 SonarQube 8.3.x 支持 PostgreSQL 9.3–11，但 9.6 是分水岭。9.3–9.5 缺少并行 VACUUM，而 SonarQube 的 metrics 表每天新增数万行，不及时清理会导致 bloat 率飙升，磁盘空间三个月吃紧；9.7+ 虽然功能更强，但某公司 DBA 团队的自动化巡检脚本只适配到 9.6，强行升级意味着要重写整套监控指标采集逻辑，ROI 太低。最后解释为何跳过 8.4+。SonarQube 8.4 引入了全新的 Quality Gate 引擎，要求所有规则必须通过 REST API 显式启用，而我们存量的 37 个自定义 Java 规则（基于 PMD 和 Checkstyle 封装）全部失效，重写规则描述文件耗时 11 人日。8.3.1 的规则管理仍是 Web UI 可视化勾选，迁移成本几乎为零。这个架构设计的本质，是把“能跑通”和“能管住”拆开：SonarQube 负责代码分析逻辑的确定性，PostgreSQL 负责数据持久化的可靠性，中间用最薄的 JDBC 层粘合，拒绝任何抽象层带来的不可控变量。实测下来，这套组合在 4C8G 的虚拟机上，支撑 50 人研发团队的日常扫描，平均响应延迟稳定在 1.2 秒以内，CE（Compute Engine）任务积压率低于 3%，比同配置下 MySQL 方案低 17 个百分点。

2.1 数据库选型对比：PostgreSQL 9.6 vs MySQL 5.7 vs Embedded H2

选 PostgreSQL 9.6 不是拍脑袋，而是拉出三台同配置测试机（CentOS 7.6, 4C8G, SSD）跑满 72 小时压力测试后的结论。核心指标不是吞吐量，而是“长尾延迟”和“故障恢复速度”。我们模拟了真实场景：每分钟触发 1 次全量扫描（含 5 个模块，总代码行数 120 万），同时每 5 秒插入 1 条质量门禁结果记录。测试结果如下表：

提示：P95 延迟才是影响用户体验的关键。MySQL 在第 36 小时出现一次 189ms 的尖峰，原因是 InnoDB 的 purge thread 被大事务阻塞，导致后续所有 INSERT 等待。PostgreSQL 的 MVCC 实现更彻底，长事务只影响自身 snapshot，不影响其他连接。H2 虽快，但单点故障风险极高——某次磁盘 I/O 中断 2.3 秒，H2 数据库文件直接损坏，恢复失败。

更关键的是数据一致性保障。SonarQube 的 Compute Engine 任务是典型的“两阶段提交”：先写 task 表标记任务开始，再写 analysis 表存结果，最后更新 project_measures 表更新指标。PostgreSQL 的SERIALIZABLE隔离级别能保证这三张表的跨事务一致性，而 MySQL 5.7 的REPEATABLE READ在极端情况下会出现幻读，导致质量门禁状态错乱（比如明明扫描失败，页面却显示“通过”）。我们曾用 JMeter 模拟 200 并发 CE 任务，MySQL 环境下复现了 3 次状态不一致，PostgreSQL 0 次。这不是理论缺陷，是血泪教训换来的选型依据。

2.2 SonarQube 8.3.1 的 LTS 属性与生态兼容性锚点

SonarQube 8.3.1 是 2020 年 3 月发布的长期支持版本（LTS），官方承诺提供 3 年安全补丁更新（至 2023 年 3 月），这个时间窗口恰好覆盖了大多数企业的年度 IT 预算周期。它的核心价值在于“冻结接口”：REST API v2 的/api/measures/component、/api/qualitygates/project_status等 17 个关键端点，在整个 8.3.x 小版本迭代中保持完全兼容。这意味着你写的 Jenkins Pipeline 脚本、GitLab CI 的 quality gate check、甚至自研的钉钉告警机器人，只要适配了 8.3.1，后续升级到 8.3.2、8.3.3 无需任何修改。反观非 LTS 版本，比如 8.5，API 返回结构微调（periods字段从数组变为对象），就导致我们一个已上线半年的自动化报表系统崩溃。另一个常被忽略的锚点是插件生态。SonarJava 6.15（对应 Java 14 支持）、SonarJS 7.2（支持 ES2020）、SonarPython 3.0（支持 type hints）这三个主力语言插件，其最后一个兼容 8.3.1 的版本，恰恰是它们各自功能最成熟的稳定版。SonarJava 6.15 的符号解析引擎比 7.x 版本更轻量，对老旧 Spring Boot 1.5 项目的类路径扫描成功率高出 22%；SonarJS 7.2 对 Webpack 4 的 source map 解析准确率是 98.7%，而 8.x 版本在处理动态 import() 语法时偶发丢包。这些细节，只有在真实项目里踩过坑才会懂。所以选择 8.3.1，本质是选择了一个“能力封顶但足够用、接口冻结且无惊喜”的确定性基线。

3. 核心环境准备与依赖解析：JDK、系统参数、内核调优的硬性门槛

SonarQube 8.3.1 对底层环境的要求，远比官网文档写的更苛刻。它不像新版本那样能自动降级适配，很多参数是“硬编码检查”，不达标直接拒绝启动。我整理了一份必须逐项核验的清单，漏掉任何一项，都会在sonar.log里看到 cryptic 的错误信息，比如Failed to start component [org.sonar.core.platform.ComponentContainer]，这种报错根本看不出根源。

3.1 JDK 8u202+ 的强制要求与 GC 参数陷阱

SonarQube 8.3.1 官方声明支持 JDK 8，但实测发现，低于 JDK 8u202 的版本（如常见的 8u181）会在启动时卡在 Elasticsearch 初始化阶段，日志里只有一行Starting Elasticsearch...，然后静默超时。根本原因是 SonarQube 8.3.1 内嵌的 ES 7.3.2 使用了 JDK 8u202 引入的java.nio.file.Files.isSameFile()新实现，旧版本该方法存在符号链接解析缺陷。解决方案只有两个：要么升级 JDK，要么打 Oracle 的 CPU 补丁（不推荐，补丁兼容性难验证）。我们最终统一部署 JDK 8u232，这是 8u 系列最后一个公开更新版本，安全性有保障。

JVM 参数设置更是深坑。官网推荐-Xmx4g -Xms4g，但这是针对纯分析场景。在生产环境，必须额外加入 GC 相关参数：

-XX:+UseG1GC -XX:MaxGCPauseMillis=200 -XX:+ExplicitGCInvokesConcurrent -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/opt/sonarqube/logs/heap.hprof

重点解释-XX:+ExplicitGCInvokesConcurrent：SonarQube 的 Web Server（基于 Jetty）和 Compute Engine（独立 JVM）之间通过文件系统交换任务，CE 进程在完成任务后会显式调用System.gc()通知 Web Server 清理缓存。如果不加这个参数，System.gc()会触发 Full GC，停顿时间长达 8~12 秒，导致 Web 界面假死。加上后，它转为并发 GC，停顿控制在 200ms 内。这个参数在 JDK 8u202+ 才被完全稳定支持，早于该版本可能引发 GC 循环。

3.2 Linux 系统级调优：vm.max_map_count 与 fs.file-max 的生死线

PostgreSQL 9.6 和 SonarQube 内嵌 ES 都极度依赖内存映射（mmap）。ES 要求vm.max_map_count至少为 262144，否则启动报错max virtual memory areas vm.max_map_count [65536] is too low。但很多人只改了这个，忘了fs.file-max。当并发扫描任务超过 30 个时，PostgreSQL 的连接池（默认 50）和 ES 的 HTTP 连接（默认 10000）会争抢文件描述符，fs.file-max必须设为 1048576（即 100 万）。设置方法不是简单 echo，必须写入/etc/sysctl.conf并执行sysctl -p生效：

echo "vm.max_map_count = 262144" >> /etc/sysctl.conf echo "fs.file-max = 1048576" >> /etc/sysctl.conf sysctl -p

注意：ulimit -n用户级限制必须同步调整。在sonar用户的~/.bashrc里添加ulimit -n 65536，否则 systemd 启动的服务会继承系统默认的 1024，照样爆 open files 错误。

另一个隐形杀手是swappiness。默认值 60 会让内核过于激进地将匿名页换出到 swap，而 SonarQube 的 JVM 堆内存是锁定的（-XX:+AlwaysPreTouch），swap 操作会直接失败，触发 OOM。必须设为 1：

echo "vm.swappiness = 1" >> /etc/sysctl.conf

3.3 PostgreSQL 9.6 的关键配置项：shared_buffers 与 work_mem 的黄金比例

PostgreSQL 的性能，80% 取决于shared_buffers和work_mem的设置。网上很多教程教人把shared_buffers设成物理内存的 25%，这是严重误导。SonarQube 的 workload 是 OLTP（在线事务处理）混合轻量 OLAP（分析），shared_buffers过大会挤占 OS page cache，反而降低文件读取效率。我们的实测黄金比例是：shared_buffers = 25% of RAM，但上限不超过 8GB；work_mem = shared_buffers / 4。例如 16GB 内存服务器：

# /var/lib/pgsql/9.6/data/postgresql.conf shared_buffers = 4GB work_mem = 1GB maintenance_work_mem = 2GB effective_cache_size = 12GB

effective_cache_size设为 12GB 是告诉查询规划器：“你假设 OS cache 能缓存这么多数据”，这直接影响 JOIN 策略选择。如果设得太小，规划器会倾向 Nested Loop，而 SonarQube 的project_measures和metrics表 JOIN 是典型的大表关联，Hash Join 才是高效解法。maintenance_work_mem设为 2GB 是为了加速VACUUM和CREATE INDEX，SonarQube 在首次加载大型项目时会批量建索引，这个值太小会导致索引创建耗时翻倍。

4. 完整部署流程与核心环节详解：从下载解压到质量门禁生效

部署不是复制粘贴命令，而是一系列有因果关系的操作链。每个步骤的输出，都是下一步的输入前提。我按真实操作顺序，把关键命令、预期输出、以及“为什么这么写”全部摊开。

4.1 PostgreSQL 9.6 的初始化与安全加固

第一步永远是创建专用用户和数据目录，禁止用postgres用户直接跑 SonarQube：

# 创建系统用户，禁止登录 sudo useradd -r -s /bin/false sonarpg # 创建数据目录，属主严格限定 sudo mkdir -p /var/lib/pgsql/9.6/sonarqube sudo chown -R sonarpg:sonarpg /var/lib/pgsql/9.6/sonarqube # 初始化数据库集群 sudo -u sonarpg /usr/pgsql-9.6/bin/initdb -D /var/lib/pgsql/9.6/sonarqube -E UTF8 --locale=C -U sonarpg

关键点：--locale=C是强制要求。SonarQube 的字符串排序（比如文件路径比较）依赖 C locale，用en_US.UTF-8会导致某些 SQL 查询返回空结果，质量门禁判定异常。-U sonarpg指定数据库超级用户为sonarpg，而非默认的postgres，这是最小权限原则。

第二步是配置pg_hba.conf，只允许本地 socket 连接，禁用所有网络访问：

# TYPE DATABASE USER ADDRESS METHOD local all all peer host all all 127.0.0.1/32 md5 host all all ::1/128 md5

然后创建 SonarQube 专用数据库和用户：

-- 用 psql 登录后执行 CREATE DATABASE sonarqube OWNER sonarpg ENCODING 'UTF8' LC_COLLATE 'C' LC_CTYPE 'C' TEMPLATE template0; CREATE USER sonar WITH PASSWORD 'your_strong_password'; GRANT ALL PRIVILEGES ON DATABASE sonarqube TO sonar; -- 关键：回收 public schema 的默认权限，防止越权 REVOKE CREATE ON SCHEMA public FROM PUBLIC;

注意：LC_COLLATE 'C'和LC_CTYPE 'C'必须显式指定，否则继承集群默认 locale，可能出错。REVOKE CREATE是安全红线，不执行此步，任何能连上数据库的用户都能在 public schema 下建表。

4.2 SonarQube 8.3.1 的安装与 JDBC 驱动注入

SonarQube 8.3.1 官方包不带 PostgreSQL JDBC 驱动，必须手动注入。下载postgresql-42.2.12.jar（这是 9.6 兼容性最好的版本），放到lib/jdbc/postgresql/目录：

cd /opt/sonarqube sudo mkdir -p lib/jdbc/postgresql sudo wget https://repo1.maven.org/maven2/org/postgresql/postgresql/42.2.12/postgresql-42.2.12.jar -O lib/jdbc/postgresql/postgresql-42.2.12.jar

然后编辑conf/sonar.properties，取消注释并修改以下行：

# 数据库连接 sonar.jdbc.url=jdbc:postgresql://localhost/sonarqube?currentSchema=public sonar.jdbc.username=sonar sonar.jdbc.password=your_strong_password # 指定驱动类 sonar.jdbc.driverClassName=org.postgresql.Driver # 连接池参数（关键！） sonar.jdbc.validationQuery=SELECT 1 sonar.jdbc.maxWait=5000 sonar.jdbc.minIdle=2 sonar.jdbc.maxActive=50

重点：currentSchema=public必须显式指定，否则 SonarQube 会尝试在sonarqubeschema 下建表，而 PostgreSQL 默认 search_path 是$user,public，导致表找不到。validationQuery设为SELECT 1是为了检测连接有效性，避免连接池返回失效连接。

4.3 启动服务与首次健康检查：systemd 配置与日志诊断

用 systemd 管理服务，创建/etc/systemd/system/sonarqube.service：

[Unit] Description=SonarQube service After=network.target postgresql-9.6.service [Service] Type=simple User=sonar Group=sonar PermissionsStartOnly=true ExecStart=/opt/sonarqube/bin/linux-x86-64/sonar.sh start ExecStop=/opt/sonarqube/bin/linux-x86-64/sonar.sh stop Restart=always RestartSec=10 LimitNOFILE=65536 LimitNPROC=4096 Environment=JAVA_HOME=/usr/java/jdk1.8.0_232 [Install] WantedBy=multi-user.target

启动前务必检查：

1. sonar用户对/opt/sonarqube目录有读写执行权限；
2. JAVA_HOME环境变量在Environment=中正确指向 JDK 8u232；
3. After=依赖项确保 PostgreSQL 先启动。

启动命令：

sudo systemctl daemon-reload sudo systemctl enable sonarqube sudo systemctl start sonarqube

健康检查分三层：

• 系统层：sudo systemctl status sonarqube应显示active (running)；
• 进程层：ps aux | grep sonar应看到两个 java 进程（Web Server 和 CE）；
• 应用层：curl -v http://localhost:9000/api/server/version应返回{"version":"8.3.1.34397"}。

如果卡在Starting SonarQube...，立刻查logs/sonar.log，90% 的问题是 JDBC 连接超时，此时执行sudo -u sonar psql -h localhost -U sonar sonarqube -c "SELECT 1;"验证数据库连通性。

4.4 首次登录与质量门禁配置：从 admin/admin 到生产就绪

首次访问http://<server-ip>:9000，默认账号密码是admin/admin。登录后第一件事不是扫代码，而是改密和配质量门禁：

1. 点击右上角头像 → My Account → Security → Change Password；
2. 点击 Administration → Configuration → Quality Gates → Create；
3. 命名Production-Quality-Gate，添加三条规则：
   • Coverage on New Code> 80% （新代码覆盖率）
   • New Issues= 0 （不允许新增任何严重及以上问题）
   • Duplicated Lines %< 3% （新代码重复率）

然后将此门禁绑定到默认模板：Administration → Configuration → Quality Profiles → Java → Set as Default。这样所有新项目自动继承。

实操心得：不要急着绑项目。先用sonar-scanner扫一个 100 行的测试项目（比如sonar-scanner -Dsonar.projectKey=test -Dsonar.sources=. -Dsonar.host.url=http://localhost:9000 -Dsonar.login=your_admin_token），观察ce.log是否有EXECUTED状态，确认 CE 任务能正常流转。这一步省略，后面扫大项目会积压任务队列，界面显示“Processing…” 卡死。

5. 常见问题与排查技巧实录：从连接拒绝到指标消失的 7 类真实故障

在 12 个不同客户的部署中，我总结出 7 类最高频、最隐蔽的问题。每个都附带“现象-根因-速查命令-修复方案”四件套，全是血换来的经验。

5.1 现象：Web 界面显示 “Database connection failed”，但 psql 命令行能连

根因：PostgreSQL 的pg_hba.conf中，host规则的ADDRESS字段写成了127.0.0.1/24（错误），正确应为127.0.0.1/32。/24表示匹配 127.0.0.0~127.0.0.255，而 SonarQube 的 JDBC URL 解析后 IP 是127.0.0.1，但内核路由可能走 lo 接口，导致匹配失败。

速查命令：

# 查看当前生效的 hba 规则 sudo -u postgres psql -c "SHOW hba_file;" sudo cat /var/lib/pgsql/9.6/sonarqube/pg_hba.conf | grep host # 检查连接来源 IP sudo tail -f /var/lib/pgsql/9.6/sonarqube/pg_log/*.log | grep "connection"

修复方案：将host all all 127.0.0.1/24 md5改为host all all 127.0.0.1/32 md5，然后sudo systemctl reload postgresql-9.6。

5.2 现象：扫描任务在 CE 队列中卡住，状态一直是 “IN_PROGRESS”

根因：sonar.ce.javaOptsJVM 参数未设置，CE 进程默认只分配 512MB 堆内存，分析中型项目（>5 万行）时频繁 GC，任务超时被标记为失败，但日志里只打印Task cancelled due to timeout，不报错。

速查命令：

# 查看 CE 进程的 JVM 参数 ps aux | grep "sonar-ce" | grep -o "-Xmx[^ ]*" # 查看 CE 日志中的 GC 统计 sudo tail -100 /opt/sonarqube/logs/ce.log | grep "GC"

修复方案：编辑conf/sonar.properties，添加：

sonar.ce.javaOpts=-Xmx2g -Xms2g -XX:+UseG1GC -XX:MaxGCPauseMillis=200

然后重启 SonarQube。

5.3 现象：项目页面显示 “No measures found”，所有指标为空

根因：PostgreSQL 的search_path被意外修改。SonarQube 的 SQL 查询默认不带 schema 前缀（如SELECT * FROM projects），依赖search_path包含public。如果 DBA 执行过ALTER DATABASE sonarqube SET search_path TO sonarqube,public;，而sonarqubeschema 不存在，查询就失败。

速查命令：

-- 登录 PostgreSQL 后执行 SELECT current_database(), current_schema(), current_schemas(true); -- 检查是否存在 public schema \dn

修复方案：执行ALTER DATABASE sonarqube RESET search_path;，然后重启 SonarQube。

5.4 现象：中文项目名显示为 “????”，但代码文件内容正常

根因：PostgreSQL 服务端编码是UTF8，但客户端连接时未指定client_encoding。JDBC URL 缺少?currentSchema=public&clientEncoding=UTF8参数。

速查命令：

-- 查看数据库编码 SHOW server_encoding; -- 查看当前连接编码 SHOW client_encoding;

修复方案：修改sonar.jdbc.url为：

sonar.jdbc.url=jdbc:postgresql://localhost/sonarqube?currentSchema=public&clientEncoding=UTF8

5.5 现象：sonar-scanner报错 “Unable to load component class org.sonar.scanner.scan.filesystem.FileIndexer”

根因：Scanner 版本与 SonarQube 8.3.1 不兼容。官方明确要求 Scanner 4.2+，但 4.2.0.1873 版本存在 ClassLoader bug，必须用 4.2.0.1874 或更高。

速查命令：

sonar-scanner -version # 检查 scanner 的 lib 目录是否有冲突 jar ls ~/.sonar/scanner/lib/ | grep "guava\|commons"

修复方案：下载sonar-scanner-cli-4.2.0.1874-linux.zip，解压覆盖旧版本。

5.6 现象：/api/qualitygates/project_statusAPI 返回{"status":"ERROR","conditions":[]}，条件为空

根因：Quality Gate 绑定到了错误的 Quality Profile。SonarQube 要求 Quality Gate 的规则必须在项目使用的 Quality Profile 中启用。如果 Profile 里没启用Coverage on New Code规则，即使 Gate 里配置了，API 也返回空条件。

速查命令：

# 获取项目使用的 Profile ID curl -u admin:your_password "http://localhost:9000/api/qualityprofiles/search?language=java" # 检查该 Profile 下规则启用状态 curl -u admin:your_password "http://localhost:9000/api/rules/search?f=severity,lang,templateKey,actives&ps=500&qprofile=AYZ1234567890"

修复方案：进入 Web UI → Quality Profiles → Java → Activate More → 搜索并启用Coverage on New Code。

5.7 现象：sonar.log频繁打印 “Too many open files”，服务随机挂起

根因：sonar用户的ulimit -n未生效。systemd 服务默认继承系统DefaultLimitNOFILE=1024，即使~/.bashrc里写了ulimit -n 65536，systemd 启动时不读该文件。

速查命令：

# 查看 sonar 进程的实际 limits cat /proc/$(pgrep -f "sonar-web")/limits | grep "Max open files"

修复方案：在/etc/systemd/system/sonarqube.service的[Service]段添加：

LimitNOFILE=65536 LimitNPROC=4096

然后sudo systemctl daemon-reload && sudo systemctl restart sonarqube。

6. 运维与扩展建议：备份策略、监控指标、平滑升级路径

这套组合不是一劳永逸，需要建立可持续的运维习惯。我分享三个最实用的建议，都是从客户现场抄回来的。

6.1 数据库备份：pg_dump + WAL 归档的双保险

只靠pg_dump全量备份不够，必须开启 WAL 归档，实现任意时间点恢复（PITR）。在postgresql.conf中添加：

archive_mode = on archive_command = 'test ! -f /var/lib/pgsql/9.6/sonarqube/archive/%f && cp %p /var/lib/pgsql/9.6/sonarqube/archive/%f' archive_timeout = 300

然后创建归档目录并授权：

sudo mkdir -p /var/lib/pgsql/9.6/sonarqube/archive sudo chown -R sonarpg:sonarpg /var/lib/pgsql/9.6/sonarqube/archive

每日凌晨 2 点执行全量备份脚本（/root/backup_sonar.sh）：

#!/bin/bash DATE=$(date +%Y%m%d) sudo -u sonarpg /usr/pgsql-9.6/bin/pg_dump -h localhost -U sonar -F c -b -v -f "/backup/sonarqube_${DATE}.dump" sonarqube # 清理 7 天前的备份 find /backup -name "sonarqube_*.dump" -mtime +7 -delete

提示：-F c生成自定义格式，支持并行恢复；-b备份大对象（SonarQube 的二进制报告存于此）；-v输出详细日志便于审计。这个脚本在某金融客户环境运行 3 年，成功恢复过 2 次误删项目数据。

6.2 关键监控指标：用 Prometheus + Grafana 看透瓶颈

SonarQube 自带的/api/system/status只能看启停状态，真正要定位性能瓶颈，得盯住四个指标：

• JVM 堆内存使用率（jvm_memory_used_bytes{area="heap"}）：持续 > 85% 说明-Xmx设置不足；
• PostgreSQL 连接数（pg_stat_database_connections{datname="sonarqube"}）：接近max_connections（默认 100）时，CE 任务会排队；
• ES 线程池拒绝数（elasticsearch_thread_pool_rejected_count{thread_pool="write"}）：> 0 表示写入压力过大，需调大thread_pool.write.queue_size；
• CE 任务积压数（sonar_ce_task_queue_size）：来自 SonarQube 的 JMX Exporter，> 5 表示 CE 处理不过来。

我们用jmx_exporter抓取 SonarQube JMX 指标，postgres_exporter抓取 PG 指标，全部喂给 Prometheus。Grafana 仪表盘里，我把这四个指标放在首页顶部，红绿灯预警：绿色（正常）、黄色（>70%）、红色（>90% 或 >0）。某次客户反馈“扫描变慢”，我看仪表盘发现sonar_ce_task_queue_size稳定在 8，立刻知道是 CE 资源不足，扩容 CE JVM 内存后秒解。

6.3 平滑升级路径：从 8.3.1 到 9.x 的避坑指南

升级不是stop -> replace -> start。SonarQube 的数据库迁移脚本（sonarqube-9.9.0.65466/sql/upgrade/) 有严格顺序，跳步必崩。我们的升级 checklist：

1. 备份