slms/docs/SONARQUBE_CONFIG_FIX.md

SonarQube 配置修复文档

问题分析

对比两个项目的配置差异

SLMS 项目（有问题）

environment {
    JAVA_HOME = 'E:\\2025-2026\\GitAIOps\\jdk'
    ANDROID_HOME = 'D:\\development\\Android'
    SONAR_HOST_URL = 'http://localhost:9000'
    SONAR_PROJECT_KEY = 'slms:smart-library-management-system'
}

CSTATM-MTE 项目（正常工作）

environment {
    SONAR_HOST_URL = 'http://localhost:9000'
    SONAR_PROJECT_KEY = 'sqp_9d031755bd0b2619fa06f5002e7aa9d6aef349d6'
    SONARQUBE_SCANNER_PARAMS = '-Dsonar.qualitygate.wait=true -Dsonar.qualitygate.timeout=300'
    SONARQUBE_QUALITY_GATE = 'CSTATM-MTE-Quality-Gate'
}

关键差异

1. 缺少 SONARQUBE_SCANNER_PARAMS

   • 这个参数告诉 SonarQube Scanner 等待质量阈结果
   • 超时时间设置为 300 秒（5分钟）

2. 缺少 SONARQUBE_QUALITY_GATE

   • 指定使用的质量阈名称
   • 需要在 SonarQube 中创建对应的质量阈

3. SONAR_PROJECT_KEY 格式

   • SLMS 使用项目名称格式
   • CSTATM-MTE 使用 token 格式（但这不是必须的）

修复方案

1. 更新 Jenkinsfile 环境变量

environment {
    JAVA_HOME = 'E:\\2025-2026\\GitAIOps\\jdk'
    ANDROID_HOME = 'D:\\development\\Android'
    SONAR_HOST_URL = 'http://localhost:9000'
    SONAR_PROJECT_KEY = 'slms:smart-library-management-system'
    SONARQUBE_SCANNER_PARAMS = '-Dsonar.qualitygate.wait=true -Dsonar.qualitygate.timeout=300'
    SONARQUBE_QUALITY_GATE = 'SLMS-Quality-Gate'
}

2. 修改 Stage 4 和 Stage 5（关键修复）

原来的实现（有问题）：

• Stage 4 中手动解析 report-task.txt 获取 CE Task ID
• Stage 5 中使用 waitForQualityGate abortPipeline: false
• 复杂且容易出错

修复后的实现（参考 cstatm-mte）：

stage('4. SonarQube 质检') {
    when {
        expression { currentBuild.result == null || currentBuild.result == 'SUCCESS' }
    }
    steps {
        echo '========== 执行 SonarQube 代码质量检测 =========='
        dir('SLMS') {
            withSonarQubeEnv('SonarQube') {
                bat '''
                    set JAVA_HOME=%JAVA_HOME%
                    mvn sonar:sonar -Dsonar.qualitygate.wait=true -Dsonar.qualitygate.timeout=300
                '''
            }
        }
        echo '✓ SonarQube 分析完成'
    }
}

stage('5. 质量阈检查') {
    steps {
        echo '========== 等待 SLMS-Quality-Gate 质量门禁结果 =========='
        timeout(time: 10, unit: 'MINUTES') {
            script {
                withSonarQubeEnv('SonarQube') {
                    def qg = waitForQualityGate()
                    if (qg.status != 'OK') {
                        error "SLMS-Quality-Gate 质量门禁未通过: ${qg.status}"
                    } else {
                        echo "✓ SLMS-Quality-Gate 质量门禁检查通过: ${qg.status}"
                    }
                }
            }
        }
    }
}

关键改进：

1. ✅ 在 mvn sonar:sonar 命令中直接添加 -Dsonar.qualitygate.wait=true
2. ✅ 使用 withSonarQubeEnv 包裹 waitForQualityGate()
3. ✅ 简化逻辑，移除复杂的 CE Task ID 解析
4. ✅ 使用标准的质量阈检查方式

3. 在 SonarQube 中配置质量阈

1. 登录 SonarQube: http://localhost:9000
2. 进入 Quality Gates 页面
3. 创建新的质量阈 "SLMS-Quality-Gate"
4. 设置质量阈规则（建议配置）：
   • Coverage < 80% → Failed
   • Duplicated Lines (%) > 3% → Failed
   • Maintainability Rating worse than A → Failed
   • Reliability Rating worse than A → Failed
   • Security Rating worse than A → Failed

4. 删除旧项目并重新测试

步骤 1: 删除 SonarQube 上的项目

# 在 SonarQube Web UI 中
1. 进入项目 "slms:smart-library-management-system"
2. Project Settings → Deletion
3. 确认删除

步骤 2: 推送代码触发 Jenkins 构建

# 在本地 Git 仓库
git add .
git commit -m "fix: 修复 SonarQube 配置，添加质量阈等待参数"
git push origin feature-ldl

步骤 3: 观察 Jenkins 流水线

• 查看 Jenkins 构建日志
• 确认 SonarQube 扫描阶段输出
• 验证质量阈检查是否正常等待

步骤 4: 验证 SonarQube 项目

• 确认项目自动创建
• 检查质量阈是否关联
• 查看分析结果

预期结果

Jenkins 日志应该显示

========== 执行 SonarQube 代码质量检测 ==========
[INFO] Analysis report uploaded in XXXms
[INFO] ANALYSIS SUCCESSFUL, you can browse http://localhost:9000/dashboard?id=slms:smart-library-management-system
[INFO] Note that you will be able to access the updated dashboard once the server has processed the submitted analysis report
[INFO] More about the report processing at http://localhost:9000/api/ce/task?id=AY...
✓ SonarQube 分析完成

========== 等待 SonarQube 质量阈结果 ==========
[INFO] Waiting for quality gate result...
[INFO] Quality gate status: PASSED
✓ 质量阈检查通过

SonarQube 项目应该

• ✅ 自动创建项目
• ✅ 关联正确的质量阈
• ✅ 显示完整的分析结果
• ✅ Webhook 正常触发

故障排查

如果质量阈仍然超时

1. 检查 SonarQube 服务状态
2. 查看 SonarQube 日志: logs/ce.log
3. 确认 Webhook 配置正确
4. 增加超时时间到 600 秒

如果项目未自动创建

1. 检查 SonarQube 权限配置
2. 确认 Jenkins SonarQube 插件配置
3. 验证 SONAR_PROJECT_KEY 格式

如果 Webhook 未触发

1. 在 SonarQube 中检查 Webhook 配置
2. 测试 Webhook URL 可达性
3. 查看 Jenkins 日志确认接收情况

参考文档

• SonarQube Quality Gates
• Jenkins SonarQube Plugin
• SonarQube Scanner Parameters