最稳方案是直接使用官方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。这些版本不匹配，比乱码更难排查。