代碼審查這件事很多團(tuán)隊(duì)都經(jīng)歷過同一條曲線項(xiàng)目立項(xiàng)那陣子每次 Merge Request 下面都有人認(rèn)真寫評論、提改進(jìn)點(diǎn)三五個(gè)月之后評論變成了清一色的LGTM評審就剩一個(gè)形式。不是大家變懶了而是靠人力去守住風(fēng)格統(tǒng)一、空指針、資源未釋放、SQL 注入、硬編碼密鑰這類機(jī)器天生比人敏感的問題本身就撐不住。我這幾年搭過幾套持續(xù)代碼審查鏈路核心思路一直是同一套組合GitLab 管代碼和觸發(fā)Jenkins 管調(diào)度和執(zhí)行SonarQube 管靜態(tài)分析和質(zhì)量門禁。三個(gè)東西各司其職串起來之后代碼一提交就自動(dòng)跑掃描不達(dá)標(biāo)直接卡住合并按鈕。這篇文章我把這套SonarQube Jenkins GitLab的搭建過程完整拆開講一遍包括版本怎么挑、參數(shù)怎么設(shè)、流水線腳本怎么寫以及最值錢的那部分——跑通之后會(huì)遇到的真實(shí)故障怎么排查。適合已經(jīng)用過這三個(gè)工具里至少一個(gè)、準(zhǔn)備把它們組起來的后端或 DevOps 同學(xué)也適合完全沒搭過但想照著復(fù)現(xiàn)的運(yùn)維新手。1. 手工評審撐不住的地方正好是這條流水線要補(bǔ)的位1.1 代碼審查真正卡住的不是沒人看而是看不全先別急著裝軟件得先想清楚這條路要解決什么。人工評審最擅長的其實(shí)是設(shè)計(jì)層面的判斷這個(gè)抽象合不合理、這個(gè)接口劃分會(huì)不會(huì)導(dǎo)致后面耦合、這段業(yè)務(wù)邏輯有沒有理解偏差。這些是機(jī)器給不出意見的。但人工評審最不擅長的恰恰是逐行的一致性檢查一個(gè) 800 行的 diff里面混著 3 個(gè)未關(guān)閉的流、2 處字符串拼接 SQL、4 個(gè)復(fù)制粘貼出來的重復(fù)代碼塊評審人大概率會(huì)漏掉其中兩三個(gè)。所以持續(xù)代碼審查鏈路的定位很明確它不替代人它把人從找低級問題里解放出來讓人只專注在這個(gè)設(shè)計(jì)對不對上。理解了這個(gè)定位后面所有配置的取舍就有依據(jù)了規(guī)則集不要追求全開門禁不要追求一步到位因?yàn)樗哪繕?biāo)是讓問題消解在合并之前而不是讓所有人每天被一堆不痛不癢的告警淹沒。1.2 三個(gè)組件各自管哪一段邊界先劃清楚搭之前先把職責(zé)邊界畫出來不然很容易出現(xiàn)到底該在哪一層配置的反復(fù)糾結(jié)。我用一張表把實(shí)際分工列清楚組件在這條鏈路里的職責(zé)不負(fù)責(zé)的部分GitLab代碼托管、分支與 MR 管理、變更事件觸發(fā)、拉取憑證不做分析、不做構(gòu)建調(diào)度Jenkins拉代碼、跑構(gòu)建與單測、調(diào)用 Scanner、查詢質(zhì)量門結(jié)果、通知不存規(guī)則、不做靜態(tài)分析引擎SonarQube規(guī)則庫、掃描結(jié)果存儲(chǔ)、質(zhì)量門判定、歷史趨勢不主動(dòng)拉代碼、不感知 MR 狀態(tài)一個(gè)常見的誤區(qū)是希望 GitLab CI 直接調(diào)用 SonarQube 完成全部工作。技術(shù)上可行但如果你的構(gòu)建體系本來就在 Jenkins 上強(qiáng)行搬遷意味著所有歷史任務(wù)、憑據(jù)、構(gòu)建節(jié)點(diǎn)都要重新梳理成本遠(yuǎn)高于收益。我通常的做法是GitLab 只負(fù)責(zé)通知有事發(fā)生Jenkins 負(fù)責(zé)干活SonarQube 負(fù)責(zé)下結(jié)論。三者之間靠 Webhook 和 Token 通信邊界清晰任何一個(gè)組件換掉都不至于推倒重來。2. 資源盤點(diǎn)和版本取舍這一步省下來的時(shí)間后面都要還2.1 版本組合怎么選踩坑成本最低SonarQube 的版本策略這幾年變化挺大社區(qū)版Community Edition一直免費(fèi)但功能上有邊界比如不支持多分支項(xiàng)目的完整分析也不帶某些語言的企業(yè)級規(guī)則。對絕大多數(shù)中小團(tuán)隊(duì)來說社區(qū)版完全夠用。版本上我建議優(yōu)先選LTS 版本比如 9.9 這個(gè)長期支持線原因是插件生態(tài)和文檔都穩(wěn)定遇到問題好搜。想嘗鮮上最新版也行但要接受插件兼容性可能需要自己折騰。Jenkins 建議用LTS 版本的 war 包或官方鏡像不要用每周更新版。Jenkins 的插件升級經(jīng)常會(huì)帶出兼容問題LTS 至少給你一個(gè)相對固定的基線。Java 運(yùn)行時(shí)我一般固定 JDK 17Jenkins 從 2.357 之后對 JDK 11 以上支持已經(jīng)比較成熟17 是當(dāng)前比較穩(wěn)的選擇。GitLab 這邊如果是自建社區(qū)版CE也足夠跑這套流程。裝的時(shí)候別用太低的配置GitLab 本身對內(nèi)存要求不低4GB 起步是底線8GB 更舒服。2.2 內(nèi)存與內(nèi)核參數(shù)這塊最容易低估SonarQube 內(nèi)部帶著 Elasticsearch這是它最吃資源的部分也是最容易在第一次啟動(dòng)時(shí)直接崩掉的地方。有兩個(gè)參數(shù)必須在啟動(dòng)容器前設(shè)好否則日志里會(huì)出現(xiàn)一堆看不懂的報(bào)錯(cuò)。第一是內(nèi)核參數(shù)vm.max_map_countElasticsearch 要求至少 262144。臨時(shí)生效可以用sysctl -w命令但重啟就沒了所以務(wù)必要寫進(jìn)配置文件# 追加到 /etc/sysctl.conf echo vm.max_map_count262144 /etc/sysctl.conf sysctl -p第二是文件句柄數(shù)限制nofile這個(gè)在 docker-compose 里通過ulimits聲明比較干凈。我在一臺(tái) 8 核 16G 的機(jī)器上跑 SonarQube Jenkins GitLab 三個(gè)服務(wù)實(shí)測下來內(nèi)存分配大概是GitLab 3G、SonarQube 3G含 ES 約 1G、Jenkins 2G剩下的留給系統(tǒng)和 PostgreSQL剛好不緊張。如果機(jī)器只有 8G建議把 GitLab 放到另一臺(tái)機(jī)器上或者直接用云托管的 GitLab 服務(wù)別硬塞。2.3 用 compose 把 SonarQube 和數(shù)據(jù)庫拉起來SonarQube 從 7.9 之后就不再內(nèi)置數(shù)據(jù)庫了必須外掛一個(gè)。生產(chǎn)環(huán)境推薦 PostgreSQL別用 H2 或者 MySQL前者是給測試用的后者官方支持已經(jīng)在逐步收縮。下面這份 compose 文件我用了很久可以直接參考version: 3.8 services: sonar-db: image: postgres:14 container_name: sonar-db environment: POSTGRES_USER: sonar POSTGRES_PASSWORD: Change_This_Pwd POSTGRES_DB: sonar volumes: - ./pgdata:/var/lib/postgresql/data networks: - sonarnet restart: always sonarqube: image: sonarqube:9.9-community container_name: sonarqube depends_on: - sonar-db environment: SONAR_JDBC_URL: jdbc:postgresql://sonar-db:5432/sonar SONAR_JDBC_USERNAME: sonar SONAR_JDBC_PASSWORD: Change_This_Pwd SONAR_ES_BOOTSTRAP_CHECKS_DISABLE: true volumes: - ./sonar/data:/opt/sonarqube/data - ./sonar/extensions:/opt/sonarqube/extensions - ./sonar/logs:/opt/sonarqube/logs ports: - 9000:9000 ulimits: nofile: soft: 65536 hard: 65536 networks: - sonarnet restart: always networks: sonarnet: driver: bridge啟動(dòng)之后別急著訪問SonarQube 首次初始化要建表日志里出現(xiàn) SonarQube is operational 才算真正就緒這個(gè)過程在機(jī)械盤上可能要兩三分鐘。默認(rèn)賬號(hào)密碼都是 admin第一次登錄會(huì)強(qiáng)制你改密碼。注意SONAR_ES_BOOTSTRAP_CHECKS_DISABLE這個(gè)環(huán)境變量是繞過 ES 啟動(dòng)檢查的只在確認(rèn)服務(wù)器參數(shù)已經(jīng)設(shè)好的情況下使用。它的作用是避免容器因?yàn)樗拗鳈C(jī)檢查失敗而直接退出而不是讓你跳過參數(shù)配置。3. GitLab 側(cè)的準(zhǔn)備賬號(hào)、權(quán)限與兩類憑證的分工3.1 建項(xiàng)目、建賬號(hào)堅(jiān)決不用 root 跑流水線GitLab 裝好之后第一件事是建一個(gè)專用的服務(wù)賬號(hào)比如叫ci-bot給它 Developer 或 Maintainer 權(quán)限就夠了。很多團(tuán)隊(duì)圖省事直接把管理員賬號(hào)的 Token 塞進(jìn) Jenkins短期看不出問題等到有人離職或者需要審計(jì)的時(shí)候發(fā)現(xiàn)所有操作記錄都是同一個(gè)身份根本查不清是誰觸發(fā)的。接著按業(yè)務(wù)把代碼倉庫建好命名上建議和 SonarQube 里的 projectKey 保持一致比如倉庫叫order-serviceSonarQube 里的 key 也叫order-service。這樣流水線里不用額外維護(hù)一份映射關(guān)系省事而且不容易錯(cuò)。3.2 Personal Access Token 與 SSH Key各自管一攤這是新手最容易混的地方。GitLab 里有兩類憑證用途完全不同Personal Access Token給 API 用的Jenkins 的 GitLab 插件靠它去回寫構(gòu)建狀態(tài)、讀取項(xiàng)目信息、給 MR 打評論。創(chuàng)建的時(shí)候至少要勾api和read_repository兩個(gè) scope。SSH Key給 Git 協(xié)議用的Jenkins 拉代碼時(shí)用它做免密認(rèn)證。把公鑰傳到 GitLab 的 SSH Keys 頁面私鑰存進(jìn) Jenkins 憑據(jù)。兩者不能互相替代。我見過有人拿著 PAT 去配 SSH 拉取報(bào)了一堆認(rèn)證失敗最后發(fā)現(xiàn)方向就錯(cuò)了。還有一種情況是倉庫地址用的是 HTTP 協(xié)議那就不需要 SSH Key直接在 Jenkins 憑據(jù)里存賬號(hào)密碼或者用 Token 當(dāng)密碼用。Token 的有效期也得留意。GitLab 現(xiàn)在默認(rèn)給 PAT 設(shè)了過期時(shí)間如果設(shè)得太短某天早上流水線突然全部拉不到代碼你會(huì)發(fā)現(xiàn)是 Token 過期了。我的習(xí)慣是設(shè)一年同時(shí)在日歷上留個(gè)提醒。3.3 Webhook 配置里兩個(gè)坑內(nèi)網(wǎng)地址與觸發(fā)令牌代碼提交要能自動(dòng)觸發(fā) Jenkins靠的就是 Webhook。在 GitLab 項(xiàng)目的 Settings → Webhooks 里填 Jenkins 的地址勾選 Push events 和 Merge request events。這里第一個(gè)坑是地址可達(dá)性。如果 Jenkins 跑在內(nèi)網(wǎng)GitLab 是云端的這個(gè) Webhook 根本發(fā)不進(jìn)來。解決方案是在內(nèi)網(wǎng)部署一個(gè)輕量的轉(zhuǎn)發(fā)服務(wù)接收外網(wǎng)請求再轉(zhuǎn)給 Jenkins或者干脆把 GitLab 也放在同一內(nèi)網(wǎng)。別指望用 NAT 端口映射解決安全組策略和證書校驗(yàn)會(huì)帶來一堆額外麻煩。第二個(gè)坑是URL 末尾的斜杠。GitLab 的 webhook 地址如果寫成http://jenkins:8080/project/order-service有些版本會(huì)返回 404正確寫法通常要看 Jenkins 這邊配的是哪種觸發(fā)方式。用 GitLab 插件自帶的觸發(fā)器時(shí)地址形如http://jenkins.internal:8080/project/order-service而用 Generic Webhook Trigger 插件時(shí)地址是http://jenkins.internal:8080/generic-webhook-trigger/invoke?token訂單服務(wù)令牌兩個(gè)方式我都用過前者配置簡單后者解析 payload 更靈活能直接拿到分支名、MR 標(biāo)題這些字段。如果只是做基礎(chǔ)的自動(dòng)觸發(fā)第一種足夠了。4. SonarQube 服務(wù)端的落地配置從默認(rèn)狀態(tài)到能用的狀態(tài)4.1 第一次登錄后必須動(dòng)的三處設(shè)置SonarQube 裝完是能跑但不好用的狀態(tài)有三處必須調(diào)。第一是強(qiáng)制改掉 admin 密碼這個(gè)不用多說。第二是關(guān)閉匿名訪問默認(rèn)情況下未登錄用戶也能看到項(xiàng)目在 Administration → Configuration → Security 里把Force user authentication打開即可。第三是確認(rèn)服務(wù)端地址在 Administration → Configuration → General → Server base URL 里填上外網(wǎng)可訪問的地址比如http://sonar.internal:9000。這一項(xiàng)很關(guān)鍵因?yàn)?SonarQube 生成 Webhook 回調(diào)地址、生成報(bào)告鏈接都依賴它如果這里空著回到 Jenkins 的鏈接會(huì)是localhost點(diǎn)開就是 404。4.2 質(zhì)量門不是越嚴(yán)越好得分階段推Quality Gate 是這套鏈路的核心卡點(diǎn)也就是什么條件下允許合并。SonarQube 默認(rèn)內(nèi)置了一個(gè)叫 Sonar way 的門規(guī)則大致是新代碼覆蓋率不低于 80%、重復(fù)率不高于 3%、無 Blocker 級別問題、技術(shù)債比率不超過 5%。直接把 Sonar way 套到一個(gè)跑了三五年的老項(xiàng)目上結(jié)果一定是全線飄紅然后團(tuán)隊(duì)就會(huì)習(xí)慣性地點(diǎn)忽略門禁形同虛設(shè)。我的做法是分三步走階段門禁策略目標(biāo)第一階段只統(tǒng)計(jì)新代碼覆蓋率不設(shè)限只看 Blocker/Critical 問題讓團(tuán)隊(duì)先接受有掃描這件事第二階段新代碼覆蓋率設(shè) 50%重復(fù)率設(shè) 10%開始對新增質(zhì)量提要求第三階段新代碼覆蓋率 80%重復(fù)率 3%對齊 Sonar way穩(wěn)定運(yùn)行后的常態(tài)這里的關(guān)鍵在于**新代碼這個(gè)概念**。SonarQube 支持設(shè)置 New Code Period可以按天數(shù)比如最近 30 天、按版本號(hào)、按指定分支基準(zhǔn)來定義。對存量項(xiàng)目一定要用 New Code 做門禁否則你永遠(yuǎn)在還歷史債誰也推不動(dòng)。這個(gè)能力只在社區(qū)版以外的版本提供完整支持社區(qū)版也能配但選項(xiàng)少一些夠用。4.3 Scanner 的兩種接入方式和選擇依據(jù)SonarScanner 有兩類用法。一類是獨(dú)立的命令行 Scannersonar-scanner-cli通過sonar-project.properties文件傳參適合前端、Go、Python 這類沒有專門插件的項(xiàng)目。另一類是構(gòu)建工具的原生插件比如 Maven 的sonar:sonar目標(biāo)、Gradle 的sonar任務(wù)把分析直接嵌進(jìn)構(gòu)建生命周期參數(shù)可以寫在 pom.xml 里也可以命令行傳。選哪個(gè)的判斷標(biāo)準(zhǔn)很簡單項(xiàng)目用什么構(gòu)建就用什么方式接。Java Maven 項(xiàng)目用 Maven 插件原因是它已經(jīng)知道源碼目錄、編譯產(chǎn)物目錄、依賴 jar 路徑不需要你再手動(dòng)指定sonar.java.binaries這類參數(shù)省去一堆路徑錯(cuò)誤。而如果是前端項(xiàng)目用獨(dú)立 Scanner 更合適配一份 properties 文件就夠了。實(shí)在不想在構(gòu)建節(jié)點(diǎn)上裝 Scanner還能用 docker 鏡像方式跑docker run --rm \ -v $(pwd):/usr/src \ --network host \ -e SONAR_HOST_URLhttp://sonar.internal:9000 \ -e SONAR_LOGIN${SONAR_TOKEN} \ sonarsource/sonar-scanner-cli:5這種方式的好處是節(jié)點(diǎn)上零依賴壞處是每次都要拉鏡像、映射目錄分析大項(xiàng)目時(shí) IO 會(huì)慢一些。我一般在多語言混合、構(gòu)建節(jié)點(diǎn)不方便裝東西的場景下用這個(gè)方案。5. Jenkins 上把憑據(jù)和插件配起來5.1 插件清單和安裝順序Jenkins 裝完先別急著建任務(wù)插件沒裝齊后面會(huì)反復(fù)報(bào)錯(cuò)。這套鏈路需要的插件其實(shí)不多我把清單列一下Git plugin拉代碼的基礎(chǔ)幾乎必裝。GitLab Plugin負(fù)責(zé)和 GitLab 通信回寫構(gòu)建狀態(tài)、解析 Webhook payload。SonarQube Scanner提供withSonarQubeEnv和waitForQualityGate這兩個(gè)流水線步驟。Pipeline含 Declarative Pipeline寫 Jenkinsfile 用。Credentials Binding把憑據(jù)注入環(huán)境變量。Build Timeout給質(zhì)量門等待加超時(shí)防止流水線卡死。DingTalk 通知插件或普通 HTTP 請求插件構(gòu)建結(jié)束后發(fā)通知。如果 Jenkeins 服務(wù)器在內(nèi)網(wǎng)、無法訪問外網(wǎng)插件中心就得走離線安裝在有網(wǎng)的機(jī)器上下載.hpi文件從 Manage Jenkins → Plugins → Advanced 里手動(dòng)上傳。離線安裝最煩的是依賴關(guān)系插件 A 依賴插件 BB 又依賴 C裝完重啟發(fā)現(xiàn)啟動(dòng)失敗日志里提示某個(gè)類找不到。我的建議是先裝 Git plugin再裝 Pipeline最后裝業(yè)務(wù)插件按這個(gè)順序走基本不會(huì)缺依賴。5.2 憑據(jù)管理Token 放哪里、怎么命名憑據(jù)統(tǒng)一放在 Manage Jenkins → Credentials → System → Global credentials 下面。這套鏈路至少需要三個(gè)憑據(jù) ID類型用途gitlab-ssh-keySSH Username with private keyJenkins 拉代碼gitlab-api-tokenSecret textGitLab 插件回寫狀態(tài)sonar-tokenSecret textScanner 上報(bào)分析結(jié)果命名上我堅(jiān)持用帶前綴的規(guī)則比如gitlab-和sonar-開頭好處是憑據(jù)列表一多還能快速辨認(rèn)用途。ID 一旦定下來就盡量別改因?yàn)?Jenkinsfile 里會(huì)硬引這個(gè) ID改了要同步改一堆腳本。SonarQube 那邊的 Token 在用戶頭像 → My Account → Security 里生成生成后只顯示一次務(wù)必當(dāng)場復(fù)制。這個(gè) Token 的權(quán)限跟著生成它的用戶走所以別用 admin 賬號(hào)生成用前面建的那個(gè)服務(wù)賬號(hào)。5.3 GitLab Connection 的填法以及 login failed 從哪來在 Manage Jenkins → System 里找到 GitLab 配置區(qū)填兩樣?xùn)|西GitLab 服務(wù)器地址和憑據(jù)。地址必須寫根地址比如http://gitlab.internal不要帶結(jié)尾斜杠也不要帶/api/v4后面的路徑插件會(huì)自己拼接。這一點(diǎn)很多人搞錯(cuò)填成http://gitlab.internal/之后保存測試連接就報(bào)錯(cuò)。如果測試連接時(shí)彈出login failed. check api token or gitlab version按這個(gè)順序排查Token 是否真的勾了apiscope。只勾read_api是不夠的插件需要寫權(quán)限來回寫狀態(tài)。Token 有沒有過期。GitLab 的 PAT 現(xiàn)在默認(rèn)帶有效期過期后接口返回 401。GitLab 版本是否過老。GitLab Plugin 對服務(wù)端版本有最低要求太老的版本 API 路徑不一致插件直接判定失敗。如果用的是 Git 協(xié)議訪問而不是 API 訪問那這個(gè)報(bào)錯(cuò)本身就說明配錯(cuò)了入口應(yīng)該去檢查憑據(jù)綁定那一層而不是在 GitLab Connection 里糾纏。順帶說一個(gè)容易忽略的點(diǎn)如果 GitLab 是自簽證書的 HTTPSJenkins 的 JVM 里沒有導(dǎo)入這個(gè) CA連接會(huì)直接拋 SSL 握手異常。解決方式是給 Jenkins 的啟動(dòng)參數(shù)加上信任庫或者用 Jenkins 內(nèi)置的-Djavax.net.ssl.trustStore指定。內(nèi)網(wǎng)環(huán)境里這個(gè)問題出現(xiàn)的頻率比想象的高。5.4 那些真正好用的 Jenkins 可用環(huán)境變量寫 Jenkinsfile 時(shí)用好環(huán)境變量能讓腳本短一大截。這套鏈路里我用得最多的是這些GIT_BRANCH當(dāng)前構(gòu)建的分支名回寫狀態(tài)、拼通知消息都要用。GIT_COMMIT完整 commit hashSonarQube 關(guān)聯(lián)分析結(jié)果靠它。GIT_PREVIOUS_SUCCESSFUL_COMMIT上一次成功構(gòu)建的 commit做增量分析時(shí)非常有用。WORKSPACE工作目錄Scanner 的路徑參數(shù)直接引這個(gè)。BUILD_NUMBER構(gòu)建序號(hào)通知里帶上能快速定位。JOB_NAME任務(wù)名多任務(wù)共用一套 pipeline 時(shí)用來區(qū)分。NODE_NAME構(gòu)建節(jié)點(diǎn)名排查為什么這臺(tái)機(jī)器上沒有輸出時(shí)有奇效。提示GIT_BRANCH在 MR 場景下拿到的值形如origin/feature/login前面帶origin/。拼進(jìn) SonarQube 參數(shù)時(shí)要先剝掉這個(gè)前綴否則分支名對不上。這個(gè)細(xì)節(jié)我踩過一次掃描結(jié)果全落到一個(gè)叫origin/xxx的假分支上去了。6. Jenkinsfile把分析、門禁、通知串成一條鏈6.1 聲明式流水線的整體骨架我不太推薦用自由風(fēng)格任務(wù)配這套流程雖然能跑通但腳本一旦變復(fù)雜就沒法維護(hù)而且核心步驟還是得寫 shell不如直接用聲明式流水線。整體骨架是四段拉代碼、構(gòu)建與單測、執(zhí)行掃描、查詢質(zhì)量門。順序不能隨意調(diào)整因?yàn)橘|(zhì)量門必須在掃描完成、SonarQube 處理完之后才能查否則查到的永遠(yuǎn)是上一次的結(jié)果。pipeline { agent any tools { maven maven-3.9 jdk jdk-17 } options { timeout(time: 30, unit: MINUTES) buildDiscarder(logRotator(numToKeepStr: 30)) } stages { stage(Checkout) { steps { checkout scm script { env.BRANCH_NAME env.GIT_BRANCH.replaceFirst(origin/, ) } } } stage(Build Test) { steps { sh mvn -B -U clean test } } stage(SonarQube Analysis) { steps { withSonarQubeEnv(sonar-server) { sh mvn -B sonar:sonar \ -Dsonar.projectKeyorder-service \ -Dsonar.projectNameorder-service \ -Dsonar.branch.name${env.BRANCH_NAME} } } } stage(Quality Gate) { steps { timeout(time: 5, unit: MINUTES) { waitForQualityGate abortPipeline: true } } } } }6.2 Checkout、Scanner、Quality Gate 三段里的關(guān)鍵參數(shù)Checkout 段里我加了一步剝離origin/前綴原因前面說過。另外如果要多倉庫同時(shí)構(gòu)建checkout scm就換成顯式的git步驟把 url 和 credentialsId 寫清楚。Scanner 段靠withSonarQubeEnv注入環(huán)境變量這個(gè)步驟會(huì)把 SonarQube 服務(wù)地址和 Token 自動(dòng)塞進(jìn)環(huán)境變量Scanner 直接讀就行不用明文寫 Token。里面那個(gè)sonar-server是 Jenkins 全局配置里給 SonarQube 服務(wù)器起的名字兩邊必須一致。sonar.branch.name參數(shù)在社區(qū)版里支持有限如果是社區(qū)版可以考慮用-Dsonar.projectKey拼分支后綴的方式區(qū)分。Quality Gate 段的核心是waitForQualityGate它不主動(dòng)去查而是等 SonarQube 回調(diào)。也就是說SonarQube 那邊必須配好一個(gè) Webhook地址指向http://jenkins.internal:8080/sonarqube-webhook/這個(gè)地址是固定的路徑不能改。如果 SonarQube 是容器部署從容器里能不能訪問到 Jenkins 的地址也得驗(yàn)證一下容器內(nèi)的jenkins.internal未必能解析這種情況直接寫宿主機(jī)的內(nèi)網(wǎng) IP。6.3 分支和 MR 場景下的差異化策略主干和特性分支的要求不應(yīng)該一樣。我的做法是主干分支跑全量分析 嚴(yán)格門禁特性分支只統(tǒng)計(jì)新代碼 寬松門禁。實(shí)現(xiàn)方式是用流水線里的條件判斷根據(jù)分支名走不同參數(shù)stage(SonarQube Analysis) { steps { withSonarQubeEnv(sonar-server) { script { def extraArgs env.BRANCH_NAME master || env.BRANCH_NAME main ? -Dsonar.qualitygate.waitfalse : -Dsonar.newCode.referenceBranchmaster sh mvn -B sonar:sonar \ -Dsonar.projectKeyorder-service \ -Dsonar.branch.name${env.BRANCH_NAME} \ ${extraArgs} } } } }MR 場景下還有個(gè)實(shí)用技巧把 SonarQube 分析出來的問題數(shù)寫進(jìn)構(gòu)建描述里評審人在 GitLab 的 MR 頁面上就能看到這次提交引入了 3 個(gè)新的嚴(yán)重問題比讓人去點(diǎn)開 Sonar 頁面直觀得多。這個(gè)通過 Jenkins 的currentBuild.description屬性設(shè)置即可配合 GitLab 插件的狀態(tài)回寫信息就同步過去了。7. 跑起來之后真正的麻煩才剛開始7.1 Webhook 發(fā)了Jenkins 一點(diǎn)反應(yīng)都沒有這是最高頻的問題。排查思路是按鏈路倒著走第一步去 GitLab 的 Webhooks 頁面點(diǎn) Test 按鈕看響應(yīng)碼。如果是 403基本都是 Jenkins 的 CSRF 保護(hù)攔住了。用 GitLab 插件自帶的觸發(fā)方式時(shí)在任務(wù)的構(gòu)建觸發(fā)器里要勾選 Enable GitLab trigger插件會(huì)自動(dòng)處理鑒權(quán)。如果用的是 Generic Webhook Trigger地址里帶 token 參數(shù)就能繞過。第二步如果響應(yīng) 404檢查項(xiàng)目路徑對不對尤其注意任務(wù)名里帶中文或者空格時(shí) URL 編碼的問題能避則避。第三步如果響應(yīng) 200 但 Jenkins 沒建新任務(wù)那就是觸發(fā)的分支過濾沒配對。GitLab 插件默認(rèn)只對配置里允許的分支觸發(fā)比如確實(shí)配了master但你提交的是feature/xxx自然不會(huì)觸發(fā)。7.2 質(zhì)量門結(jié)果回寫不回來流水線卡在 waitForQualityGate現(xiàn)象是掃描步驟明明成功了SonarQube 頁面上也能看到結(jié)果但 Jenkins 一直停在 Quality Gate 那一步最后被 timeout 干掉。九成的原因是SonarQube 的 Webhook 配置有問題。去 SonarQube 的 Administration → Configuration → Webhooks 里加一條URL 填 Jenkins 的sonarqube-webhook地址然后點(diǎn)測試。這里最常見的失敗原因是 SonarQube 的容器網(wǎng)絡(luò)訪問不到 Jenkins 的地址或者 Jenkins 地址里填了localhost。SonarQube 是從它自己的網(wǎng)絡(luò)視角去回調(diào)的你本機(jī)瀏覽器能打開的localhost:8080它未必打得開。還有一個(gè)隱蔽的原因sonar.branch.name參數(shù)和 Webhook 回調(diào)里帶的分支標(biāo)識(shí)對不上導(dǎo)致 Jenkins 收到回調(diào)后找不到對應(yīng)的等待中的任務(wù)只能干等。這種情況在社區(qū)版里出現(xiàn)得多一個(gè)繞法是不用waitForQualityGate改用輪詢方式調(diào) SonarQube 的 Web API 查結(jié)果curl -s -u ${SONAR_TOKEN}: \ http://sonar.internal:9000/api/qualitygates/project_status?projectKeyorder-servicebranch${BRANCH_NAME}拿到 JSON 后判斷projectStatus.status字段不是OK就讓構(gòu)建失敗。這種方式犧牲了實(shí)時(shí)性但穩(wěn)定得多。7.3 Scanner 報(bào)超時(shí)、內(nèi)存溢出和構(gòu)建節(jié)點(diǎn)上的路徑錯(cuò)誤大項(xiàng)目上跑 Scanner報(bào)內(nèi)存不足是常事。默認(rèn) JVM 堆可能只有幾百 M分析幾萬行代碼直接 OOM。解決辦法是設(shè)SONAR_SCANNER_OPTSexport SONAR_SCANNER_OPTS-Xmx2g -Xms512m如果用的是 Maven 插件方式改設(shè)MAVEN_OPTS。另一個(gè)高頻問題是 Java 項(xiàng)目的sonar.java.binaries找不到報(bào)錯(cuò)說Please provide compiled classes。用 Maven 插件不會(huì)有這問題因?yàn)樗赾ompile之后才跑sonar:sonar但如果流水線里把sonar:sonar放在了clean后面沒跟compile編譯產(chǎn)物就被清掉了自然找不到。順序必須是clean compile sonar:sonar或者至少保證target/classes存在。還有一種情況發(fā)生在多模塊項(xiàng)目里父 pom 和子模塊的路徑關(guān)系沒配好Scanner 只掃到了父模塊的空殼子模塊代碼一行沒進(jìn)。判斷方法是看 SonarQube 報(bào)告里的代碼行數(shù)如果遠(yuǎn)小于實(shí)際代碼量基本就是這個(gè)原因。7.4 各類認(rèn)證失敗報(bào)錯(cuò)的真實(shí)成因除了前面說的 GitLab Connection 報(bào)錯(cuò)還有幾個(gè)容易撞上的報(bào)錯(cuò)信息關(guān)鍵詞大概率原因處理方向401 UnauthorizedScanner 上報(bào)Sonar Token 錯(cuò)誤或已失效重新生成 Token 并更新 Jenkins 憑據(jù)Permission denied (publickey)SSH 私鑰不匹配或格式問題確認(rèn)公鑰已加進(jìn) GitLab私鑰是 OpenSSH 格式Host key verification failedJenkins 節(jié)點(diǎn)首次連接該主機(jī)手動(dòng)執(zhí)行一次 ssh-keyscan 寫入 known_hostsdocker: error response from daemon: Get https://registry-1...構(gòu)建節(jié)點(diǎn)拉不到鏡像配置鏡像加速或改用本地已緩存鏡像最后那條在離線或網(wǎng)絡(luò)受限的環(huán)境里特別常見。如果構(gòu)建節(jié)點(diǎn)不能訪問公共鏡像倉庫方案是在有網(wǎng)的機(jī)器上docker save導(dǎo)出鏡像傳過去docker load導(dǎo)入然后把流水線里的image換成本地已有的 tag避免觸發(fā)拉取。8. 讓它長期活下去誤報(bào)治理、掃描節(jié)奏和升級順序8.1 誤報(bào)治理比加規(guī)則重要得多工具上線三個(gè)月之后最大的敵人不是漏報(bào)而是誤報(bào)堆積導(dǎo)致的麻木。團(tuán)隊(duì)慢慢發(fā)現(xiàn)Sonar 報(bào)的這些問題其實(shí)沒關(guān)系然后所有人都開始忽略整個(gè)門禁就廢了。治理誤報(bào)有幾種手段按推薦順序排標(biāo)記為 False Positive確實(shí)不成立的規(guī)則告警在界面上直接標(biāo)掉下個(gè)版本就不再出現(xiàn)。這個(gè)動(dòng)作要有人定期做我一般安排每兩周花半小時(shí)過一遍新增的誤報(bào)。調(diào)整規(guī)則的嚴(yán)重級別有些規(guī)則本身成立但對當(dāng)前項(xiàng)目來說不算關(guān)鍵把它從 Major 降到 Minor不再影響門禁。在代碼里注釋抑制// NOSONAR這種注釋要慎用它只適合極個(gè)別場景一旦泛濫就失去意義。我見過一個(gè)項(xiàng)目里幾十處 NOSONAR最后沒人知道哪處是合理的。8.2 全量掃描和增量掃描的節(jié)奏安排每種掃描的目的不同頻率也該不同。我的實(shí)際安排是這樣每次提交/推送跑增量分析只看變更文件幾十秒出結(jié)果不阻塞開發(fā)節(jié)奏。每天一次定時(shí)任務(wù)跑全量分析發(fā)現(xiàn)那些跨文件的、需要全局視野才能看出來的問題比如循環(huán)依賴、大范圍的重復(fù)代碼。每個(gè)版本發(fā)布前跑一次帶完整門禁的全量分析作為發(fā)布卡點(diǎn)。定時(shí)掃描用 Jenkins 的 cron 觸發(fā)器實(shí)現(xiàn)寫在流水線里就一行triggers { cron(H 2 * * *) }H是 Jenkins 的散列語法用來打散同一時(shí)刻的任務(wù)避免所有任務(wù)半夜兩點(diǎn)同時(shí)起跑把機(jī)器壓垮。這個(gè)細(xì)節(jié)在小規(guī)模時(shí)無所謂任務(wù)一多就是救命的東西。8.3 升級 SonarQube 和 Jenkins 的穩(wěn)妥順序升級是有順序的亂了容易出大問題。SonarQube 升級必須先備份數(shù)據(jù)庫和data、extensions目錄然后按官方文檔的升級路徑走。跨大版本比如 8.9 到 9.9不能跳要經(jīng)過中間版本。升級完第一件事是檢查插件兼容性很多第三方插件在新版本上會(huì)失效需要重新下載對應(yīng)版本。Jenkins 升級的風(fēng)險(xiǎn)點(diǎn)主要在插件。我一般先在測試環(huán)境升一遍重點(diǎn)驗(yàn)證 GitLab 插件和 SonarQube Scanner 插件能不能正常工作。這兩個(gè)插件是鏈路的生命線它們出問題整條流水線就斷了。升級前把當(dāng)前插件版本列表導(dǎo)出來備份出問題時(shí)能快速回滾。還有一個(gè)跨版本的坑SonarQube 大版本升級時(shí)Scanner 的版本可能也需要同步跟進(jìn)。新舊版本之間 API 協(xié)議有變化時(shí)會(huì)出現(xiàn)分析提交上了但結(jié)果不完整這種軟失敗日志里不一定有明顯報(bào)錯(cuò)只有看 SonarQube 上的分析詳情才能發(fā)現(xiàn)。升級后一定要跑一次完整回歸核對代碼行數(shù)、問題數(shù)量是否合理。這套鏈路我前后搭過四五次從最早的純手工到后來全自動(dòng)最深的一個(gè)體會(huì)是第一次搭起來不算完成能連續(xù)跑半年不被人嫌棄才算完成。中間那段調(diào)整期基本都花在把門禁從卡所有人調(diào)成只卡新代碼、把誤報(bào)一條條清掉、把通知從每次都發(fā)改成只有失敗才發(fā)這些細(xì)節(jié)上。所以如果你正準(zhǔn)備動(dòng)手建議第一版就把質(zhì)量門設(shè)得寬松一些先讓大家感受到代碼提交完半分鐘就能看到自己引入了什么問題這個(gè)即時(shí)反饋的價(jià)值等人習(xí)慣了再逐步收緊。反過來先上嚴(yán)格門禁大概率第二周就會(huì)有人在群里問這個(gè)能不能先關(guān)掉。