最稳方案是直接使用官方Docker镜像sonarqube:lts-community，避免tar.gz手动部署引发的Java版本错配、权限混乱、内存配置错误三连坑；镜像已预装JDK 17、默认调优内存参数并自动挂载关键路径，同时需确保PostgreSQL预建用户/库及pg_trgm、btree_gin扩展，且scanner URL、token域名与Nginx反代Host头完全一致，并显式指定-Dfile.encoding=UTF-8。
直接用 sonarqube:lts-community Docker 镜像启动最稳，别碰 tar.gz 手动解压部署——90% 的失败都卡在 Java 版本错配、目录权限混乱、内存参数没调这三件事上。
为什么必须用 Docker 启动 sonarqube:lts-community
官方自 9.0 起就弃用内置 H2 数据库的“开箱即用”模式，tar.gz 包默认仍走 H2，真连 PostgreSQL/MySQL 就得自己改 sonar.properties、调 JVM 参数、修文件属主，稍一疏忽就报 java.lang.OutOfMemoryError: Metaspace 或 Failed to bind to 0.0.0.0/0.0.0.0:9000。而 sonarqube:lts-community 镜像已预装适配的 JDK 17、设好 -Xms2g -Xmx2g、自动挂载关键路径，省掉所有环境校验环节。
实操建议：
- 宿主机至少留出 4GB 可用内存，Docker 启动时显式加
-e SONAR_JAVA_OPTS="-Xms2g -Xmx2g"，别信“默认够用” - 别把
sonarqube容器和 PostgreSQL 容器塞在同一台低配机器上跑；本地开发用postgres:15-alpine即可，但必须提前建库建用户 -
docker run命令里必须挂载/opt/sonarqube/data和/opt/sonarqube/extensions到宿主机，否则重启后数据全丢
PostgreSQL 初始化必须手建用户+库+扩展
SonarQube 启动时若发现 schema 为空，会尝试自动建表，但在 PostgreSQL 15+ 上大概率失败，典型报错是 ERROR: permission denied to create extension "pg_trgm" 或 relation "projects" does not exist。根本原因是连接用户没 CREATEDB 权限，且缺 pg_trgm 和 btree_gin 两个扩展。
进 psql 执行以下命令（注意替换密码）：
CREATE USER sonarqube WITH PASSWORD 'your_strong_pwd'; CREATE DATABASE sonarqube OWNER sonarqube; \c sonarqube CREATE EXTENSION IF NOT EXISTS pg_trgm; CREATE EXTENSION IF NOT EXISTS btree_gin;
验证是否生效：psql -U sonarqube -d sonarqube -h localhost -c "SELECT 1" 能返回 1 才算通。
sonar-scanner 连不上？先对齐这三个 URL
本地跑 sonar-scanner 提示 Unable to execute SonarQube，95% 不是网络不通，而是三个地方域名不一致：
-
sonar-scanner配置里的sonar.host.url（比如http://sonar.example.com） - SonarQube Web 界面右上角生成 token 时显示的访问域名（必须和上面完全一样）
- Nginx 反代配置中实际设置的
Host头（比如proxy_set_header Host $host;）
三者只要有一个是 localhost、一个是 127.0.0.1、一个是 sonar.example.com，就会认证失败或重定向跳转异常。统一用带协议+域名的完整地址，别混用。
最容易被忽略的是 JVM 编码参数：无论用 Docker 还是手动部署，-Dfile.encoding=UTF-8 必须显式加进 SONAR_JAVA_OPTS，否则中文注释、路径、日志全乱码，且错误日志里不会明确提示这点。
