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

孤舟蓑翁發表於2020-12-30
Jenkins前端

前言

網上教程大多介紹的是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伺服器啟動成功了。

在瀏覽器中開啟 http://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=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，就開始檢查專案程式碼質量。

1.4.6 檢視掃描報告

程式碼掃描完成後，開啟 http://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 服務地址，這裡使用本地啟動的預設地址 http://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" "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
)

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手冊

相關文章