­

手把手教你用SonarQube+Jenkins搭建–前端項目–代碼質量管理平台 (Window系統)

  • 2020 年 12 月 30 日
  • 筆記

前言

網上教程大多介紹的是Linux系統下SonarQube+Jenkins如何使用，這是因為這兩款軟件一般都是部署在服務器上，而大多數服務器，採用的都是Linux系統。大多數服務器用Linux的原因是：

  • Linux服務器上的許多軟件都是免費的，Window服務器的軟件大多是付費的
  • 基於Linux服務器的解決方案多，Linux是開源白盒的，容易做優化和自定義，開源的解決方案幾乎都是最先基於Unix族系統開發，Windows要麼是二等公民延遲支持，要麼是優化不夠，性能和Unix族有差距。
  • 龐大的生態系統，服務器端的各種軟件都為它而設計，許多優秀的企業開發的軟件，要麼對window沒有做支持，要麼在window上性能有缺失。比如說Hadoop只能在linux上跑, Nginx在window上有損失，NodeJS對Windows支持不完整

考慮到大家使用的是Windows系統，為了能夠讓大家親自實踐一下，跟着這篇教程將SonarQube+Jenkins在本地搭建運行起來，這篇文章講一下在Windows下SonarQube+Jenkins的安裝使用方法。

效果展示

 啟動SonarQube服務器

在Jenkins上運行代碼掃描任務，查看掃描結果

1.SonarQube 用法

1.1 SonarQube是什麼？

SonarQube 是一個代碼質量管理的開源平台，用於持續評測Java源代碼的代碼質量。安裝Sonar 插件可以對包括 JavaScript,TypeScript, C#,C/C++, PHP, SQL,Golang,Groovy等20多種編程語言的代碼質量分析與檢測提供支持。通過插件機制，Sonar 可以集成不同的測試工具，代碼分析工具，以及持續集成工具，比如pmd-cpd、checkstyle、findbugs、Jenkins。對不同的代碼質量檢測插件執行結果進行再加工處理，通過量化的方式度量代碼質量的變化，從而可以方便地對不同編程語言和規模的工程進行代碼質量管理。同時 Sonar 還對大量的持續集成工具提供了接口支持，可以很方便地在持續集成工具中使用 Sonar。

SonarQube的架構如下圖所示：它的工作原理是：sonar掃描任務運行代碼質量檢測工具(例如Checkstyle， FindBugs，PMD 等）分析代碼，將分析結果寫入到與sonar服務器綁定的數據庫，sonar服務器會通過不同語言的插件算法對代碼分析結果進行再加工，最終將代碼分析加工結果以可視化，可度量的方式展示給用戶。

1.2 它是怎樣保障代碼質量的？

它是從 Architecture Design, Coding Rule, Potential Bugs, Duplications, Comments, Unit Tests,Complexity 7個維度檢查代碼質量的。

1.3 為什麼要用它保證代碼質量？

1.3.1 什麼導致了代碼質量下降

  • 持續不斷的代碼變更；
  • 持續不斷的架構演變；
  • 不良的編碼習慣；
  • 項目緊，時間急

1.3.2 如何提高代碼質量

從大的方面說：

  • 良好的編碼規範；
  • 代碼 Review；
  • 代碼 lint 工具；
  • 加入測試（單元測試、回歸測試、覆蓋率測試）；
  • 不斷改進 CQA 方案(CQA: Code Quality Analysis)；

從小的方面來講：

  • 重複的可以合併
  • 零散的可以集中
  • 複雜的可以拆分
  • 沒用的可以刪除

採用它的好處就是：

相比lint工具檢測維度比較全面, 有可視化的友好展示代碼缺陷的界面，結合CI/CD工具，可以不依賴手工檢查，定時清查代碼

1.4 如何搭建代碼質量管理平台？

SonarQube環境要求參見官方文檔,

  • 運行SonarQube需要安裝Java,不同版本的SonarQube依賴的Java安裝包不一樣
  • SonarQube服務器需要至少2GB的RAM才能有效運行，win10查看主機RAM大小的方法是 開始(鼠標右鍵)==>設置==>系統==>關於
  • 需要的磁盤空間量取決於使用SonarQube分析的代碼量

1.4.1下載JDK

SonarQube服務器和掃描器運行時依賴JDK,不同SonarQube版本依賴的JDK版本不一樣，SonarQube V8.5.x服務器依賴的JDK版本是JDK11，SonarQube Scanner -v2.249.3依賴的jdk版本是JDK8~11，為了兼容兩者，要下載JDK11 下載JDK （下載的時候要註冊一個Oracle賬號）

 JDK的安裝比較簡單，選擇JDK的安裝目錄後,一路下一步即可

1.4.2下載SonarQube服務器

下載 SonarQube服務器，一定要下載社區版，其它版本都有試用期，都是收費的，並解壓到軟件安裝目錄。本文是解壓在E:\ProgramFile下。

1.4.3 運行SonarQube服務器

進入到E:\ProgramFile\sonarqube-8.5.1.38104\bin\windows-x86-64下，打開cmd命令窗口，執行

StartSonar

建議將這個路徑添加到系統環境變量或者設置成桌面快捷方式，方便啟動。

看到SonarQube is up字樣，說明SonarQube服務器啟動成功了。

在瀏覽器中打開 //localhost:9000，就可以訪問本地的 SonarQube 

1.4.4 在SonarQube服務器創建檢測項目

點擊創建新項目

填寫項目標識和顯示名

創建分析項目時的登錄憑據

選擇分析的語言和電腦的操作系統，下載掃描器，複製掃描腳本命令

SonarQube需要與SonarScanner配套起來才能完成代碼質量檢測功能。SonarScaner有多種版本，

不依賴任何構建工具，可以獨立使用的是SonarSCanner CLI版，點擊上圖的下載按鈕下載的就是CLI版,  與構建工具結合使用的Sonar掃描器有兩種下載途徑：

1) 可在對應構建工具的應用市場去找 (推薦)，

2) SonarQube官方也提供了下載地址，點擊下載

1.4.5 開始掃描代碼

切換到項目路徑，有兩種掃描命令參數的寫法：

第一種是在控制台窗口下，將參數寫到可執行命令後面

E:\ProgramFile\sonar-scanner-cli-4.5.0.2216-windows\bin\sonar-scanner sonar-scanner.bat -D"sonar.projectKey=sonar-test" -D"sonar.sources=." -D"sonar.host.url=//127.0.0.1:9000" -D"sonar.login=c5c52709e8cde01e9293fd61be6b00539f8a65fa"

建議將掃描器可執行程序路徑 E:\ProgramFile\sonar-scanner-cli-4.5.0.2216-windows\bin 添加到系統環境變量中,每次執行時就不用寫這麼長的路徑了

第二種是在項目下，創建一個sonar-project.properties文件，在裏面配置好參數 (推薦)，就像下面這樣

#項目的唯一標識，必填
sonar.psonar.projectKey=sonar-test-prj
項目名稱
sonar.projectName=sonar-test-prj
項目版本
sonar.projectVersion=1.0
#掃描目錄
sonar.sources=src
#檢測語言
sonar.language=js
#掃描結果上報地址
sonar.host.url=//127.0.0.1:9000
#登錄賬號
sonar.login=admin
sonar.password=xxx
#文件編碼
sonar.sourceEncoding=UTF-8

然後執行 sonar-scanner，就開始檢查項目代碼質量。

1.4.6 查看掃描報告

代碼掃描完成後，打開 //localhost:9000，然後登陸，查看掃描報告。

默認用戶: admin

默認密碼: 用下面的cmd命令查看 

type C:\WINDOWS\system32\config\systemprofile\AppData\Local\Jenkins\.jenkins\secrets\initialAdminPassword

2.Jenkins用法

2.1 Jenkins是什麼?

Jenkins是一個開源的、提供友好操作界面的持續集成(CI)工具，起源於Hudson（Hudson是商用的），主要用於持續、自動的構建/測試軟件項目、監控外部任務。Jenkins是用Java語言編寫，通常與版本管理工具(簡稱SCM,通常是Git,SVN)、構建工具(Maven、Ant、Gradle)結合使用。Jenkins作為CI第一大神器，擁有龐大的1058個擴展插件。你想實現的功能，基本上都能找到相應的擴展插件。

2.2 Jenkins下載安裝使用

2.2.1 下載jenkins ,選擇windows版本

2.2.2 選擇安裝目錄

建議不要放在系統盤，系統盤安裝的軟件多了，會導致機器運行速度下降。這裡我們安裝在E盤。

2.2.3 選擇服務運行賬戶

Jenkins是以系統服務的方式運行的，需要指定服務運行的賬戶，LocalSystem和LocalService都是系統內置賬號，區別是LocalSystem具有最高的權限，LocalService只具有運行服務的最小權限，本文是在本地安裝，所以選擇了LocalSystem賬戶。

2.2.4 設定服務端口

輸入服務端口,建議輸入值大一些，不要與系統的端口衝突。這裡填寫的是60000，輸入完之後，可以點擊一下test port,確認端口可用。

2.2.4 定製安裝

定製安裝這裡，選擇特性需要時再安裝

接下來點擊install，再點擊完成

2.2.5 解鎖Jenkins

第一次訪問新的Jenkins實例時，系統會要求你使用自動生成的密碼對其進行解鎖。
在cmd命令行下用 type 查看密碼 

type C:\WINDOWS\system32\config\systemprofile\AppData\Local\Jenkins\.jenkins\secrets\initialAdminPassword

2.2.6 自定義Jenkins擴展

解鎖 Jenkins之後，在 自定義 Jenkins 頁面內， 可以安裝任何數量的有用插件進行初始化配置。有兩個選項可供選擇:

  • 安裝建議的插件 – 安裝推薦的一組插件，這些插件基於最常見的用例.
  • 選擇要安裝的插件 – 可以定製安裝插件，如果你很清楚自己要用到哪些插件，就選擇定製安裝，否則選擇安裝推薦的插件

這裡需要較長時間，耐心等待插件安裝完畢

可能部分插件會安裝失敗，不用管，因為好些你也用不到，繼續下面的操作。

2.2.7 創建第一個Jenkins管理員賬號

安裝完自定義的Jenkins插件之後，會進入管理員用戶創建頁面。可以創建一個非admin的管理員賬戶，也可以不創建，繼續使用默認的 admin管理員賬戶；

配置 jenkins網頁訪問地址，點擊 保存並完成。可以使用默認地址

2.2.8. 配置完成後自動進入首頁，配置node.exe安裝目錄

前端項目的構建都依賴node.exe,  所以要指定NodeJS的安裝目錄 ,  操作路徑Manage Jenkins ==> Global Tool Configuration

NodeJS版本及路徑查看

 配置node的版本和安裝路徑

2.2.10 配置項目構建任務

1. 打開 Jenkins 首頁，點擊 新建 Item 創建項目。新建一個自由風格的項目

2.選擇 源碼管理 面板 ，輸入你的 git 上的倉庫地址。注意要添加gitee憑證

3.選擇 構建環境 面板，配置執行Node命令使用NodeJS版本

4.選擇 增加構建步驟 面板，windows 要選 execute windows batch command 輸入

npm i && npm run build && xcopy .\build\* E:\server\dist\ /s/e/y 
rem 這行命令的作用是安裝依賴，構建項目，並將構建後的靜態資源複製到指定目錄 E:\server\dist\; 。這個目錄是靜態服務器資源目錄。

5. 保存後，返回首頁。點擊項目旁邊的小三角，選擇 build now 。就完成了項目的構建部署

3 將SonarQube+Gitee集成到Jenkins

3.1 添加Jenkins訪問Gitee的憑證

3.1.1 在 Gitee 中生成 Personal access tokens，設置 token 相關權限

3.1.2 在Jenkins的插件管理==>可選插件下,搜索Gitee安裝

3.1.3  在IJenkins中 配置 訪問Gitee Server的憑證

在 「manage jenkins」 ==> 「configure system」 中找到 Gitee，然後在 Credentials 處添加全局憑據，類型選 Secret text，Secret 處輸入上一步生成的 access token

3.2 安裝SonarQube Scanner插件，並在Jenkins中指定SonarQube Scanner的安裝目錄

3.2.1 在 Jenkins 的插件管理中安裝 SonarQube Scanner 插件

3.2.2 在 插件管理==>全局工具配置中指定Sonar掃描器的安裝路徑

Manage Jenkins ==> Global Tool Configuration

3.3 添加Jenkins訪問SonarQube Server的憑證

3.3.1 在SonarQube Server中生成token

登錄 SonarQube 後，在 「我的賬號」 ==> 「安全」 中生成 token，注意生成的令牌不會再顯示第二次，要立即複製

3.3.2 在Jenkins下添加 Jenkins訪問SonarQube Sever的憑證

在 「Manage Jenkins」 ==> 「Configure System」 中找到 SonarQube servers
Name ：隨意；
Server URL ：為啟動的 SonarQube 服務地址，這裡使用本地啟動的默認地址 //localhost:9000 ；
Server authentication token ： 輸入之前生成的 token

3.4 創建構建任務

3.4.1 在General下輸入任務描述

3.4.2 在源碼管理面板下，配置要檢測的項目代碼

3.4.3 在構建面板下

3.4.3.1 配置sonar掃描參數

sonar.projectKey=sonar-test--react-visual-editor
sonar.projectName=react-visual-editor
sonar.projectVersion=1.0
sonar.sources=packages
sonar.language=js,ts
sonar.eslint.eslintconfigpath=.eslintrc
sonar.eslint.ruleconfigs=.eslintrc
sonar.sourceEncoding=UTF-8
sonar.exclusions=**/__test__/**,**/demo/**,**/*.bak.*,**/*.bak

要應用eslint規則的話，需要下載一個插件sonar-eslint-plugin-0.4.0，放置在SonarQube安裝目錄下的 extension==>plugins 目錄下。
下載地址：sonar-eslint-plugin-0.4.0.jar

3.4.3.2 配置sonar掃描未通過的執行邏輯

所有指標通過是返回：

{"measures":[{"metric":"alert_status","value":"OK","component":"sonar-test--wx-minipro-ci"}]}

沒有通過時返回：

{"measures":[{"metric":"alert_status","value":"ERROR","component":"sonar-test--wx-minipro-ci"}]}

據此，SonarQube檢測是否通過的判斷條件可以寫成：

@echo off
curl -sb -H "Accept: application/json" "//localhost:9000/api/measures/search?projectKeys=sonar-test--react-visual-editor&metricKeys=alert_status" | findstr "OK"
set err=%errorlevel%
if "%err%"=="0" (
echo "sonarQube代碼質量檢測通過"
) else (
echo "sonarQube代碼質量檢測未通過"
exit
)

3.4.4 點擊Build Now, 構建完成後，就能看到代碼掃描結果

3.4.5 每次提交代碼，自動檢測代碼質量配置

3.4.5.1 在Jenkins上配置 Gitee WebHook觸發構建

3.4.5.2 Gitee WebHook配置

將Jenkins中生成的webhook通知地址，webhook密碼，填寫到gitee中的webhook對應配置項中

我沒有公網IP，域名，所以沒法演示。就不演示配置後的效果呢。

4 避坑指南

1.原因是SonarQube 7.9以上版本已不再支持mysql，我使用的是最新的8.5.x版本

2. 遠程主機強迫關閉了一個現有的連接

沒有正常退出，Ctrl+Shift+Delete 在任務管理器中結束掉JVM進程

3.配置sonar-scanner環境變量寫法不正確

正確寫法：

"C:\Program Files\Common Files\Oracle\Java\javapath";E:\ProgramFile\sonar-scanner-cli-4.5.0.2216-windows\bin;

錯誤寫法：

"C:\Program Files\Common Files\Oracle\Java\javapath;E:\ProgramFile\sonar-scanner-cli-4.5.0.2216-windows\bin;";

4.執行sonar-scanner報錯

Caused by: You must define the following mandatory properties for 'Unknown'; sonar.projectKey

解決方案：修改掃描項目下的 sonar-project.properties 文件

# 添加必要字段
sonar.projectKey=xxx（項目的唯一標識）

5.正在配置一個構建任務時，重新登錄配置另外一個構建任務，導致當然任務的配置丟失。推薦採用Ctrl+L,Alt+Enter打開一個新的頁簽，配置另外一個任務。

6 卸載Jenkins時，要手動把Jenkins的工作空間也一併卸載掉，目錄是C:\Windows\System32\config\systemprofile\AppData\Local\Jenkins
否則前次的賬號配置信息仍舊在，重裝之後依舊不能使用。

7 如果遇到有些必須的插件安裝失敗時，重啟Jenkins服務，可能就會安裝成功。

參考文章：

[1] SonarQube 搭建代碼質量管理平台

[2] 前端項目自動化部署——超詳細教程（Jenkins、Github Actions）

[3] 部署SonarQube代碼檢測服務以及jenkins實現代碼自動測試、自動部署

[4] windows中jenkins關聯gitLab進行vue項目自動部署打包

[5] SonarQube手冊

VirMach 便宜 VPS

QNews

QNews