SonarQube 代码质量静态分析¶

# 启动 SonarQube 社区版
docker run -d \
  --name sonarqube \
  -p 9000:9000 \
  sonarqube:community  # 社区版，免费

# 访问 http://localhost:9000
# 默认账号密码：admin / admin（首次登录要求改密码）

# docker-compose.yml
version: "3"
services:
  sonarqube:
    image: sonarqube:community
    ports:
      - "9000:9000"  # Web 界面端口
    environment:
      - SONAR_JDBC_URL=jdbc:postgresql://db:5432/sonarqube  # 数据库连接
      - SONAR_JDBC_USERNAME=sonar  # 数据库用户
      - SONAR_JDBC_PASSWORD=sonar  # 数据库密码
    volumes:
      - sonarqube_data:/opt/sonarqube/data  # 数据持久化
      - sonarqube_logs:/opt/sonarqube/logs  # 日志
    depends_on:
      - db

  db:
    image: postgres:15
    environment:
      - POSTGRES_USER=sonar
      - POSTGRES_PASSWORD=sonar
      - POSTGRES_DB=sonarqube
    volumes:
      - postgresql_data:/var/lib/postgresql/data

volumes:
  sonarqube_data:
  sonarqube_logs:
  postgresql_data:

docker compose up -d  # 启动

# 方式一：npm 安装（JS/TS 项目推荐）
npm install -D sonarqube-scanner  # 安装扫描器

# 方式二：全局安装
npm install -g sonarqube-scanner

# 方式三：下载独立版
# 从 https://docs.sonarqube.org/latest/analyzing-source-code/scanners/sonarscanner/ 下载

# sonar-project.properties - 项目根目录
sonar.projectKey=my-project  # 项目唯一标识
sonar.projectName=My Project  # 项目名称
sonar.sources=src  # 源码目录
sonar.tests=tests  # 测试目录
sonar.host.url=http://localhost:9000  # SonarQube 地址
sonar.token=sqa_xxxxxx  # 认证令牌（在 SonarQube 界面生成）

# 语言相关
sonar.language=ts  # 语言（可选，自动检测）
sonar.sourceEncoding=UTF-8  # 源码编码

# 覆盖率报告（需要先跑测试生成报告）
sonar.javascript.lcov.reportPaths=coverage/lcov.info  # JS/TS 覆盖率
# sonar.python.coverage.reportPaths=coverage.xml  # Python 覆盖率

# 先生成测试覆盖率报告
npm run test:coverage  # 或 pytest --cov --cov-report=xml

# 运行 SonarQube 扫描
npx sonar-scanner  # 读取 sonar-project.properties 配置并扫描

# 或者用命令行参数
npx sonar-scanner \
  -Dsonar.projectKey=my-project \
  -Dsonar.sources=src \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.token=sqa_xxxxxx

# .github/workflows/sonar.yml
name: SonarQube Analysis
on:
  push:
    branches: [main]
  pull_request:

jobs:
  sonar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 完整克隆（SonarQube 需要 git 历史）

      - name: 安装依赖并测试
        run: |
          npm ci
          npm run test:coverage  # 生成覆盖率报告

      - name: SonarQube 扫描
        uses: sonarsource/sonarqube-scan-action@master
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

在 SonarQube Web 界面配置质量门禁：
Quality Gates → Create → 设置条件：

推荐条件：
- 新代码覆盖率 >= 80%（Coverage on New Code）
- 新代码重复率 <= 3%（Duplicated Lines on New Code）
- 可维护性评级 = A（Maintainability Rating）
- 可靠性评级 = A（Reliability Rating）
- 安全性评级 = A（Security Rating）
- 安全热点审查率 = 100%（Security Hotspots Reviewed）

不满足条件 → PR 阻止合并

在 SonarQube 界面：
Rules → 搜索规则 → 选择激活/停用

Quality Profiles → 创建自定义配置文件 → 选择启用的规则集
可以针对不同项目使用不同的规则配置

# sonar-project.properties
sonar.exclusions=**/*.test.ts,**/*.spec.ts,**/node_modules/**  # 排除测试文件和依赖
sonar.coverage.exclusions=**/config/**,**/types/**  # 覆盖率排除配置文件和类型定义
sonar.cpd.exclusions=**/migrations/**  # 重复代码检测排除迁移文件

# CLI 命令
npx sonar-scanner  # 运行扫描
npx sonar-scanner -Dsonar.verbose=true  # 详细输出
npx sonar-scanner -Dsonar.projectKey=xxx  # 指定项目

# 严重级别
BLOCKER    # 阻断级：必须立即修复
CRITICAL   # 严重级：应尽快修复
MAJOR      # 主要级：应该修复
MINOR      # 次要级：建议修复
INFO       # 提示级：了解即可

# 评级说明
A：无问题或极少 / B：有一些小问题 / C：有中等问题
D：有严重问题 / E：有大量严重问题

# 常用指标
Bugs                    # Bug 数量
Vulnerabilities         # 安全漏洞数
Code Smells             # 坏味道数
Coverage                # 测试覆盖率
Duplicated Lines (%)    # 重复代码比率
Technical Debt          # 技术债务（修复时间）