SonarQube 与 Jenkins 自动化集成与代码扫描（CD 实验指南）

SonarQube 与 Jenkins 自动化集成与代码扫描（CD 实验指南）

1. 实验概述

本指南用于记录并指导首次安装 SonarQube 后，如何将其与 Jenkins 进行深度对接，实现持续集成（CI）过程中的自动化代码质量扫描与质量阀（Quality Gate）回传。

1.1 环境信息

角色	服务组件	IP 地址	默认端口	备注
代码托管	GitLab 17.1	192.168.108.30	80	触发源
持续集成	Jenkins 2.555.2	192.168.108.31	8080	执行流水线
质量分析	SonarQube 2026.5 Community	192.168.108.32	9000	分析代码并出具报告

---

2. SonarQube 端配置

为了允许 Jenkins 安全地推送扫描数据并接收分析结果，需在 SonarQube 端进行凭证与 Webhook 配置。

2.1 生成安全访问 Token

1. 登录 SonarQube 界面（http://192.168.108.32:9000）。
2. 点击右上角用户头像 -> My Account（我的账号） -> Security（安全）。
3. 在 Generate Token 区域输入名称（例如 jenkins-token），类型选择 User Token。
4. 点击 Generate，获取生成的 Token：

squ_e7fad1dbfeb8d4f0c15efe79f07988855e1bb1f9

⚠️ 安全提示：该 Token 仅在生成时可见，请妥善保存。

2.2 配置 Webhook 回传

Webhook 用于在扫描完成后，由 SonarQube 异步将质量阀（Quality Gate）的结果主动推送到 Jenkins。

1. 在 SonarQube 界面，点击顶部导航栏的 Administration（配置） -> Configuration -> Webhooks。
2. 点击 Create 按钮，填写如下信息：
   • Name: jenkins-webhook
   • URL: http://192.168.108.31:8080/sonarqube-webhook/
3. 点击 Create 保存。

   💡 避坑提示：URL 末尾的斜杠 / 必须保留，否则 Jenkins 可能会拒绝解析此请求。

---

3. Jenkins 端配置

3.1 安装必要插件

进入 Manage Jenkins -> Plugins，安装以下三个核心插件：

1. SonarQube Scanner（集成扫描仪管理）
2. GitLab（用于对接 GitLab 触发器与代码拉取）
3. Pipeline（支持声明式与脚本式工作流）

3.2 配置 SonarQube 服务器凭据

将 SonarQube 产生的 Token 托管给 Jenkins 凭据系统。

1. 进入 Manage Jenkins -> Credentials（凭据管理） -> System -> Global credentials。
2. 点击 Add Credentials：
   • Kind: Secret text
   • Secret: 粘贴刚才生成的 Token（squ_e7fad1dbfeb8...）
   • ID: sonarqube-token（自定义，后续系统关联时调用）
   • Description: SonarQube Authentication Token

3.3 系统关联 SonarQube Server

1. 进入 Manage Jenkins -> System（系统配置）。
2. 找到 SonarQube servers 配置项，勾选 Environment variables。
3. 点击 Add SonarQube 并填写：
   • Name: SonarQube-Server
   • Server URL: http://192.168.108.32:9000
   • Server authentication token: 选择刚才创建的 sonarqube-token 凭据。
4. 保存配置。

3.4 注册 SonarQube Scanner 工具

1. 官方下载地址（若需手动安装）：sonar-scanner-cli 官方归档。
2. 进入 Manage Jenkins -> Tools（全局工具配置）。
3. 找到 SonarQube Scanner installations，点击 Add SonarQube Scanner：
   • Name: SonarQube-Scanner
   • 勾选 Install automatically（自动安装）。可以指定特定版本，让 Jenkins 在首次执行任务时自动完成环境下载与解压。

---

4. 实验验证：Pipeline 语法测试

为验证 Jenkins 是否能正确拉取、安装并执行 sonar-scanner 工具，避免因全局 tools 块解析失败导致构建异常，采用以下动态调用工具路径的 Pipeline 脚本进行首轮验证。

4.1 验证流水线脚本

在 Jenkins 中新建一个 Pipeline（流水线） 任务，将以下脚本粘贴至配置中：

pipeline {
    agent any
    
    // 此处不采用全局 tools 声明，使用脚本动态加载，提高兼容性
    
    stages {
        stage('Verify Sonar Scanner') {
            steps {
                script {
                    // 使用插件内置的类名和配置工具名称动态获取本地路径
                    def scannerHome = tool name: 'SonarQube-Scanner', type: 'hudson.plugins.sonar.SonarRunnerInstallation'
                    echo "Sonar Scanner 本地安装路径为: ${scannerHome}"
                    
                    // 在 Jenkins 节点上执行版本查询命令
                    sh "${scannerHome}/bin/sonar-scanner --version"
                }
            }
        }
    }
}

4.2 验证结果说明

• 首次启动任务时，Jenkins 会通过配置的下载源自动获取 sonar-scanner-cli 包并解压至工作空间。
• 成功输出指标：在构建日志（Console Output）中，应能输出类似如下内容：

  Sonar Scanner 本地安装路径为: /var/jenkins_home/tools/hudson.plugins.sonar.SonarRunnerInstallation/SonarQube-Scanner
  INFO: Scanner version: X.X.X
  INFO: Java version: X.X.X
  

  至此，说明 Jenkins 与 SonarQube 的底层扫描通路已完全打通。

---

5. 总结与后续规划

通过本次实验，成功在 Jenkins 2.555.2 与 SonarQube 2026.5 之间建立了：

1. 单向认证通路（通过安全 Token 认证）。
2. 异步结果回调机制（通过 Webhook 异步推送到 /sonarqube-webhook/ 路径）。
3. Scanner 环境自治（通过 Pipeline 动态 tool 引用避免了解析器报错）。

接下来的步骤可以将具体的业务项目代码引入，在流水线中加入编译、质量红线拦截（waitForQualityGate()）以及自动化 CD 部署阶段。