搬瓦工 VPS 搭建 SonarQube 代码质量分析平台教程

SonarQube 是全球最流行的开源代码质量和安全分析平台，支持 30 多种编程语言的静态代码分析。它可以检测代码中的 Bug、安全漏洞、代码异味和重复代码，并通过质量门（Quality Gate）机制确保只有达标的代码才能合入主分支。SonarQube 可以无缝集成到 CI/CD 流水线中，实现代码质量的持续监控。本教程将介绍如何在搬瓦工 VPS 上使用 Docker 部署 SonarQube Community Edition。部署前请确保已安装好 Docker 和 Docker Compose。

一、SonarQube 核心功能

• 多语言支持：Java、JavaScript/TypeScript、Python、Go、C/C++、PHP、C# 等 30+ 语言。
• 质量门：定义代码质量通过标准，如覆盖率不低于 80%、无新增 Bug 等。
• 安全检测：基于 OWASP Top 10 和 CWE 标准检测安全漏洞。
• 技术债务：量化代码中需要修复的问题所需时间，帮助制定改进计划。
• PR 装饰：在 Pull Request 中自动添加分析报告评论。

二、系统要求

• 内存：至少 4GB，推荐 8GB（SonarQube + PostgreSQL + Elasticsearch）
• 磁盘：至少 10GB 可用空间
• 系统参数：需要调整 vm.max_map_count

2.1 系统参数调整

# SonarQube 内嵌的 Elasticsearch 需要此参数
echo "vm.max_map_count=524288" >> /etc/sysctl.conf
echo "fs.file-max=131072" >> /etc/sysctl.conf
sysctl -p

三、Docker Compose 部署

mkdir -p /opt/sonarqube && cd /opt/sonarqube

cat > docker-compose.yml <<'EOF'
version: '3.8'

services:
  sonarqube:
    image: sonarqube:10-community
    container_name: sonarqube
    restart: always
    depends_on:
      - postgres
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://postgres:5432/sonarqube
      SONAR_JDBC_USERNAME: sonarqube
      SONAR_JDBC_PASSWORD: sonar_db_2026
    volumes:
      - sonar_data:/opt/sonarqube/data
      - sonar_extensions:/opt/sonarqube/extensions
      - sonar_logs:/opt/sonarqube/logs
    ports:
      - "127.0.0.1:9000:9000"
    ulimits:
      nofile:
        soft: 131072
        hard: 131072
      nproc:
        soft: 8192
        hard: 8192

  postgres:
    image: postgres:15-alpine
    container_name: sonar-db
    restart: always
    environment:
      POSTGRES_DB: sonarqube
      POSTGRES_USER: sonarqube
      POSTGRES_PASSWORD: sonar_db_2026
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  sonar_data:
  sonar_extensions:
  sonar_logs:
  pgdata:
EOF

docker compose up -d

3.1 初始登录

# 等待 SonarQube 启动（约 2-3 分钟）
docker logs -f sonarqube 2>&1 | grep "SonarQube is operational"

# 通过 SSH 隧道访问
ssh -L 9000:127.0.0.1:9000 root@your-server-ip
# 浏览器打开 http://localhost:9000
# 默认账户: admin / admin（首次登录后修改密码）

四、安装 SonarScanner

# 下载 SonarScanner CLI
wget https://binaries.sonarsource.com/Distribution/sonar-scanner-cli/sonar-scanner-cli-5.0.1.3006-linux.zip
unzip sonar-scanner-cli-5.0.1.3006-linux.zip
mv sonar-scanner-5.0.1.3006-linux /opt/sonar-scanner
ln -s /opt/sonar-scanner/bin/sonar-scanner /usr/local/bin/sonar-scanner

# 验证
sonar-scanner --version

五、分析项目

5.1 创建项目 Token

在 SonarQube Web 界面中：我的账户 > 安全 > 生成 Token，记录生成的 Token 值。

5.2 分析 JavaScript/TypeScript 项目

cd /opt/my-project

# 创建 sonar-project.properties
cat > sonar-project.properties <<'EOF'
sonar.projectKey=my-web-app
sonar.projectName=My Web App
sonar.projectVersion=1.0
sonar.sources=src
sonar.tests=tests
sonar.language=js
sonar.sourceEncoding=UTF-8
sonar.javascript.lcov.reportPaths=coverage/lcov.info
EOF

# 运行分析
sonar-scanner \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.token=your_project_token_2026

5.3 分析 Python 项目

cat > sonar-project.properties <<'EOF'
sonar.projectKey=my-python-app
sonar.projectName=My Python App
sonar.sources=app
sonar.tests=tests
sonar.python.coverage.reportPaths=coverage.xml
sonar.python.version=3.11
EOF

# 生成覆盖率报告后分析
pytest --cov=app --cov-report=xml
sonar-scanner -Dsonar.host.url=http://localhost:9000 -Dsonar.token=your_token

5.4 分析 Go 项目

cat > sonar-project.properties <<'EOF'
sonar.projectKey=my-go-app
sonar.projectName=My Go App
sonar.sources=.
sonar.exclusions=**/*_test.go,**/vendor/**
sonar.tests=.
sonar.test.inclusions=**/*_test.go
sonar.go.coverage.reportPaths=coverage.out
EOF

go test -coverprofile=coverage.out ./...
sonar-scanner -Dsonar.host.url=http://localhost:9000 -Dsonar.token=your_token

六、质量门配置

在 Web 界面的"质量门"页面配置通过标准：

• 新代码覆盖率 >= 80%
• 新代码无 Bug（评级 A）
• 新代码无安全漏洞（评级 A）
• 新代码重复率 < 3%
• 新代码异味数 < 10

七、CI/CD 集成

# Woodpecker CI Pipeline 集成
# .woodpecker.yml
steps:
  - name: test
    image: node:20
    commands:
      - npm ci
      - npm test -- --coverage

  - name: sonar-analysis
    image: sonarsource/sonar-scanner-cli:latest
    environment:
      SONAR_HOST_URL: https://sonar.example.com
    commands:
      - sonar-scanner -Dsonar.token=$SONAR_TOKEN
    secrets: [sonar_token]

# GitHub Actions 集成
# .github/workflows/sonar.yml
name: SonarQube Analysis
on: [push, pull_request]
jobs:
  sonar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: sonarsource/sonarqube-scan-action@master
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

八、Nginx 反向代理

cat > /etc/nginx/conf.d/sonarqube.conf <<'EOF'
server {
    listen 443 ssl http2;
    server_name sonar.example.com;

    ssl_certificate /etc/letsencrypt/live/sonar.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/sonar.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
EOF

nginx -t && systemctl reload nginx

九、常见问题

Elasticsearch 启动失败

# 确认 vm.max_map_count 已设置
sysctl vm.max_map_count

# 查看日志
docker logs sonarqube 2>&1 | grep -i error

分析超时

大型项目分析时间较长，可以增加 JVM 内存或使用 -Dsonar.scanner.javaOpts=-Xmx2g 参数。

内存不足

SonarQube Community Edition 建议至少 4GB 内存。可以在 docker-compose.yml 中限制 JVM 堆大小：

environment:
  SONAR_CE_JAVAOPTS: "-Xmx1g"
  SONAR_WEB_JAVAOPTS: "-Xmx512m"
  SONAR_SEARCH_JAVAOPTS: "-Xmx1g"

总结

SonarQube 是提升代码质量的利器，结合 Woodpecker CI 可以在每次提交时自动执行代码分析。制品管理可以搭配 Nexus，镜像仓库可以使用 Harbor，构建完整的 DevOps 工具链。选购搬瓦工 VPS 请参考 全部方案，部署 SonarQube 建议选择内存 4GB 以上的方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的折扣，购买链接：bwh81.net。