SonarQube在Kubernetes中必须独立部署PostgreSQL（Deployment+Service），宿主机需配置vm.max_map_count≥262144，存储须用支持POSIX锁的ReadWriteOnce云盘或NFSv4.1，且data目录需chown 1001:1001确保可写。
SonarQube 在 Kubernetes 中不是“直接部署就能用”的应用，它强依赖外部数据库（PostgreSQL），且对内核参数、存储、启动顺序有明确要求。跳过数据库解耦或忽略 vm.max_map_count 配置，90% 的部署会在 Pod 启动后卡在 Starting SonarQube... 状态，日志里反复报 java.lang.OutOfMemoryError: Map failed 或连接 PostgreSQL 超时。
PostgreSQL 必须独立部署，不能和 SonarQube 共享 Pod
早期教程里把 PostgreSQL 和 SonarQube 打包进同一个 StatefulSet（甚至 Deployment）是错误实践。原因很实际：
-
SonarQube启动前必须确保 PostgreSQL 已就绪并能接受连接，Kubernetes 原生不保证容器启动顺序； - 两者资源需求差异大：PostgreSQL 需要稳定内存和 I/O，SonarQube 启动阶段 JVM 内存压力高，混部易互相干扰；
- 升级/备份/扩缩容必须解耦——你不会因为想升级
sonarqube:9.9就顺手重启数据库。
正确做法：用独立的 Deployment + Service 部署 PostgreSQL，再通过 SONARQUBE_JDBC_URL 环境变量指向该 Service 名（如 jdbc:postgresql://postgres:5432/sonarqube）。不要用 localhost 或 127.0.0.1 ——那会绕过 Kubernetes DNS，导致连接失败。
vm.max_map_count 必须在宿主机层面调高
SonarQube 从 7.x 开始底层依赖 Elasticsearch（嵌入式），而 ES 对 Linux 的 vm.max_map_count 有硬性要求（默认值 65530 远不够）。Pod 内部改 sysctl 无效，必须在每个 Node 上执行：
sysctl -w vm.max_map_count=262144
并写入 /etc/sysctl.conf 持久化：
echo "vm.max_map_count=262144" >> /etc/sysctl.conf
没做这步，你会看到 Pod 日志卡在：
ERROR: [1] bootstrap checks failed [1]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]
注意：如果你用的是托管 K8s（如 EKS、AKS、GKE），需确认节点镜像或节点组配置是否已预设该值；否则只能提工单或换自建节点。
StorageClass 和 PVC 必须支持 ReadWriteOnce，且不能用 NFSv3
SonarQube 的 /opt/sonarqube/data 目录要求文件系统支持 POSIX 文件锁（flock），而大多数 NFSv3 实现不满足。现象是 Pod 反复 CrashLoopBackOff，日志出现：
java.nio.file.FileSystemException: /opt/sonarqube/data/es7: Device or resource busy
解决方案：
- 优先使用本地盘（
hostPath）或云盘（如 AWS EBS、Azure Disk、Aliyun CloudDisk）； - 若必须用 NFS，请升到 NFSv4.1+，并在 PV 定义中显式指定：
mountOptions: ["nfsvers=4.1", "hard"]； - PVC 的
accessModes必须是ReadWriteOnce（RWO），ReadWriteMany（RWX）虽能挂载成功，但会导致 Elasticsearch 启动失败。
别信某些示例里用 emptyDir 或 ReadWriteMany PVC 的写法——那是临时测试能跑通，生产一压就崩。
配置项优先用环境变量，别硬塞进 sonar.properties
官方镜像（sonarqube:latest）设计上优先读取环境变量，覆盖 sonar.properties。比如：
-
SONARQUBE_JDBC_USERNAME比sonar.jdbc.username优先级高； -
SONARQUBE_WEB_JAVA_OPTS控制 JVM 参数，比改sonar.sh安全可靠； - LDAP 配置也建议用环境变量（
SONAR_AUTHENTICATION_LDAP_*），避免 ConfigMap 挂载出错导致启动失败。
硬编码进 ConfigMap 的 sonar.properties 容易因换行、缩进、注释格式引发解析错误，而且每次改配置都要重建 ConfigMap 和滚动更新 Pod——远不如直接改 Deployment 的 env 字段来得快。
最常被忽略的一点：SonarQube 的 data 和 extensions 目录必须由非 root 用户可写，但官方镜像默认以 UID 1001 运行。如果你的 StorageClass 创建的 PV 底层目录权限是 root:root 且无写权限，Pod 会因无法创建子目录直接退出。检查方式很简单：kubectl exec -it <sonar-pod> -- ls -ld /opt/sonarqube/data</sonar-pod> —— 如果显示 Permission denied，就得提前在 NFS 或云盘上 chown 1001:1001 对应路径。
