SonarQube Server 安装与项目初始化

1. Linux 内核参数#

SonarQube 底层依赖搜索引擎组件，对 Linux 文件数和虚拟内存映射数量有要求。常见检查命令：

1
sysctl vm.max_map_count
2
sysctl fs.file-max
3
ulimit -n
4
ulimit -u

常见建议值：

1
sudo sysctl -w vm.max_map_count=524288
2
sudo sysctl -w fs.file-max=131072
3
ulimit -n 131072
4
ulimit -u 8192

持久化可以写入：

1
/etc/sysctl.d/99-sonarqube.conf
2
/etc/security/limits.d/99-sonarqube.conf

如果用 systemd 管理 SonarQube，还要在 unit 的 [Service] 中设置：

1
LimitNOFILE=131072
2
LimitNPROC=8192

2. 数据库准备#

生产环境应使用外部数据库。以 PostgreSQL 为例：

1
CREATE DATABASE sonarqube;
2
CREATE USER sonar WITH ENCRYPTED PASSWORD 'sonar_password';
3
GRANT ALL PRIVILEGES ON DATABASE sonarqube TO sonar;

实际生产环境要使用强密码，并按数据库版本兼容性选择支持版本。

1. Docker Compose 示例#

更接近真实环境的写法是配 PostgreSQL：

1
services:
2
  sonarqube:
3
    image:  swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/sonarqube:community
4
    container_name: sonarqube
5
    depends_on:
6
      - postgres
7
    ports:
8
      - "9000:9000"
9
    environment:
10
      SONAR_JDBC_URL: jdbc:postgresql://postgres:5432/sonarqube
11
      SONAR_JDBC_USERNAME: sonar
12
      SONAR_JDBC_PASSWORD: sonar
13
      SONAR_ES_BOOTSTRAP_CHECKS_DISABLE: true
14
    volumes:
15
      - ./sonarqube_data:/opt/sonarqube/data
16
      - ./sonarqube_extensions:/opt/sonarqube/extensions
17
      - ./sonarqube_logs:/opt/sonarqube/logs
18

19
  postgres:
20
    image: swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/postgres:15
21
    container_name: sonarqube-postgres
22
    environment:
23
      POSTGRES_DB: sonarqube
24
      POSTGRES_USER: sonar
25
      POSTGRES_PASSWORD: sonar
26
    volumes:
27
      - ./postgresql_data:/var/lib/postgresql/data

1
sudo mkdir sonarqube_{data,extensions,logs}
2
sudo useradd --system --create-home --shell /bin/bash sonar
3
sudo chown -R sonar:sonar sonarqube*

启动：

1
docker compose up -d
2
docker compose logs -f sonarqube

2. Docker 常见注意点#

• vm.max_map_count 是宿主机参数，不是只在容器里改。
• 生产环境密码不要明文写在公开仓库里。
• SonarQube 和 PostgreSQL 数据卷必须持久化。
• 升级前先备份数据库和 SonarQube 数据。

1. 创建运行用户#

1
sudo useradd --system --create-home --shell /bin/bash sonarqube

不要用 root 直接运行 SonarQube。

2. 解压安装包#

1
sudo unzip sonarqube-*.zip -d /opt
2
sudo ln -s /opt/sonarqube-* /opt/sonarqube
3
sudo chown -R sonarqube:sonarqube /opt/sonarqube*

3. 配置数据库连接#

编辑：

1
/opt/sonarqube/conf/sonar.properties

设置 PostgreSQL：

1
sonar.jdbc.username=sonar
2
sonar.jdbc.password=sonar_password
3
sonar.jdbc.url=jdbc:postgresql://127.0.0.1:5432/sonarqube

4. 启动和停止#

切换到运行用户：

1
sudo su - sonarqube
2
/opt/sonarqube/bin/linux-x86-64/sonar.sh start
3
/opt/sonarqube/bin/linux-x86-64/sonar.sh status
4
/opt/sonarqube/bin/linux-x86-64/sonar.sh stop

查看日志：

1
tail -f /opt/sonarqube/logs/sonar.log
2
tail -f /opt/sonarqube/logs/web.log
3
tail -f /opt/sonarqube/logs/es.log
4
tail -f /opt/sonarqube/logs/ce.log

5. systemd 管理思路#

生产环境通常用 systemd 管理进程。关键点不是 unit 模板本身，而是：

• 使用 sonarqube 用户运行。
• 设置 LimitNOFILE 和 LimitNPROC。
• 确认启动脚本路径和 Java 环境正确。
• 日志能被排查人员找到。

1. 添加 Helm 仓库#

1
helm repo add sonarqube https://SonarSource.github.io/helm-chart-sonarqube
2
helm repo update

2. 创建命名空间#

1
kubectl create namespace sonarqube

3. 准备 values.yaml#

一个简化示例：

1
edition: community
2

3
service:
4
  type: ClusterIP
5

6
ingress:
7
  enabled: true
8
  hosts:
9
    - name: sonarqube.example.com
10

11
postgresql:
12
  enabled: false
13

14
jdbcOverwrite:
15
  enable: true
16
  jdbcUrl: jdbc:postgresql://postgres.example.com:5432/sonarqube
17
  jdbcUsername: sonar
18
  jdbcPassword: sonar_password
19

20
persistence:
21
  enabled: true

不同 chart 版本字段可能变化，实际落地前要以当前 chart 的 values.yaml 为准。

4. 安装或升级#

1
helm upgrade --install sonarqube sonarqube/sonarqube \
2
  -n sonarqube \
3
  -f values.yaml

检查状态：

1
kubectl get pods -n sonarqube
2
kubectl logs -n sonarqube deploy/sonarqube

5. Kubernetes 常见注意点#

• 存储要持久化，避免 Pod 重建后数据丢失。
• 数据库建议使用独立托管 PostgreSQL，而不是随应用一起临时跑。
• Ingress、TLS、反向代理路径要和 sonar.core.serverBaseURL 等配置匹配。
• 节点也可能需要满足 vm.max_map_count 等系统参数要求。

1. 创建项目#

登录 SonarQube Web 后，创建项目时需要关注：

• Project Key：项目唯一标识。
• Project Name：页面展示名称。
• Main Branch：主分支名称。

Project Key 后续会写到扫描配置中，建议稳定、可读、不要频繁变动。

2. 创建 Token#

扫描需要 token。推荐使用项目级 token，并只授予当前项目分析权限。

运行扫描时优先通过环境变量传入：

1
export SONAR_TOKEN="your-project-token"

不要把 token 明文写进仓库。

3. 第一次登录后的基础设置#

建议先做几件事：

• 修改默认管理员密码。
• 配置 Server Base URL。
• 设置项目权限和用户组。
• 确认默认 Quality Gate。
• 确认项目使用的 Quality Profile。

1. 只启动容器，不准备持久化#

如果数据库和数据目录没有持久化，重建容器可能导致项目配置和历史分析结果丢失。

2. token 写进配置文件#

sonar.token 可以作为参数传入，但不建议写进仓库里的配置文件。更安全的方式是使用环境变量或 CI/CD 凭据管理。

3. Project Key 随便改#

Project Key 是项目身份。随意更改会导致扫描结果进入另一个项目，历史趋势也会断开。

4. 没看日志就猜原因#

安装失败时优先看：

• web.log
• es.log
• ce.log
• 容器或 Pod 日志
• 数据库连接日志