最稳方案是直接使用官方Docker镜像sonarqube:lts-community，避免tar.gz手动部署引发的Java版本、权限、内存配置三连坑；需配PostgreSQL（预建用户/库及pg_trgm、btree_gin扩展），并确保scanner URL、token域名与Nginx反代Host头完全一致，同时JVM必须指定-Dfile.encoding=UTF-8。
直接装官方 Docker 镜像最稳，别碰 tar.gz 手动部署
Linux 上跑 SonarQube，90% 的人卡在 Java 版本、权限、内存配置三连坑里。官方早就不推荐手动解压 sonarqube-*.tar.gz 启动了——它默认用内置 H2 数据库，仅限 demo；真要检测代码，必须连 PostgreSQL 或 MySQL，而手动部署时数据库初始化、目录权限、sonar.properties 路径错位一多，java.lang.OutOfMemoryError: Metaspace 或 Failed to bind to 0.0.0.0/0.0.0.0:9000 就轮着来。
实操建议：
- 用 Docker：官方镜像
sonarqube:lts-community已预装适配的 Java 17 + 内存参数，且自动挂载/opt/sonarqube/data和/opt/sonarqube/extensions - 宿主机至少留 4GB 可用内存，Docker 启动时加
-e SONAR_JAVA_OPTS="-Xms2g -Xmx2g"，别信“默认够用” - 别把
sonarqube容器和数据库容器放在同一台低配机器上跑 PostgreSQL；本地开发用postgres:15-alpine即可，但记得提前建好sonarqube用户和数据库
PostgreSQL 初始化必须手建用户+库，不能靠 SonarQube 自动创
SonarQube 启动时若发现数据库连接成功但 schema 为空，会尝试自动建表——这在 PostgreSQL 15+ 上大概率失败，报错 ERROR: permission denied to create extension "pg_trgm" 或 relation "projects" does not exist。根本原因是：SonarQube 连接用户没被授 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; - 检查
sonarqube用户是否能登录：psql -U sonarqube -d sonarqube -h localhost -c "SELECT 1"
scanner CLI 报 Unable to execute SonarQube 多半是 token 或 URL 没对齐
本地跑 sonar-scanner 提示连不上服务端，不是网络问题，而是三个地方常不一致：Scanner 配置里的 sonar.host.url、SonarQube 界面右上角生成 token 时用的域名、以及 Nginx 反代实际暴露的 Host 头。比如你在 http://localhost:9000 登录生成了 token，但用 sonar-scanner -Dsonar.host.url=https://sonar.example.com 提交，就会因 CORS 或 401 被拒。
排查顺序：
- 先确认 SonarQube 容器日志有没有
Web server is started，再 curl 宿主机curl -v http://localhost:9000/api/server/version看通不通 - Scanner 的
sonar-project.properties里sonar.host.url必须和浏览器访问地址完全一致（协议、端口、路径前缀都不能差） - 如果用了 Nginx 反代，确保
proxy_set_header Host $host;和proxy_set_header X-Forwarded-For $remote_addr;都写了，否则 SonarQube 认为请求来源非法
中文项目乱码或注释不分析？改 JVM 参数比改编码更有效
Java 或 Python 项目扫描后中文注释全变 ，或者 sonar.language 设了 java 却不识别 Lombok 注解，本质不是文件编码问题，而是 SonarQube JVM 启动时没指定 UTF-8 字符集，导致底层 ASM 或 ANTLR 解析器读字节流出错。
解决方式很简单，只改一处：
- 如果是 Docker，启动时加环境变量：
-e SONAR_JAVA_OPTS="-Dfile.encoding=UTF-8 -Xms2g -Xmx2g" - 如果是 systemd 托管的 jar 包，编辑
/etc/systemd/system/sonarqube.service，在ExecStart=行末尾追加-Dfile.encoding=UTF-8 - 别去改源码文件的
file.encoding属性或强制转码——Scanner 本身不处理文件内容，它只把 AST 结构发给服务端
真正影响分析深度的是插件兼容性：Lombok 需要 sonar-java 插件 ≥ 7.26；Python 3.11+ 要用 sonar-python ≥ 3.17。这些版本不匹配，比乱码更难排查。
