跳到主要内容

SonarQube 代码质量分析配置指南

本文档介绍如何配置和使用 SonarQube 进行代码质量分析。

概述​

SonarQube 是一个开源的代码质量管理平台，用于持续检测代码质量、安全性和可靠性。iForge 项目已配置 SonarQube 集成，支持自动化代码分析。

功能特性​

  • 代码质量检查：检测代码异味、重复代码、复杂度问题
  • 安全漏洞扫描：识别常见安全漏洞（SQL 注入、XSS、命令注入等）
  • 测试覆盖率：集成 Go 和 TypeScript 测试覆盖率报告
  • 技术债务追踪：量化技术债务并提供修复建议
  • 质量门禁：设置质量门槛，阻止低质量代码合并

本地部署 SonarQube​

前置要求​

  • Docker 和 Docker Compose
  • 至少 4GB 可用内存
  • 至少 10GB 磁盘空间

启动 SonarQube​

# 进入项目根目录
cd d:\code\iforge\iforge

# 启动 SonarQube 和 PostgreSQL
docker-compose -f deploy/sonarqube/docker-compose.yml up -d

# 查看日志
docker-compose -f deploy/sonarqube/docker-compose.yml logs -f sonarqube

访问 SonarQube​

首次登录后需要修改密码。

停止 SonarQube​

docker-compose -f deploy/sonarqube/docker-compose.yml down

清理数据（可选）​

docker-compose -f deploy/sonarqube/docker-compose.yml down -v

配置 GitHub Actions​

1. 获取 SonarQube Token​

  1. 登录 SonarQube: http://localhost:9000
  2. 进入 My Account → Security
  3. 在 Generate Tokens 部分，创建新 token
  4. 命名 token（如 github-actions），选择类型 Global Analysis
  5. 复制生成的 token

2. 配置 GitHub Secrets​

在 GitHub 仓库中配置以下 secrets：

  1. 进入仓库 Settings → Secrets and variables → Actions
  2. 添加以下 secrets：
    • SONAR_TOKEN: 上一步生成的 token
    • SONAR_HOST_URL: SonarQube 服务器 URL
      • 本地测试: http://host.docker.internal:9000（Docker Desktop）
      • 生产环境: https://sonarqube.your-domain.com

3. 触发分析​

配置完成后，以下事件会自动触发 SonarQube 分析：

  • Push 到 main 分支
  • Pull Request 到 main 分支

本地运行分析​

安装 SonarScanner​

# 下载 SonarScanner
# Windows
choco install sonarscanner

# macOS
brew install sonar-scanner

# 或手动下载：https://docs.sonarqube.org/latest/analysis/scan/sonarscanner/

运行分析​

# 进入项目根目录
cd d:\code\iforge\iforge

# 生成 Go 测试覆盖率
cd api
go test ./... -coverprofile=coverage.out -covermode=atomic
cd ..

# 运行 SonarScanner
sonar-scanner \
  -Dsonar.projectKey=iforge \
  -Dsonar.sources=api,web \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.token=YOUR_TOKEN

配置文件说明​

sonar-project.properties​

项目根目录的 sonar-project.properties 文件包含 SonarQube 分析配置：

# 项目标识
sonar.projectKey=iforge
sonar.projectName=iForge
sonar.projectVersion=1.0.0

# 源代码位置
sonar.sources=api,web

# 测试覆盖率报告路径
sonar.go.coverage.reportPaths=api/coverage.out
sonar.javascript.lcov.reportPaths=web/coverage/lcov.info

# 排除规则
sonar.exclusions=**/node_modules/**,**/vendor/**,**/*.pb.go

CI 工作流配置​

.github/workflows/ci.yml 包含 SonarQube 分析步骤：

sonarqube:
  name: SonarQube Analysis
  runs-on: ubuntu-latest
  needs: [backend, frontend]
  steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0
    
    - name: SonarQube Scan
      uses: SonarSource/sonarqube-scan-action@v4
      env:
        SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

质量门禁配置​

内置质量门禁​

SonarQube 提供默认质量门禁，包含以下条件：

  • 覆盖率：新代码覆盖率 ≥ 80%
  • 重复率：新代码重复率 ≤ 3%
  • 可维护性：无新的 Code Smell
  • 可靠性：无新的 Bug
  • 安全性：无新的 Vulnerability

自定义质量门禁​

  1. 进入 Quality Gates → Create
  2. 添加条件，例如：
    • Coverage on New Code ≥ 70%
    • Duplicated Lines (%) on New Code ≤ 5%
    • Maintainability Rating on New Code = A
  3. 将质量门禁应用到项目

常见问题​

Q: SonarQube 启动失败​

A: 检查以下项：

  • 确保 Docker 有足够的内存（至少 4GB）
  • 检查端口 9000 是否被占用
  • 查看日志：docker-compose logs sonarqube

Q: 分析失败，提示找不到覆盖率报告​

A: 确保先运行测试生成覆盖率报告：

cd server && go test ./... -coverprofile=coverage.out

Q: Quality Gate 检查失败​

A: 查看 SonarQube 仪表板，分析具体问题：

  • 覆盖率不足：添加更多单元测试
  • 重复代码：重构重复逻辑
  • 代码异味：修复 SonarQube 标记的问题

Q: 如何排除某些文件​

A: 在 sonar-project.properties 中配置：

sonar.exclusions=**/generated/**,**/vendor/**

最佳实践​

  1. 定期审查：每周审查 SonarQube 报告，及时处理新问题
  2. 渐进式改进：先关注新代码质量，逐步清理技术债务
  3. 团队协作：将 SonarQube 报告纳入代码审查流程
  4. 自动化：配置 CI/CD 自动分析，阻止低质量代码合并
  5. 持续学习：参考 SonarQube 提供的修复建议，提升团队编码水平

相关资源​