SonarQube使用教程（Docker安装）

一、SonarQube介绍：

面向多语言的代码质量与安全静态分析平台

1、组成：

① sonarQube：web界面管理平台

1）展示所有的项目代码的质量数据。

2）配置质量规则、管理项目、配置通知、配置SCM等。

② sonarScanner：代码扫描工具

1）专门用来扫描和分析项目代码，支持20+语言。

2）代码扫描和分析完成之后，会将扫描结果存储到数据库当中，在sonarQube平台看到扫描的数据。

2、优势：

① 检测维度全：

基于代码编写规范与安全规范双重规则集，自动识别安全漏洞、代码异味、重复代码、圈复杂度及测试覆盖率缺口

② 工程集成：

无缝对接 IDE、SCM（Git/SVN） 及 CI/CD 流水线，自动定位问题代码与具体提交人。

③ 持续赋能：

通过量化质量门禁与增量分析，驱动团队持续交付更干净、更安全的代码。

二、SonarQube下载：

官网：https://www.sonarsource.com/products/sonarqube/downloads/

1、安装要求：

① 软件环境硬性要求：JDK 版本（分界线很关键）

• SonarQube 8.9 LTS：仅支持 JDK11
• SonarQube 9.9 LTS：支持 JDK11 / JDK17（推荐 JDK17）
• SonarQube 10.x+：强制 OpenJDK 17，不再兼容 JDK11

② 数据库（重点避坑）：

• 内置 H2 数据库：仅用于测试、本地临时使用，生产严禁使用
• 正式生产仅支持：PostgreSQL 12~16
• 支持 MySQL 的 SonarQube 版本（7.8 及更早）需要较旧的 Java 版本（通常是 Java 8 或 11）

③ 端口与权限要求：

• 默认 Web 端口：9000，需放行防火墙
• 禁止管理员（root 用户）启动 SonarQube，必须新建普通用户运行。 Docker 默认容器内部进程不是 root 用户，容器内置了普通账号，因此不用手动新建用户。

④ 附属依赖：

• 如需对接 CI/ESLint：Node.js 14~20
• Docker 部署：Docker Engine ≥20.10

2、安装软件：

① 查看 docker 版本是否符合要求

docker 安装教程：暂时占位

运行 Docker Desktop，并且开启 WSL2：

• 按下 Ctrl+Shift+Esc ：打开任务管理器 → 性能 → CPU
• 右下角查看：虚拟化：已启用 ✅

② 创建目录：

必须使用 Docker 命名卷（named volumes），不能用 bind mounts。

我没有放在C盘，都放在D盘了，可以根据要求选择数据存放位置。

（1） mkdir D:\sonarqube\postgres_data

• 对应容器路径： /var/lib/postgresql/data
• 存什么：
  • PostgreSQL 的全部数据库文件
  • SonarQube 的用户账号、项目配置、分析结果、权限设置、插件市场元数据等
• 能不能删：
  • 删了等于数据库清空，SonarQube 所有配置和扫描记录都没了

（2） mkdir D:\sonarqube\sonarqube_data

• 对应容器路径： /opt/sonarqube/data
• 存什么：
  • SonarQube 内置 Elasticsearch 的索引数据
  • 项目分析结果的搜索索引
  • 缓存、临时计算数据等
• 能不能删：
  • 可以删，但删了要重建索引，启动会变慢，首次登录后项目搜索可能暂时不可用。
  • 一般只在索引损坏、升级异常或清理空间时才删。

（3） mkdir D:\sonarqube\sonarqube_extensions

• 对应容器路径： /opt/sonarqube/extensions
• 存什么：
  • 你自己安装的插件（比如汉化包、语言插件）
  • 上传的自定义规则、质量配置等
• 能不能删：
  • 别随便删。删了插件就没了，SonarQube 可能缺少必要的语言支持或功能。
  • 如果因为插件导致启动失败，可以进这个目录的 plugins 子目录删掉问题插件。

（4） mkdir D:\sonarqube\sonarqube_logs

• 对应容器路径： /opt/sonarqube/logs
• 存什么：
  • SonarQube 的运行日志
  • 包括 sonar.log、web.log、es.log、ce.log 等
  • 出问题排查时主要靠这些日志
• 能不能删：
  • 可以删。日志文件删了会自动重新生成。
  • 但建议先压缩备份，方便后续排查历史问题。

③ 创建 docker-compose.yml：

在任意路径下新建文件（我放在D:\sonarqube下了），写入以下代码：

version: "3.8"

services:
  sonarqube:
    image: sonarqube:community
    container_name: sonarqube
    depends_on:
      - postgres
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://postgres:5432/sonar
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: sonar123
    ports:
      - "9000:9000"
    volumes:
      - D:\sonarqube\sonarqube_data:/opt/sonarqube/data
      - D:\sonarqube\sonarqube_extensions:/opt/sonarqube/extensions
      - D:\sonarqube\sonarqube_logs:/opt/sonarqube/logs
    restart: unless-stopped

  postgres:
    image: postgres:15
    container_name: sonarqube_postgres
    environment:
      POSTGRES_USER: sonar
      POSTGRES_PASSWORD: sonar123
      POSTGRES_DB: sonar
    ports:
       - "5432:5432"
    volumes:
      - D:\sonarqube\postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

Windows 上 Docker Desktop 默认会把 C 盘共享给容器，但D 盘可能默认没有共享，需要手动开启。

设置方法：

• 打开 Docker Desktop
• 点击右上角齿轮图标 → Resources → File sharing
• 把 D:\ 或 D:\sonarqube 加到共享列表里
• 点击 Apply，然后重启Docker
  

③ 下载 SonarQube和数据库

cd D:\sonarqube
docker compose up -d

• 检查状态如图就是安装成功

docker ps -a

④ 访问：

http://localhost:9000

账号：admin

密码：admin

3、创建项目：

• SonarQube 页面点击顶部 项目
• 点击 创建项目
• 选择 手动创建
  

三、汉化：

• 下载汉化插件之后重启当前的服务
  
  Install Pending 卡住，网页端触发重启失败，直接用命令强制重启即可解决。

cd D:\sonarqube
docker compose restart sonarqube

四、查看 PostgreSQL 的图形化工具：

下载链接：https://www.pgadmin.org/download/

1、安装：

一路Next安装即可，最后在开始菜单中找到软件打开

2、新建并连接数据库：

一定要在docker中启动数据库，才能连接！

3、创建角色：

直接用默认的超级管理员权限用户就行，也可以创建一个普通的用户

4、创建数据库：

直接用默认的数据库也行，也可以创建一个新的数据库

五、Sonar-scanner安装：

官网链接：https://docs.sonarsource.com/sonarqube-server/10.8/analyzing-source-code/scanners

1、Docker 安装镜像：

docker pull sonarsource/sonar-scanner-cli

2、验证是否成功：

docker images | findstr sonar-scanner-cli

六、扫描代码：

1、拉取源码

2、项目根目录新建配置文件：

文件名固定：sonar-project.properties

① Java 项目版：

• 使用前置
  • 先执行 mvn clean compile 生成 target/classes
  • 需要覆盖率则执行 mvn test jacoco:report

# ====================== 【通用基础配置 前后端通用】 ======================
# SonarQube服务部署地址，修改为你的Sonar地址+端口
sonar.host.url=http://127.0.0.1:9000
# 身份认证Token，Sonar平台个人账号-Security里生成，用于上报扫描结果鉴权
sonar.login=替换为你的Sonar个人访问token
# 项目唯一标识，整个Sonar服务内不能重复，英文/数字/下划线，核心区分不同项目
sonar.projectKey=backend_xx_server
# Sonar网页展示的项目名称，可以中文，方便辨认
sonar.projectName=xx后端服务
# 项目版本号，迭代新版本时可更新，用于追溯不同版本代码质量
sonar.projectVersion=1.0
# 源码编码格式，统一UTF-8，避免中文注释乱码、解析失败
sonar.sourceEncoding=UTF-8
# 指定需要扫描的源码根目录，. 代表当前项目根目录全部扫描
sonar.sources=.

# ====================== 【Java后端专属配置】 ======================
# 限定仅扫描Java语言，关闭多语言识别，提升扫描速度
sonar.language=java
# 编译后的class文件目录(Maven默认路径)，Sonar依靠class做类型推断、精准代码分析，必须编译后再扫描
sonar.java.binaries=target/classes
# 单元测试编译后的class目录，用来区分业务代码与测试代码
sonar.java.test.binaries=target/test-classes
# 指定覆盖率采集工具为Jacoco，适配Java单元测试覆盖率统计
sonar.java.coveragePlugin=jacoco
# Jacoco生成的覆盖率二进制文件路径，Sonar读取后展示单元测试覆盖率
sonar.jacoco.reportPaths=target/jacoco.exec

# ====================== 【过滤配置：不需要扫描的目录/文件】 ======================
# 排除目录规则：xxx/** 代表该文件夹下所有内容全部跳过扫描
# 排除打包产物、测试目录、文档、SQL脚本，减少无效扫描
sonar.exclusions=target/**,test/**,doc/**,sql/**,*.sql
# 白名单：指定哪些目录属于单元测试代码，测试代码不计入业务代码复杂度、重复率统计
sonar.test.inclusions=src/test/**

② React JS/TS 前端版：

• 使用前置
  • 安装依赖：npm install
  • 生成覆盖率文件：npm run test:coverage

# ====================== 【通用基础配置 前后端通用】 ======================
sonar.host.url=http://127.0.0.1:9000
sonar.login=替换为你的Sonar个人访问token
sonar.projectKey=react_admin_web
sonar.projectName=React前端管理系统
sonar.projectVersion=1.0
sonar.sourceEncoding=UTF-8
# 前端业务代码统一放在src目录，只扫描src，避免扫描根目录多余文件
sonar.sources=src

# ====================== 【React前端专属配置】 ======================
# 开启JSX语法解析，Sonar才能识别React标签、组件写法，避免误报语法错误
sonar.javascript.jsx.support=true
# TS+React项目开启，纯JS项目注释此行即可
sonar.typescript.enabled=true
# 自动读取项目根目录的.eslintrc配置，本地eslint和Sonar校验规则完全保持一致
sonar.javascript.eslint.use.eslintrc=true

# ====================== 【过滤配置 前端必配，防止扫描node_modules卡死】 ======================
# 排除依赖包、打包产物、静态资源、配置文件、说明文档，千万不要删掉node_modules/**
sonar.exclusions=node_modules/**,dist/**,build/**,public/**,config/**,*.md
# 标记哪些文件是单元测试代码
sonar.test.inclusions=src/**/*.test.js,src/**/*.test.tsx,src/**/__tests__/**
# Jest/Vitest执行测试后生成的覆盖率文件，Sonar读取展示前端单元测试覆盖率
sonar.javascript.lcov.reportPaths=coverage/lcov.info

③ Vue2/Vue3 前端版：

# ====================== 通用基础配置 ======================
sonar.host.url=http://127.0.0.1:9000
sonar.login=替换为你的Sonar个人访问token
sonar.projectKey=vue_web_system
sonar.projectName=Vue前端管理平台
sonar.projectVersion=1.0
sonar.sourceEncoding=UTF-8
sonar.sources=src

# ====================== Vue专属配置 ======================
# 开启Vue单文件组件解析，识别.vue中的template/script/style
sonar.javascript.vue.support=true
# 复用项目本地eslint配置，统一编码规范
sonar.javascript.eslint.use.eslintrc=true

# ====================== 过滤配置 ======================
sonar.exclusions=node_modules/**,dist/**,build/**,public/**,*.md
# 识别测试代码目录
sonar.test.inclusions=tests/**,src/**/*.spec.js
# 前端覆盖率文件地址
sonar.javascript.lcov.reportPaths=coverage/lcov.info

④ 前后端混合版本：

# 基础连接配置
sonar.host.url=http://127.0.0.1:9000
sonar.login=替换为你的Sonar个人访问token
sonar.projectKey=fullstack_project
sonar.projectName=前后端一体化项目
sonar.projectVersion=1.0
sonar.sourceEncoding=UTF-8
sonar.sources=.

# 删掉 sonar.language=xxx，自动识别Java/JS/Vue/React多语言
# Java编译目录配置
sonar.java.binaries=target/classes
# 同时支持React JSX + Vue解析
sonar.javascript.jsx.support=true
sonar.javascript.vue.support=true
# 读取前端eslint规则
sonar.javascript.eslint.use.eslintrc=true

# 全局统一排除所有无用目录
sonar.exclusions=target/**,node_modules/**,dist/**,build/**,test/**,*.md

# Java覆盖率、前端覆盖率双配置
sonar.jacoco.reportPaths=target/jacoco.exec
sonar.javascript.lcov.reportPaths=coverage/lcov.info

3、新建环境变量文件：.env

SONAR_HOST_URL=http://host.docker.internal:9000
SONAR_TOKEN=sqa_965xxx
SONAR_PROJECT_VERSION=2026.08-01

.gitignore忽略这个环境变量文件

SONAR_TOKEN 在Sonarqube网站中进行创建

4、添加环境变量：

① 切换到.env文件所在的目录（或者将代码中的 .env 换为绝对路径），执行下面的代码：

Get-Content .env | ForEach-Object {
    if ($_ -match '^(.*?)=(.*)$') {
        [System.Environment]::SetEnvironmentVariable($matches[1], $matches[2], 'Process')
    }
}

② 验证环境变量是否设置成功：

$env:SONAR_HOST_URL

$env:SONAR_TOKEN

Tips：更改环境变量文件后需要重新设置

5、上传分析结果

-v "..." ：把你本地的代码目录挂载到容器里的 /usr/src，扫描器会自动读取里面的 `sonar-project.properties`

docker run --rm --env-file ".env绝对路径" -v "被扫描项目的绝对路径:/usr/src" sonarsource/sonar-scanner-cli

6、定制质量配置：

① 点击创建按钮进行规则初始化：

• 创建空质量配置（激活规则就是0）：
  
• 扩展现存质量配置（激活规则就是内置的）：
• 复制现存质量配置（激活规则就是内置的）：同上

② 激活并使用当前配置：

七、Sonarlint 与 IDE 集成：

我用的是VSCode，插件搜索：SonarQube for IDE

1、安装插件：

2、配置插件连接sonarqube：

3、打开源代码文件进行查看：

4、绑定本地的项目同步远程的Sonarqube项目：

为了同步远程的规则集

注意事项：

绑定失败需要删除绑定失败的项目，不然sonarqube无法使用

绑定项目一直显示<project not found>，排查一下Token权限（用户权限）：

检测问题的脚本：

$SQ_URL = "http://localhost:9000"
$TOKEN = "sqa_xxx"
$PROJECT_KEY = "xx-backend"

$auth = "Basic " + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("${TOKEN}:"))

Write-Host "=== 1. Token 有效性 ===" -ForegroundColor Cyan
try {
    $r = Invoke-RestMethod -Uri "$SQ_URL/api/authentication/validate" -Headers @{ Authorization = $auth }
    Write-Host "✅ Token 有效: $($r.valid)" -ForegroundColor Green
} catch { Write-Host "❌ $($_.Exception.Message)" -ForegroundColor Red }

Write-Host "`n=== 2. 可见项目列表 ===" -ForegroundColor Cyan
try {
    $p = Invoke-RestMethod -Uri "$SQ_URL/api/projects/search?ps=500" -Headers @{ Authorization = $auth }
    Write-Host "✅ 可见项目数: $($p.paging.total)" -ForegroundColor Green
    $p.components | ForEach-Object { Write-Host "   $($_.key) | $($_.name)" -ForegroundColor Gray }
} catch { Write-Host "❌ $($_.Exception.Message)" -ForegroundColor Red }

Write-Host "`n=== 3. 指定项目访问 (training-backend) ===" -ForegroundColor Cyan
try {
    $n = Invoke-RestMethod -Uri "$SQ_URL/api/navigation/component?component=$PROJECT_KEY" -Headers @{ Authorization = $auth }
    Write-Host "✅ 项目可访问: $($n.name)" -ForegroundColor Green
} catch {
    $s = $_.Exception.Response.StatusCode.value__
    Write-Host "❌ HTTP $s : $($_.Exception.Message)" -ForegroundColor Red
    switch ($s) {
        401 { Write-Host "   Token 无效" -ForegroundColor Yellow }
        403 { Write-Host "   无项目权限" -ForegroundColor Yellow }
        404 { Write-Host "   项目 Key 不存在" -ForegroundColor Yellow }
    }
}