Настройка SonarQube: полный гайд от установки до первого скана

SonarQube — это серьёзный инструмент. Если ты решил его внедрить, то уже понимаешь, что просто "добавить проверку кода" недостаточно. Нужна правильная настройка, иначе получишь либо кучу ложных срабатываний, либо пропустишь реальные проблемы.

Я помню, как на одном проекте мы неправильно сконфигурировали SonarQube, и он стал флудить уведомления о нарушениях стиля. Разработчики просто игнорировали результаты. Потом пришлось переделывать всё с нуля. Вот я и решил написать как надо.

Что такое SonarQube и зачем он вообще нужен

SonarQube — это платформа для статического анализа кода. Она ловит баги, уязвимости, дублирование, нарушения стандартов — всё в автоматическом режиме. Работает как для классических проектов, так и для микросервисов.

Основной плюс: SonarQube не просто находит проблемы, но и объясняет, почему это проблема, и как её исправить. Плюс даёт метрики по всему проекту — покрытие тестами, техдолг, сложность кода.

Минусы? Ну, смотрите. SonarQube требует ресурсов на хостинг. Для малого проекта это может быть избыточно. Настройка может быть сложной, если ты не знаешь, что делаешь. И правила по умолчанию часто слишком строгие — придётся адаптировать под свой проект.

Подходит для: средних и крупных проектов, команд от 5+ человек, где нужна дисциплина в коде. Для стартапа из двух разработчиков — перебор.

Установка SonarQube на Linux/Docker

Начнём с самого простого — развёртывания. Я рекомендую Docker, потому что это быстро и воспроизводимо.

version: '3.9'
services:
  sonarqube:
    image: sonarqube:lts
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://postgres:5432/sonarqube
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: sonarpassword
      SONAR_ES_BOOTSTRAP_CHECKS_DISABLED: "true"
    ports:
      - "9000:9000"
    depends_on:
      - postgres
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_logs:/opt/sonarqube/logs

  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: sonarqube
      POSTGRES_USER: sonar
      POSTGRES_PASSWORD: sonarpassword
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  sonarqube_data:
  postgres_data:

Сохраняешь это в docker-compose.yml и запускаешь:

docker-compose up -d

Через минуту-две SonarQube будет доступен по адресу http://localhost:9000. Логин и пароль по умолчанию — admin / admin. Сразу поменяй пароль, не будь ленивым.

Если у тебя есть уже готовый PostgreSQL, то просто замени параметры в переменных окружения. SonarQube требует PostgreSQL 11+, MySQL тоже поддерживает, но PostgreSQL лучше.

Генерируем токен и настраиваем локально

Теперь нужно связать SonarQube с проектом. Для этого нужен токен.

Идёшь в SonarQube на страницу профиля (иконка в правом верхнем углу) → Security → Generate Tokens. Даёшь ему имя, например "sonar-scanner-local", и копируешь токен. Да, это выглядит как пароль. Потому что это, по сути, пароль для API.

Теперь нужен сам SonarQube Scanner — это утилита, которая сканирует твой код и отправляет результаты на сервер.

# На macOS (если есть Homebrew)
brew install sonar-scanner

# На Linux (скачиваешь вручную)
wget https://binaries.sonarsource.com/Distribution/sonar-scanner-cli/sonar-scanner-cli-5.0.1.3006-linux-x64.zip
unzip sonar-scanner-cli-5.0.1.3006-linux-x64.zip
sudo mv sonar-scanner-5.0.1.3006-linux-x64 /opt/sonar-scanner
export PATH="/opt/sonar-scanner/bin:$PATH"

Проверяешь установку:

sonar-scanner --version

Должно вывести что-то вроде "SonarQube Scanner 5.0.1.3006".

Конфигурируем проект

В корне проекта создаёшь файл sonar-project.properties:

sonar.projectKey=my_project
sonar.projectName=My Awesome Project
sonar.projectVersion=1.0.0
sonar.sources=src
sonar.tests=tests
sonar.exclusions=**/node_modules/**,**/dist/**,**/build/**
sonar.test.inclusions=**/*test.py,**/*test.js,**/spec.js
sonar.python.version=3.11
sonar.sourceEncoding=UTF-8

# Для Python проектов
sonar.python.coverage.reportPaths=coverage.xml
sonar.python.pylint.reportPath=pylint-report.txt

# Для JavaScript
sonar.javascript.lcov.reportPaths=coverage/lcov.info

# Если у тебя монорепо
sonar.modules=backend,frontend
backend.sonar.projectBaseDir=./backend
frontend.sonar.projectBaseDir=./frontend

Ключевые параметры:

• sonar.projectKey — уникальный идентификатор проекта в SonarQube. Используется в URL
• sonar.sources — папка с исходным кодом
• sonar.exclusions — что игнорировать (node_modules, dist и т.д.)
• sonar.python.version — версия Python для правильного анализа

Теперь запускаешь сканирование:

sonar-scanner \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.login=токен_который_ты_скопировал

Если всё правильно, увидишь в логах "ANALYSIS SUCCESSFUL" и проект появится в SonarQube.

Интеграция с Git и CI/CD

По-хорошему, SonarQube нужно запускать в CI/CD, а не вручную. Вот пример для GitLab CI:

stages:
  - test
  - analyze

sonarqube-check:
  stage: analyze
  image: sonarsource/sonar-scanner-cli:latest
  variables:
    SONAR_HOST_URL: "https://sonarqube.example.com"
    SONAR_LOGIN: $SONAR_TOKEN
  script:
    - sonar-scanner
      -Dsonar.projectKey=$CI_PROJECT_NAME
      -Dsonar.sources=src
      -Dsonar.host.url=$SONAR_HOST_URL
      -Dsonar.login=$SONAR_LOGIN
      -Dsonar.gitlab.project_id=$CI_PROJECT_ID
      -Dsonar.gitlab.commit_sha=$CI_COMMIT_SHA
      -Dsonar.gitlab.ref_name=$CI_COMMIT_REF_NAME
  allow_failure: true
  only:
    - merge_requests

Токен $SONAR_TOKEN добавляешь в переменные GitLab CI (Settings → CI/CD → Variables). Отмечаешь его как "Protected" и "Masked".

Для GitHub Actions:

name: SonarQube Analysis

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  sonarqube:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      
      - name: SonarQube Scan
        uses: SonarSource/sonarqube-scan-action@master
        env:
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

Настройка правил и Quality Gate

По умолчанию SonarQube использует встроенный набор правил. Но он часто слишком строгий. Нужно адаптировать под реальность.

Идёшь в Quality Profiles (Administration → Quality Profiles). Выбираешь язык, например Python. Видишь набор правил. Можешь:

1. Создать свой профиль (Clone) и отключить ненужные правила
2. Изменить severity отдельных правил (Info → Warning → Critical)
3. Добавить свои параметры к правилам

Например, если у тебя в проекте принято писать строки до 120 символов, а не 80, находишь правило "Line length" и меняешь параметр.

Теперь Quality Gate. Это условие, при котором билд проходит или падает. По умолчанию:

• Не более 3% дублирования кода
• Не более 5% покрытия пробелов
• Не более одной критической уязвимости

Настраиваешь в Administration → Quality Gates. Например, для стартапа можешь ослабить условия:

New Code:
- Reliability: A
- Security: A
- Maintainability: C (вместо B)
- Coverage: 30% (вместо требуемого)

Для зрелого проекта — наоборот, ужесточаешь.

Примеры конфигов для разных языков

Python:

sonar.python.version=3.11
sonar.python.coverage.reportPaths=coverage.xml
sonar.python.pylint.reportPath=pylint-report.txt
sonar.python.bandit.reportPaths=bandit-report.json

Перед сканированием генерируешь отчёты:

coverage run -m pytest
coverage xml
pylint src --output-format=json > pylint-report.txt
bandit -r src -f json -o bandit-report.json

JavaScript/TypeScript:

sonar.javascript.lcov.reportPaths=coverage/lcov.info
sonar.typescript.tsconfigPath=tsconfig.json
sonar.exclusions=node_modules/**,dist/**

В package.json:

"scripts": {
  "test:coverage": "jest --coverage",
  "sonar": "sonar-scanner"
}

Java:

sonar.java.binaries=target/classes
sonar.java.test.binaries=target/test-classes
sonar.java.source=11

В pom.xml:

<plugin>
  <groupId>org.jacoco</groupId>
  <artifactId>jacoco-maven-plugin</artifactId>
  <version>0.8.10</version>
  <executions>
    <execution>
      <goals>
        <goal>prepare-agent</goal>
      </goals>
    </execution>
    <execution>
      <id>report</id>
      <phase>test</phase>
      <goals>
        <goal>report</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Когда SonarQube может быть избыточным

Честно? SonarQube — тяжёлая артиллерия. Если у тебя:

• Проект из 2-3 разработчиков
• Простой стек (скрипты, простые CRUD приложения)
• Нет требований к документированию качества кода
• Бюджет на инфраструктуру минимален

...то может быть достаточно более лёгких решений. Например, просто настроенный ESLint/Pylint в CI, или встроенные в IDE проверки.

Для российских команд есть хороший вариант — использовать AI-based code review вроде Distiq. Это быстрее, не требует отдельного хостинга, работает прямо в MR/PR и находит реальные проблемы, а не зависает на стилистических нарушениях.

Но если у тебя команда от 10+ человек, критичны метрики качества, нужна история изменений техдолга — SonarQube имеет смысл.

Возможные проблемы и их решение

"Анализ занимает 20 минут" — увеличь memory для Java процесса. В docker-compose добавь:

environment:
  _JAVA_OPTIONS: "-Xmx2g"

"Не видит файлы конфигов" — проверь sonar.sources в sonar-project.properties. Часто забывают про папки типа config/.

"Quality Gate падает, но я не знаю, что исправить" — смотри в SonarQube UI → Issues. Там видишь каждое нарушение с описанием и примером кода.

"Интеграция с GitLab не работает" — убедись, что у пользователя SonarQube есть права на проект в GitLab, и токен сгенерирован с правами api.

Итоговая чеклист

Если решил внедрять SonarQube:

• Установи SonarQube (Docker, облако или на сервер)
• Создай токен и настрой сканер локально
• Напиши sonar-project.properties под свой проект
• Настрой интеграцию в CI/CD (GitLab CI или GitHub Actions)
• Создай свой Quality Profile с правилами, адекватными твоему проекту
• Запусти первый анализ и посмотри результаты
• Ослабь/ужесточь правила в зависимости от того, что видишь

Помни, что SonarQube — это средство, а не цель. Цель — улучшить качество кода. Если инструмент мешает работе, правила слишком строгие, разработчики игнорируют результаты — переделай конфиг.

Если хочешь бы