手把手教你用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伺服器手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

在Jenkins上執行程式碼掃描任務,檢視掃描結果

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

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伺服器會通過不同語言的外掛演算法對程式碼分析結果進行再加工,最終將程式碼分析加工結果以視覺化,可度量的方式展示給使用者。

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

1.2 它是怎樣保障程式碼質量的?

它是從 Architecture Design, Coding Rule, Potential Bugs, Duplications, Comments, Unit Tests,Complexity 7個維度檢查程式碼質量的。
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

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+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)
  • 需要的磁碟空間量取決於使用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賬號)

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

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

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

1.4.2下載SonarQube伺服器

下載 SonarQube伺服器,一定要下載社群版,其它版本都有試用期,都是收費的,並解壓到軟體安裝目錄。本文是解壓在E:\ProgramFile下。
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

1.4.3 執行SonarQube伺服器

進入到E:\ProgramFile\sonarqube-8.5.1.38104\bin\windows-x86-64下,開啟cmd命令視窗,執行

StartSonar

建議將這個路徑新增到系統環境變數或者設定成桌面快捷方式,方便啟動。

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

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

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

在瀏覽器中開啟 http://localhost:9000,就可以訪問本地的 SonarQube 
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

1.4.4 在SonarQube伺服器建立檢測專案

點選建立新專案
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)
填寫專案標識和顯示名
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)
建立分析專案時的登入憑據
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)
選擇分析的語言和電腦的作業系統,下載掃描器,複製掃描指令碼命令
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)
SonarQube需要與SonarScanner配套起來才能完成程式碼質量檢測功能。SonarScaner有多種版本,
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

不依賴任何構建工具,可以獨立使用的是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=http://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=http://127.0.0.1:9000
#登入賬號
sonar.login=admin
sonar.password=xxx
#檔案編碼 sonar.sourceEncoding=UTF-8

然後執行 sonar-scanner,就開始檢查專案程式碼質量。

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

1.4.6 檢視掃描報告

程式碼掃描完成後,開啟 http://localhost:9000,然後登陸,檢視掃描報告。

預設使用者: admin

預設密碼: 用下面的cmd命令檢視 

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

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

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版本

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

2.2.2 選擇安裝目錄

建議不要放在系統盤,系統盤安裝的軟體多了,會導致機器執行速度下降。這裡我們安裝在E盤。
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

2.2.3 選擇服務執行賬戶

Jenkins是以系統服務的方式執行的,需要指定服務執行的賬戶,LocalSystem和LocalService都是系統內建賬號,區別是LocalSystem具有最高的許可權,LocalService只具有執行服務的最小許可權,本文是在本地安裝,所以選擇了LocalSystem賬戶。
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

2.2.4 設定服務埠

輸入服務埠,建議輸入值大一些,不要與系統的埠衝突。這裡填寫的是60000,輸入完之後,可以點選一下test port,確認埠可用。
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

2.2.4 定製安裝

定製安裝這裡,選擇特性需要時再安裝
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

接下來點選install,再點選完成
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

2.2.5 解鎖Jenkins

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

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

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

2.2.6 自定義Jenkins擴充套件

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

  • 安裝建議的外掛 - 安裝推薦的一組外掛,這些外掛基於最常見的用例.
  • 選擇要安裝的外掛 - 可以定製安裝外掛,如果你很清楚自己要用到哪些外掛,就選擇定製安裝,否則選擇安裝推薦的外掛
    手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

這裡需要較長時間,耐心等待外掛安裝完畢
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

可能部分外掛會安裝失敗,不用管,因為好些你也用不到,繼續下面的操作。
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

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

安裝完自定義的Jenkins外掛之後,會進入管理員使用者建立頁面。可以建立一個非admin的管理員賬戶,也可以不建立,繼續使用預設的 admin管理員賬戶;
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

配置 jenkins網頁訪問地址,點選 儲存並完成。可以使用預設地址
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

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

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

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

NodeJS版本及路徑檢視

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

 配置node的版本和安裝路徑

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

2.2.10 配置專案構建任務

1. 開啟 Jenkins 首頁,點選 新建 Item 建立專案。新建一個自由風格的專案
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

2.選擇 原始碼管理 皮膚 ,輸入你的 git 上的倉庫地址。注意要新增gitee憑證
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

3.選擇 構建環境 皮膚,配置執行Node命令使用NodeJS版本

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

4.選擇 增加構建步驟 皮膚,windows 要選 execute windows batch command 輸入
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

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

5. 儲存後,返回首頁。點選專案旁邊的小三角,選擇 build now 。就完成了專案的構建部署
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

3 將SonarQube+Gitee整合到Jenkins

3.1 新增Jenkins訪問Gitee的憑證

3.1.1 在 Gitee 中生成 Personal access tokens,設定 token 相關許可權

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

3.1.2 在Jenkins的外掛管理==>可選外掛下,搜尋Gitee安裝

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

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

在 “manage jenkins” ==> “configure system” 中找到 Gitee,然後在 Credentials 處新增全域性憑據,型別選 Secret text,Secret 處輸入上一步生成的 access token
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

3.2 安裝SonarQube Scanner外掛,並在Jenkins中指定SonarQube Scanner的安裝目錄

3.2.1 在 Jenkins 的外掛管理中安裝 SonarQube Scanner 外掛

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

3.2.2 在 外掛管理==>全域性工具配置中指定Sonar掃描器的安裝路徑

Manage Jenkins ==> Global Tool Configuration
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

3.3 新增Jenkins訪問SonarQube Server的憑證

3.3.1 在SonarQube Server中生成token

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

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

3.3.2 在Jenkins下新增 Jenkins訪問SonarQube Sever的憑證

在 “Manage Jenkins” ==> “Configure System” 中找到 SonarQube servers
Name :隨意;
Server URL :為啟動的 SonarQube 服務地址,這裡使用本地啟動的預設地址 http://localhost:9000 ;
Server authentication token : 輸入之前生成的 token
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

3.4 建立構建任務

3.4.1 在General下輸入任務描述

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

3.4.2 在原始碼管理皮膚下,配置要檢測的專案程式碼手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

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

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

要應用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" "http://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
)

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

3.4.4 點選Build Now, 構建完成後,就能看到程式碼掃描結果

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

3.4.5 每次提交程式碼,自動檢測程式碼質量配置

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

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

3.4.5.2 Gitee WebHook配置

將Jenkins中生成的webhook通知地址,webhook密碼,填寫到gitee中的webhook對應配置項中
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

我沒有公網IP,域名,所以沒法演示。就不演示配置後的效果呢。
手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

4 避坑指南

1.原因是SonarQube 7.9以上版本已不再支援mysql,我使用的是最新的8.5.x版本手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

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

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

沒有正常退出,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;";

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

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開啟一個新的頁籤,配置另外一個任務。

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

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

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

手把手教你用SonarQube+Jenkins搭建--前端專案--程式碼質量管理平臺 (Window系統)

參考文章:

[1] SonarQube 搭建程式碼質量管理平臺

[2] 前端專案自動化部署——超詳細教程(Jenkins、Github Actions)

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

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

[5] SonarQube手冊

相關文章