3. SonarQube 基础：核心概念与安装部署
SonarQube 是缺陷分析工具链中的“质量裁判”。它通过一套可量化的规则和指标，对代码库进行持续审查，并输出“通过/失败”的明确结论。理解其核心概念是整合 JIRA 与 CI/CD 管道的前提。
3.1 核心概念全景
SonarQube 的架构围绕四个核心实体构建：项目、规则、指标 和 质量门。它们之间的关系如下图所示：
关键理解：质量门是 SonarQube 的“总开关”。只有通过质量门的代码，才允许进入下一阶段（如合并到主分支或触发生产部署）。
3.2 核心概念详解
3.2.1 项目 (Project)
在 SonarQube 中，项目是代码分析的逻辑单元。通常一个项目对应一个 Git 仓库或一个微服务。每个项目拥有独立的配置、规则集和质量门。
3.2.2 规则 (Rules)
规则是 SonarQube 的“法律条文”。每条规则定义了一种代码问题（Bug、漏洞、坏味道）。规则按语言、类型和严重程度分类。
| 规则类型 | 说明 | 示例 |
|---|---|---|
| BUG | 代码中明确的错误，可能导致运行时失败 | 空指针解引用、资源未关闭 |
| VULNERABILITY | 安全漏洞，可能被攻击者利用 | SQL 注入、XSS 跨站脚本 |
| CODE_SMELL | 代码可维护性问题，降低代码质量 | 过长方法、重复代码、命名不规范 |
| SECURITY_HOTSPOT | 需要人工审查的安全敏感代码区域 | 未验证的用户输入、硬编码密码 |
3.2.3 指标 (Measures)
指标是 SonarQube 的“体检报告”。每次分析后，SonarQube 会计算数十个量化指标，用于评估代码健康状况。
- 可靠性指标：Bug 数量、可靠性评级（A-E）
- 安全性指标：漏洞数量、安全评级、安全热点数量
- 可维护性指标：代码异味数量、技术债务（人天）、可维护性评级
- 覆盖率指标：代码行覆盖率、分支覆盖率、单元测试数量
- 重复指标：重复代码行数、重复代码块数、重复密度
- 规模指标：代码行数（LOC）、注释行数、语句数、类数、函数数
3.2.4 质量门 (Quality Gate)
质量门是 SonarQube 的“准入条件”。它是一个布尔表达式，由一组条件（Condition）组成。当所有条件都满足时，质量门状态为 Passed（绿色）；否则为 Failed（红色）。
质量门条件示例：
新代码覆盖率 < 80% → 失败新增 Bug 数量 > 0 → 失败新增安全漏洞数量 > 0 → 失败新增代码异味数量 > 50 → 失败
3.3 SonarQube 安装部署
SonarQube 支持多种部署方式。以下以 Docker Compose 方式为例，演示如何快速搭建一个包含 SonarQube Server 和 PostgreSQL 数据库的生产级环境。
3.3.1 部署架构
3.3.2 环境要求
- Docker Engine >= 20.10
- Docker Compose >= 2.0
- 至少 4GB 可用内存（推荐 8GB）
- 开放端口：9000（SonarQube Web UI）
3.3.3 部署步骤
步骤 1：创建 docker-compose.yml 文件
version: "3.8"
services:
sonarqube:
image: sonarqube:community-10.6.0
container_name: sonarqube
depends_on:
- db
environment:
SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar
SONAR_JDBC_USERNAME: sonar
SONAR_JDBC_PASSWORD: sonar_pass
volumes:
- sonarqube_data:/opt/sonarqube/data
- sonarqube_extensions:/opt/sonarqube/extensions
- sonarqube_logs:/opt/sonarqube/logs
ports:
- "9000:9000"
networks:
- sonarnet
db:
image: postgres:15
container_name: sonarqube_db
environment:
POSTGRES_USER: sonar
POSTGRES_PASSWORD: sonar_pass
POSTGRES_DB: sonar
volumes:
- postgresql_data:/var/lib/postgresql/data
networks:
- sonarnet
volumes:
sonarqube_data:
sonarqube_extensions:
sonarqube_logs:
postgresql_data:
networks:
sonarnet:
driver: bridge步骤 2：启动服务
# 启动所有容器（后台运行）
docker compose up -d
# 查看启动日志
docker compose logs -f sonarqube步骤 3：访问并初始化
- 浏览器访问
http://localhost:9000 - 默认管理员账号：
admin/ 密码：admin - 首次登录后，系统会强制要求修改管理员密码
⚠️ 生产环境注意事项：
- 不要使用默认密码，立即修改为强密码。
- PostgreSQL 数据库建议使用独立服务器或托管服务。
- Elasticsearch 存储路径建议挂载 SSD 磁盘。
- 根据代码量调整 JVM 堆内存：
SONARQUBE_WEB_JVM_OPTS=-Xmx2048m
3.4 验证安装
部署完成后，通过以下步骤验证 SonarQube 是否正常工作：
- 检查服务状态：
docker compose ps，确保所有容器状态为Up。 - 访问 Web UI：打开
http://localhost:9000，确认登录页面正常显示。 - 创建测试项目：在 UI 中手动创建一个测试项目，生成一个令牌（）。
- 运行本地分析：在本地代码目录中执行 Sonar Scanner CLI，验证分析结果能否成功上报。
快速验证命令：
docker run --rm -e SONAR_HOST_URL="http://localhost:9000" -e SONAR_="your_" -v "$(pwd):/usr/src" sonarsource/sonar-scanner-cli