目录

• 前言
• 1. 环境准备
  • 1.1 操作系统要求
  • 1.2 Java 环境安装与配置
    • 1.2.1、检查电脑是否已有 Java
    • 1.2.2、安装 JDK 21
    • 1.2.3、配置与使用（可选方案）
• 2. 下载 SonarQube
• 3. 启动 SonarQube
  • 3.1 打开 SonarQube 的安装目录
  • 3.2 启动 SonarQube
  • 3.3 等待服务启动完成
  • 3.4 访问 SonarQube 页面
  • 启动失败的处理方法
    • 1. 检查 JDK 是否安装正确
    • 2. 检查 SonarQube 路径
    • 3. 处理端口占用问题
• 4. SonarQube汉化
• 5. SonarScanner 下载与配置
  • 安装步骤如下
• 6、创建本地项目并执行代码扫描
  • 6.1 登录 SonarQube 并创建项目
  • 6.2 生成 Token
  • 6.3 配置项目并扫描文件
    • 6.3.1 创建配置文件步骤
    • 6.3.2 如果同时比较 AI 版本和手写版本
    • 6.3.3 容易出错的地方
• 7. 常见问题与故障排除

摘要： 本教程详细讲解在 Windows 系统上安装和配置 SonarQube 代码质量管理平台的完整流程。内容涵盖环境准备、软件下载、数据库配置、服务部署、Web访问、中文语言包安装以及项目扫描配置。

前言

SonarQube 是一个开源的代码质量管理平台，用于持续分析和测量代码质量。通过静态代码分析，它可以检测代码中的错误、漏洞、代码异味以及重复代码，并支持多种编程语言。本教程将详细介绍在 Windows 操作系统上安装和配置 SonarQube 的完整步骤。

1. 环境准备

在开始安装 SonarQube 之前，请确保您的 Windows 系统满足以下先决条件。特别注意：SonarQube 对运行环境（尤其是 Java 版本）有严格的要求，版本不匹配将导致服务无法启动。

1.1 操作系统要求

• 操作系统: Windows 10 或 Windows Server 2016 及以上版本（64 位系统）。

1.2 Java 环境安装与配置

SonarQube 服务端必须运行在指定的 Java 版本上，不同版本的 SonarQube 对 Java 的要求不同。

重要提示：请访问 SonarQube 官方文档 - 要求页面 以获取下载具体版本的最新、最准确的 Java 版本要求。使用不支持的 Java 版本是导致启动失败的最常见原因。

1.2.1、检查电脑是否已有 Java

在安装新 Java 之前，建议先检查系统当前 Java 环境，避免冲突。

1. 打开 PowerShell（以管理员或普通用户身份均可）。

2. 依次执行以下命令：

   java -version
   javac -version
   where java
   

3. 根据命令输出结果，判断当前 Java 环境状态：

   • 情况一：显示 Java 21 或 Java 25，并且 javac -version 也正常
     说明系统已安装符合 SonarQube ZIP 方式启动要求的 JDK。可以直接使用现有 Java，不需要重新安装。

   • 情况二：显示 Java 8、Java 11 或 Java 17
     说明系统已安装旧版本 JDK。不建议卸载原来的 Java，以免影响其他依赖旧版本的项目。可以直接安装 JDK 21，让新旧版本共存。

   • 情况三：java 命令能运行，但 javac 命令不能运行
     说明可能只安装了 JRE（Java 运行时环境）或者环境变量配置不完整。建议安装完整的 JDK 21。

   • 情况四：提示“找不到 java”
     说明系统没有配置任何 Java 环境。需要安装 JDK 21。

课堂统一建议：SonarQube ZIP 方式启动要求 JDK 21 或 25。为了课堂环境统一，避免版本兼容性问题，建议所有同学统一使用 JDK 21。

1.2.2、安装 JDK 21

1. 下载 JDK 21
   • 点击 JDK21下载 。
2. 安装 JDK 21

   • 双击下载的 .msi 安装包。

   • 下面步骤保持默认即可

     
     
     
     

   • 自定义安装，默认安装在C盘，如果自行修改位置请注意：路径最好不要用中文、特殊符号，尽量简单。eg: D:\Java\jdk-21。

   • 

选项	作用	建议设置
修改 PATH	让命令行能直接用 java / javac	勾选
Associate .jar	双击 .jar 文件用 Java 打开	可选
设置 JAVA_HOME	给开发工具指定 JDK 路径	勾选
JavaSoft registry keys	让部分软件通过注册表找到 Java	勾选

PS: 如果电脑上已有项目依赖旧 Java，先不要勾选 PATH 和 JAVA_HOME ，请自行查找相应解决方法。

• 进行安装

3. 验证安装
   • 安装完成后，重新打开一个 PowerShell 窗口（以使新的环境变量生效）。
   • 执行以下命令验证：

    java -version
    javac -version
    ```
   *   正常情况下，应看到类似 `openjdk version "21.0.11"` 的输出，确认版本为 21。
   

1.2.3、配置与使用（可选方案）

方案一：配置全局 JAVA_HOME（推荐长期使用）
如果希望 JDK 21 成为系统默认的 Java，请配置 JAVA_HOME 环境变量：

1. 右键点击“此电脑” -> “属性” -> “高级系统设置” -> “环境变量”。
2. 在“系统变量”区域，点击“新建”。
   • 变量名: JAVA_HOME
   • 变量值: 您的 JDK 21 安装路径（例如：C:\Program Files\Eclipse Adoptium\jdk-21.0.11.10-hotspot）。
3. 在“系统变量”中找到 Path 变量，双击编辑，在变量值的最前面添加 %JAVA_HOME%\bin;。
4. 点击“确定”保存所有更改，并重新打开 PowerShell 验证 java -version。

方案二：临时指定 JDK 21（不影响其他项目）
如果电脑上已有旧版本 Java（如 Java 8/11/17），且不想修改全局环境影响其他课程或项目，可以在启动 SonarQube 的 PowerShell 窗口中临时指定 JDK 21：

# 临时设置 JAVA_HOME 为 JDK 21 的安装路径
$env:JAVA_HOME="C:\Program Files\Eclipse Adoptium\jdk-21.0.11.10-hotspot"
# 将 JDK 21 的 bin 目录临时添加到 PATH 环境变量最前面
$env:Path="$env:JAVA_HOME\bin;$env:Path"
# 验证当前窗口的 Java 版本
java -version

执行上述命令后，当前 PowerShell 窗口将使用 JDK 21。只要 java -version 显示为 21，即可在此窗口中继续启动 SonarQube。关闭窗口后，设置失效，系统会恢复原来的 Java 环境。

2. 下载 SonarQube

1. 点击 SonarQube 访问 SonarQube 的官方下载页面，选择如图所示版本。
   

2. 将下载的 ZIP 文件解压到一个合适的目录，例如 C:\sonarqube。注意：解压路径不要包含中文或空格。

3. 解压完成后，大致如图所示
   

3. 启动 SonarQube

SonarQube 可以直接通过批处理文件启动，不需要手动输入命令。请按照以下步骤操作。

3.1 打开 SonarQube 的安装目录

如果 SonarQube 解压在 D 盘，请进入：

D:\sonarqube-26.6.0.123539\bin\windows-x86-64

如果 SonarQube 解压在 C 盘，请进入：

C:\sonarqube-26.6.0.123539\bin\windows-x86-64

3.2 启动 SonarQube

在该目录下找到：

StartSonar.bat

双击运行该文件。

注意：双击后会弹出一个黑色命令行窗口，如图所示，这是 SonarQube 的运行窗口。服务运行期间请不要关闭该窗口，否则 SonarQube 会停止运行。

3.3 等待服务启动完成

第一次启动通常需要 1 到 3 分钟。启动过程中窗口会不断输出运行日志。

当窗口中出现类似下面的信息时，表示 SonarQube 已成功启动：

SonarQube is operational

3.4 访问 SonarQube 页面

打开浏览器，访问：

http://localhost:9000

默认登录账号为：

• 用户名：admin
• 密码：admin

首次登录后，系统会要求修改默认密码。请按页面提示设置新密码，并妥善保存。

一切完成后将会进入下面界面：

启动失败的处理方法

如果双击 StartSonar.bat 后窗口一闪而过，通常表示启动失败。常见原因是 Java 环境不正确、端口被占用，或 SonarQube 解压路径不合适。

可以按以下方式排查：

1. 检查 JDK 是否安装正确

确认电脑中已经安装 JDK 21，并且存在类似目录：

C:\Program Files\Eclipse Adoptium\jdk-21.0.11.10-hotspot

2. 检查 SonarQube 路径

建议 SonarQube 解压到以下目录之一：

D:\sonarqube-26.6.0.123539

或：

C:\sonarqube-26.6.0.123539

不要放在中文目录、OneDrive 同步目录、网络盘，或以数字开头的目录中。

3. 处理端口占用问题

如果 SonarQube 已经启动，但浏览器无法打开：

http://localhost:9000

可能是 9000 端口被占用。

打开配置文件：

D:\sonarqube-26.6.0.123539\conf\sonar.properties

如果安装在 C 盘，则打开：

C:\sonarqube-26.6.0.123539\conf\sonar.properties

找到：

#sonar.web.port=9000

修改为：

sonar.web.port=9001

注意去掉前面的 #。

保存文件后，重新双击运行 StartSonar.bat，然后在浏览器中访问：

http://localhost:9001

4. SonarQube汉化

1. 下载汉化包
2. 将该 .jar 文件复制到 SonarQube 插件目录。

如果 SonarQube 解压在 D 盘，复制到：

  D:\sonarqube-26.6.0.123539\extensions\plugins

如果 SonarQube 解压在 C 盘，复制到：

  C:\sonarqube-26.6.0.123539\extensions\plugins

再重新启动即可

5. SonarScanner 下载与配置

SonarScanner 是本课程进行代码扫描必须使用的工具。

安装步骤如下

1. 下载压缩包：

   • 官方下载页面
   • Windowsx64 直接下载地址：sonar-scanner-cli-8.0.1.6346-windows-x64.zip安装包

2. 解压到固定目录：

   • 推荐解压到：D:\sonar-scanner-8.0.1.6346
   • 如果没有 D 盘，也可以解压到：C:\sonar-scanner-8.0.1.6346
   • 解压后应能看到：D:\sonar-scanner-8.0.1.6346\bin\sonar-scanner.bat
     

3. 配置环境变量：

   • 右键“此电脑” → 属性 → 高级系统设置 → 环境变量
   • 在“用户变量”中找到 Path，点击“编辑”，新增：
     • D:\sonar-scanner-8.0.1.6346\bin（如果安装在 D 盘）
     • C:\sonar-scanner-8.0.1.6346\bin（如果安装在 C 盘）
       具体请依据自身安装路径

4. 验证安装：

   • 重新打开 PowerShell 或 CMD，输入：

     sonar-scanner.bat -h
     

   • 如果出现类似内容：

     usage: sonar-scanner [options]
     

     说明 SonarScanner 配置成功。
     

   • 如果提示：sonar-scanner.bat 不是内部或外部命令，通常是以下原因：

     • Path 没配置；
     • 配置后没有重新打开 PowerShell；
     • 路径写错；
     • 解压目录层级不对。
     • 请确认实际文件路径中存在：bin\sonar-scanner.bat

6、创建本地项目并执行代码扫描

完成 SonarQube 和 SonarScanner 安装后，需要先在 SonarQube 中创建本地项目，然后使用 SonarScanner 扫描代码。

6.1 登录 SonarQube 并创建项目

1. 启动 SonarQube 并访问：

   • 确保 SonarQube 服务已启动（参考第 3 节）
   • 在浏览器中访问：http://localhost:9000
   • 如果前面修改过端口（如 9001），则访问：http://localhost:9001

2. 使用管理员账号登录：

   • 默认账号：
     • 用户名：admin
     • 密码：admin
   • 如果已经修改过密码，请使用新密码登录

3. 创建本地项目：

   • 登录后，点击页面上的 “Create a local project”（创建本地项目）
   • 中文版界面中可能显示为：“创建本地项目”

4. 填写项目信息：

   • 创建项目时，需要填写项目名称和项目标识，主分支名称默认为main即可；第二步遵循默认配置即可

   • 示例 1：分析 AI 生成代码时可以填写：

     • Project display name: order-calculator-ai
     • Project key: order-calculator-ai
       
       

   • 示例 2：分析学生手写代码时可以填写：

     • Project display name: order-calculator-manual
     • Project key: order-calculator-manual

   • 重要提示：Project key 是项目的唯一标识。AI 版本和手写版本应创建为两个不同项目，不能使用同一个 Project key，否则后一次扫描会覆盖前一次扫描结果

6.2 生成 Token

项目创建完成后，页面会引导生成 Token：

1. 选择本地分析方式：

   • 选择 “Locally”（本地）
   • 中文版显示为：“本地”
     

2. 生成并保存 Token：

   • Token 名称可以填写：student-token 或 sonar-local-token
   • 点击生成后，立即复制 Token
   • 重要提醒：Token 只显示一次，请临时保存，不要上传到代码仓库，也不要放入实验报告截图中
   • 如果忘记保存，可以重新生成一个新的 Token

6.3 配置项目并扫描文件

在待分析代码的根目录中需要创建 sonar-project.properties 配置文件。本课程建议按以下步骤操作：

6.3.1 创建配置文件步骤

1. 新建项目文件夹：

   • 在合适的位置（如 D 盘）新建一个文件夹，例如：

     D:\code\single-python-ai
     

2. 放入要扫描的代码文件：

   • 将要扫描的 Python 文件放入该文件夹，例如：

     D:\code\single-cpp-ai\order_calculator.py
     

3. 创建配置文件：

   • 在同一个文件夹中右键 → 新建 → 文本文档
   • 将文件名改为：sonar-project.properties
   • 注意：如果 Windows 提示"更改文件扩展名可能导致文件不可用"，请选择"是"确认
   • 如果看不到 .txt 后缀，需要先在文件资源管理器中勾选：
     • 点击"查看"选项卡
     • 勾选"显示" → “文件扩展名”
   • 确保最终文件不是：sonar-project.properties.txt

4. 编辑配置文件内容：

   • 右键 sonar-project.properties 文件 → 选择"记事本"或其它文本编辑器打开
   • 根据项目类型【前面创建的项目名称】，复制并修改相应的配置内容，具体内容如下
   • sonar-project.properties 内容如下：

sonar.projectKey=order-calculator-ai
sonar.projectName=order-calculator-ai
sonar.sources=order_calculator.py
sonar.sourceEncoding=UTF-8

含义说明：

• sonar.projectKey=order-calculator-ai：表示 SonarQube 中对应项目的唯一标识，必须和网页里创建项目时填写的 Project key 一致。
• sonar.projectName=order-calculator-ai：表示项目显示名称，依据前面的设置正常和 projectKey 一样。
• sonar.sources=order_calculator.py：表示只扫描当前目录下的这个 Cpp文件。
• sonar.sourceEncoding=UTF-8：表示源代码使用 UTF-8 编码，建议统一填写。

5. 执行扫描：
   在该目录中打开 PowerShell：

   cd D:\code\single-python-ai
   

   设置 SonarQube 地址和 Token：

   $env:SONAR_HOST_URL="http://localhost:9000"
   $env:SONAR_TOKEN="这里粘贴你的Token"
   

   如果 SonarQube 使用的是 9001 端口，则改成：

   $env:SONAR_HOST_URL="http://localhost:9001"
   

   执行扫描：

   sonar-scanner.bat
   

   看到 EXECUTION SUCCESS 说明扫描完成。
   

6.3.2 如果同时比较 AI 版本和手写版本

不要把两份代码放在同一个文件夹里一起扫。建议分开：

D:\code\single-python-ai
├─ order_calculator.py
└─ sonar-project.properties

D:\code\single-python-manual
├─ order_calculator.py
└─ sonar-project.properties

AI 版本配置：

sonar.projectKey=single-python-ai
sonar.projectName=single-python-ai
sonar.sources=order_calculator.py
sonar.sourceEncoding=UTF-8

手写版本配置：

sonar.projectKey=single-python-manual
sonar.projectName=single-python-manual
sonar.sources=order_calculator.py
sonar.sourceEncoding=UTF-8

重要：两份代码需要在 SonarQube 网页中分别创建项目，Project key 要分别对应：

• single-python-ai
• single-python-manual

6.3.3 容易出错的地方

最常见错误有这些：

1. 文件名错误：sonar-project.properties.txt - 文件名错了，SonarScanner 读不到。
2. Project key 不匹配：sonar.projectKey=abc 但网页里创建的 Project key 是 abcd，两边不一致。
3. 源路径配置错误：
   • sonar.sources=src 但实际文件没有放在 src 文件夹里。
   • sonar.sources=D:\code\single-python-ai\order_calculator.py 不建议写绝对路径。课堂文档中建议统一写相对路径，例如：sonar.sources=order_calculator.py

提醒：扫描时浏览器不需要一直登录，但 SonarQube 服务必须保持运行，也就是 StartSonar.bat 打开的窗口不能关闭。

7. 常见问题与故障排除

• 启动失败，提示 “WrapperSimpleApp: Unable to locate the class org.sonar.application.App”:
  • 检查 JAVA_HOME 环境变量是否正确设置，并确保路径中没有空格或中文。
  • 尝试使用绝对路径配置 JAVA_HOME。
• 服务启动后无法访问 localhost:9000:
  • 检查防火墙设置，确保 9000 端口已开放。
  • 检查 SonarQube 服务是否真的在运行，查看 logs 目录下的 sonar.log 和 web.log 获取详细错误信息。
• 数据库连接失败:
  • 确认 PostgreSQL 服务已启动。
  • 检查 sonar.properties 中的数据库连接字符串、用户名和密码是否正确。
  • 确认 sonarqube 用户有权限访问 sonarqube 数据库。
• 分析时内存不足:
  • 按照第 4.1 节调整 wrapper.conf 中的 -Xmx 参数，增加最大堆内存。