前兩天在給團(tuán)隊(duì)修構(gòu)建流水線的時(shí)候正好撞上這個(gè)問題Jenkins Pipeline Job 跑完是綠色的可點(diǎn)進(jìn)構(gòu)建詳情頁(yè)原本應(yīng)該在構(gòu)建記錄下方出現(xiàn)的 Stage View階段視圖區(qū)域卻一片空白只有控制臺(tái)輸出。問了一圈同事有的說(shuō)再刷新一下有的說(shuō)換瀏覽器試試全都沒用。后來(lái)翻了半天官方文檔和插件源碼才意識(shí)到這個(gè)問題可以分成好幾類——大部分時(shí)候不是玄學(xué)而是 Job 類型、腳本寫法、插件版本或者權(quán)限配置里藏著的某個(gè)小坑。這篇文章就把這次完整的排查思路整理出來(lái)順便把幾個(gè)一眼就能判斷原因的檢查項(xiàng)寫在前面讓碰到Jenkins 不顯示階段視圖的朋友能少走彎路。無(wú)論你是剛?cè)腴T的小白還是已經(jīng)被這個(gè)問題折騰了幾天的老手按著下面五步走基本都能把問題定位到具體層次。1. 階段視圖不是自來(lái)就有先確認(rèn) Job 類型這個(gè)前提1.1 階段視圖到底是怎么回事很多人第一次接觸階段視圖是在演示視頻里看到的構(gòu)建記錄下方有一排彩色小方塊綠色代表成功、紅色代表失敗、灰色代表跳過(guò)點(diǎn)進(jìn)去還能看到每個(gè)階段耗時(shí)和日志。這個(gè)視圖本質(zhì)上是由兩部分協(xié)作生成的一部分是 Pipeline 引擎在構(gòu)建時(shí)對(duì) stage 事件的記錄另一部分是頁(yè)面加載時(shí)通過(guò)后臺(tái) API 把這些記錄拉出來(lái)渲染成色塊。這意味著一個(gè)最基本的邏輯如果 Job 本身沒有階段這個(gè)概念或者階段事件根本沒有被記錄下來(lái)那么在頁(yè)面上就永遠(yuǎn)不可能看到階段視圖。這個(gè)前提往往被忽略了——很多人在排查時(shí)第一反應(yīng)是插件壞了瀏覽器緩存了實(shí)際上我遇到的案例里有一大半是因?yàn)?Job 根本不是 Pipeline 類型。Jenkins 里有多種項(xiàng)目類型Freestyle Project、Maven Project、Pipeline、多分支 Pipeline、Organization Folder 等。Freestyle 項(xiàng)目只能配置普通構(gòu)建步驟它的執(zhí)行模型里沒有聲明式 stage 的概念因此永遠(yuǎn)不會(huì)出現(xiàn)階段視圖。如果你在 Freestyle 里通過(guò)Execute Groovy script或者Invoke Gradle跑了一些命令構(gòu)建結(jié)果頁(yè)只會(huì)顯示控制臺(tái)輸出不會(huì)有階段視圖區(qū)域。還有一種容易混淆的情況多分支 Pipeline。多分支項(xiàng)目的頂層頁(yè)面只是分支列表階段視圖必須進(jìn)入具體分支的 Job 詳情頁(yè)才能看到。如果你在分支列表頁(yè)翻來(lái)翻去找不到階段視圖那不是問題是入口不對(duì)。1.2 用 API 一條命令確認(rèn) Job 類型手動(dòng)判斷 Job 類型其實(shí)也不難打開 Job 的配置頁(yè)面如果里面有Pipeline配置區(qū)通常包含 Definition 下拉框、腳本編輯區(qū)或 SCM 選擇說(shuō)明這是 Pipeline Job如果沒有說(shuō)明不是。另一個(gè)更快的辦法是看 Job 主頁(yè)左側(cè)菜單Pipeline Job 一般會(huì)有Pipeline Syntax、Replay這些入口Freestyle Job 沒有。但為了嚴(yán)謹(jǐn)我習(xí)慣直接用 REST API 確認(rèn)尤其是當(dāng) Jenkins 頁(yè)面因?yàn)槟承?quán)限或主題問題看不全時(shí)# 以管理員身份或帶讀權(quán)限的用戶身份執(zhí)行 curl -s http://your-jenkins:8080/job/demo-job/api/json | jq ._class如果輸出是org.jenkinsci.plugins.workflow.job.WorkflowJob說(shuō)明是單分支 Pipeline如果是org.jenkinsci.plugins.workflow.multibranch.WorkflowMultiBranchProject說(shuō)明是多分支如果是hudson.model.FreeStyleProject那就是 Freestyle。多分支的情況需要多走一層/job/fullstack-app/job/master/才是實(shí)際分支 Job 的路徑在這個(gè)層級(jí)頁(yè)面里才看得到階段視圖。我見過(guò)有同事在分支列表的總覽頁(yè)盯著看了十分鐘還以為 Jenkins 出 bug 了。1.3 最小化復(fù)現(xiàn)實(shí)驗(yàn)先跑一個(gè)最簡(jiǎn)單的 Pipeline Job無(wú)論你是新手還是老手我都強(qiáng)烈建議在做任何復(fù)雜排查之前先在同一個(gè) Jenkins 上新建一個(gè)最簡(jiǎn)單的 Pipeline Job跑一次試試。這一步能把環(huán)境問題和腳本問題快速切開pipeline { agent any stages { stage(hello) { steps { echo hello world } } } }如果這個(gè)最簡(jiǎn)單的 Job 能看到完整的階段視圖說(shuō)明 Jenkins 服務(wù)和相關(guān)插件是正常的問題出在你原來(lái)的 Job 或腳本上。如果這個(gè) Job 也看不到視圖那問題就在 Jenkins 環(huán)境層面后面的腳本排查就不用細(xì)看了。這個(gè)最小化復(fù)現(xiàn)實(shí)驗(yàn)是整個(gè)排查過(guò)程里性價(jià)比最高的一步強(qiáng)烈建議放在所有操作之前它能把排查范圍一下子縮小一半。2. 腳本寫法問題為什么 pipeline 跑了stage 卻隱形了2.1 Declarative 里的低級(jí)錯(cuò)誤聲明式 Pipeline 的模板結(jié)構(gòu)是頂層是pipeline塊pipeline里有agent、stages、steps。如果書寫時(shí)漏掉了stages包圍層或者把steps寫成了stepJenkins 在解析階段就會(huì)直接報(bào)錯(cuò)。這種解析失敗的構(gòu)建控制臺(tái)里往往能看到類似WorkflowScript: N: Not a valid stage的異常而頁(yè)面上的構(gòu)建記錄只會(huì)有紅色失敗標(biāo)記和日志鏈接不會(huì)出現(xiàn)階段視圖。還有一種很隱蔽的情況把node塊混進(jìn)了聲明式結(jié)構(gòu)里。我見過(guò)有人這么寫// 錯(cuò)誤寫法Declarative 中混入 node 塊 pipeline { agent any stages { node { sh make } } }這種寫法在語(yǔ)法上看似沒問題實(shí)際上node并不是一個(gè)合法的 stage 子元素Jenkins 解析時(shí)會(huì)直接拒絕運(yùn)行。正確的聲明式寫法應(yīng)該是pipeline { agent any stages { stage(Build) { steps { sh make } } } }另外需要注意不要在stages外面多加括號(hào)不要把逗號(hào)漏掉這些 Groovy 語(yǔ)法錯(cuò)誤同樣會(huì)導(dǎo)致配置階段失敗。遇到解析失敗的場(chǎng)景控制臺(tái)日志的前 20 行就是最好的線索一定要先看。還有一種情況是腳本解析成功但所有 stage 都被when條件跳過(guò)了。這種時(shí)候階段視圖區(qū)域其實(shí)會(huì)存在只是顯示成灰色跳過(guò)狀態(tài)或者完全沒有彩色塊。很多用戶以為這就是不顯示其實(shí)它和完全缺失是兩回事處理思路完全不一樣。如果你懷疑是條件判斷導(dǎo)致的問題可以把when臨時(shí)改成when { beforeAgent true; expression { true } }來(lái)強(qiáng)制放行確認(rèn)一下 stage 本身是否能出現(xiàn)。2.2 Scripted 里沒有調(diào)用 stage 方法腳本式 Pipeline 和聲明式差別很大它本質(zhì)上就是一段 Groovy 腳本只有調(diào)用stage(名稱)方法時(shí)才會(huì)在視圖上生成階段區(qū)域。如果你直接把構(gòu)建步驟裸寫在node塊里// 錯(cuò)誤寫法全程沒有定義 stage node(linux) { git ... sh make build sh make test }那么 Stage View 就是空的。構(gòu)建可以成功但沒有任何階段信息可供展示。許多從 Freestyle Job 批量腳本遷移過(guò)來(lái)的人最容易踩這個(gè)坑他們把原來(lái)的 shell 命令原樣搬到node塊里卻忘了包一層 stage。正確寫法應(yīng)該是node(linux) { stage(checkout) { git ... } stage(build) { sh make build } stage(test) { sh make test } }改完重跑一次階段視圖就出來(lái)了。另外補(bǔ)充一點(diǎn)在 Scripted 中stage可以嵌套在parallel閉包里但無(wú)論怎么嵌套前提是你得真的調(diào)用stage這個(gè)方法。有些老腳本里用build步驟去觸發(fā)別的 Job以為這樣也能在視圖里看到階段實(shí)際上它只會(huì)作為當(dāng)前 stage 里的一個(gè)步驟出現(xiàn)不會(huì)額外生成階段色塊。2.3 共享庫(kù)與外部 Jenkinsfile 的坑用Pipeline script from SCM加載遠(yuǎn)端 Jenkinsfile 時(shí)問題往往不在 Job 配置里而在遠(yuǎn)端文件本身。我遇到過(guò)好幾次有人改動(dòng)了 Git 倉(cāng)庫(kù)里 Jenkinsfile 的路徑或者文件編碼出了問題Jenkins 在加載階段就失敗了。這種構(gòu)建的控制臺(tái)日志前幾行通常只有Started和ERROR: Cannot find Jenkinsfile連 stage 都不會(huì)開始執(zhí)行階段視圖自然不存在。共享庫(kù)場(chǎng)景也類似。如果你把一段 pipeline 封裝在共享庫(kù)的方法里而共享庫(kù)內(nèi)部用的是node包裹業(yè)務(wù)步驟沒有在頂層聲明 stage那么外部 Job 調(diào)用這個(gè)庫(kù)時(shí)即使整個(gè)流程跑通了階段視圖依然空白。這一點(diǎn)特別容易讓人迷惑因?yàn)?Job 配置頁(yè)面里的腳本可能只有一行runDeployment()看起來(lái)完全正常但視圖就是不出來(lái)。排查這類問題有一個(gè)笨但有效的辦法在共享庫(kù)方法內(nèi)部臨時(shí)加一個(gè)stage(trace) { echo ... }看它是否出現(xiàn)在視圖上。如果出現(xiàn)了說(shuō)明問題是業(yè)務(wù)代碼沒有被 stage 包裹如果沒有說(shuō)明共享庫(kù)的加載鏈路本身有問題需要去看庫(kù)的加載日志。3. 數(shù)據(jù)明明存在就是渲染不出來(lái)緩存、權(quán)限與前端請(qǐng)求3.1 別小看瀏覽器與代理緩存當(dāng)腳本層面確認(rèn)沒問題、而且最小化實(shí)驗(yàn) Job 也正常顯示視圖時(shí)出問題的就只剩下當(dāng)前這個(gè) Job 的頁(yè)面展示鏈路。這時(shí)候第一個(gè)要排除的就是緩存。Jenkins 的構(gòu)建詳情頁(yè)在加載時(shí)會(huì)通過(guò)后臺(tái)接口異步拉取 stage 數(shù)據(jù)渲染成色塊。如果瀏覽器緩存了舊的頁(yè)面 JavaScript 文件或者代理層緩存了請(qǐng)求響應(yīng)就可能導(dǎo)致新構(gòu)建的 stage 數(shù)據(jù)請(qǐng)求發(fā)不出去或者響應(yīng)被當(dāng)成舊內(nèi)容處理。最簡(jiǎn)單的辦法是強(qiáng)制刷新Windows/Linux 上按 CtrlF5macOS 上按 CmdShiftR更徹底一點(diǎn)直接開一個(gè)隱私窗口訪問同一個(gè)頁(yè)面。如果你的 Jenkins 掛在反向代理后面還得看一眼代理配置里是不是對(duì)/jenkins這個(gè)路徑做了頁(yè)面緩存。雖然大多數(shù) Nginx 配置不會(huì)緩存動(dòng)態(tài)頁(yè)面但如果你自己加了 proxy_cache 規(guī)則且沒排除 JSON 接口也可能發(fā)生頁(yè)面刷新永遠(yuǎn)拿不到新數(shù)據(jù)的詭異現(xiàn)象。這種問題從 Jenkins 側(cè)完全無(wú)解只能在代理層排查。3.2 權(quán)限配置會(huì)不會(huì)隱藏 Stage View權(quán)限問題比想象中常見。很多團(tuán)隊(duì)會(huì)啟用基于角色的權(quán)限策略給不同角色分配不同 Job 的操作權(quán)限。部分權(quán)限模型會(huì)基于用戶角色動(dòng)態(tài)裁剪頁(yè)面元素如果某個(gè)角色缺少 Pipeline 相關(guān)的查看權(quán)限即使能看到構(gòu)建記錄和控制臺(tái)日志階段視圖區(qū)域也可能整個(gè)不渲染。排查權(quán)限問題的方法很簡(jiǎn)單用管理員賬號(hào)登錄打開同一個(gè) Job 的同一個(gè)構(gòu)建詳情頁(yè)看看階段視圖是否正常。如果管理員能看到、普通用戶看不到那基本就是權(quán)限配置的鍋。這時(shí)候去角色配置里把該角色對(duì)目標(biāo) Job 的Read和ViewStatus權(quán)限補(bǔ)上再讓用戶重新登錄驗(yàn)證。有一點(diǎn)需要注意權(quán)限問題往往不是整個(gè)視圖消失而是部分內(nèi)容不加載或者接口請(qǐng)求 403。如果你在瀏覽器 F12 的 Network 面板里看到某個(gè) wfapi 請(qǐng)求返回 403 或 404那權(quán)限或插件問題的可能性就非常大。3.3 用 wfapi 接口確認(rèn)數(shù)據(jù)層是否正常這是整個(gè)排查過(guò)程中最核心的一步也是最能區(qū)分腳本問題和UI 問題的分水嶺。Jenkins 的 Pipeline Stage View 插件會(huì)提供一套可視化 API通過(guò)它你可以在不打開頁(yè)面的情況下直接確認(rèn)某個(gè)構(gòu)建里到底有沒有 stage 數(shù)據(jù)# 查看某個(gè)構(gòu)建的階段數(shù)據(jù) curl -s http://your-jenkins:8080/job/demo-job/12/wfapi/describe | jq .stages[] | {name: .name, status: .status, durationMillis: .durationMillis}如果返回了 stages 數(shù)組并且每條都有 name 和 status說(shuō)明 pipeline 運(yùn)行數(shù)據(jù)是完整的問題出在 UI 渲染層也就是緩存、權(quán)限或前端資源這一類如果返回 404說(shuō)明 Stage View 插件或 Pipeline API 插件可能沒裝好如果 stages 數(shù)組為空那問題回到第 2 章說(shuō)明腳本確實(shí)沒有產(chǎn)生任何階段信息。還可以用瀏覽器 F12 打開構(gòu)建詳情頁(yè)切到 Network 面板刷新頁(yè)面后搜索wfapi看相關(guān)請(qǐng)求的返回碼。200 但頁(yè)面不顯示通常是前端渲染問題404 或 500則是后端端點(diǎn)或插件生命周期問題。這一招能讓你在跟同事遠(yuǎn)程協(xié)作時(shí)一句話就把問題層次說(shuō)清楚。4. 插件版本與組合pipeline-stage-view 的常見事故現(xiàn)場(chǎng)4.1 缺了哪個(gè)插件會(huì)導(dǎo)致視圖消失Jenkins 的 Pipeline 能力是按插件拆分出來(lái)的最基礎(chǔ)的一組包括Pipeline: Groovy提供 Pipeline DSL、Pipeline: API提供 wfapi 后臺(tái)接口、Pipeline: Stage View提供 UI 上的階段視圖渲染。如果環(huán)境是最小化安裝或者某次插件更新時(shí)誤點(diǎn)了禁用就可能出現(xiàn)pipeline 能跑、但頁(yè)面沒有階段視圖的現(xiàn)象。檢查路徑Manage Jenkins - Plugins - Installed plugins搜索pipeline確認(rèn)pipeline-stage-view和pipeline-api這兩個(gè)插件存在且狀態(tài)為已啟動(dòng)。如果某個(gè)插件缺失去 Available 頁(yè)面搜索安裝裝完需要重啟 Jenkins 才能生效。這里有個(gè)容易踩的細(xì)節(jié)pipeline-aggregator是一個(gè)聚合插件它會(huì)把常用 Pipeline 插件一起裝好但如果你手動(dòng)安裝 Jenkins 時(shí)選擇了自定義插件列表或者在離線環(huán)境里做了精簡(jiǎn)安裝聚合插件可能沒有裝全結(jié)果就是 Pipeline 能跑但視圖工具鏈缺胳膊少腿。檢查的時(shí)候別只看有沒有 pipeline要看具體的 stage-view 組件在不在。4.2 升級(jí) Jenkins 或插件后突然消失另一種高頻場(chǎng)景是Jenkins 本身升級(jí)了或者批量升級(jí)了一堆插件之后階段視圖突然不顯示了。這種現(xiàn)象在從老版本 LTS 大跨度升級(jí)時(shí)尤其常見因?yàn)榕f版 stage-view 插件可能依賴的 Web UI 組件在新版本里已經(jīng)被替換渲染邏輯和新的頁(yè)面框架不兼容。遇到這種升級(jí)后消失的情況最先要看的是版本兼容性。一般在 Jenkins 升級(jí)之后插件管理器里會(huì)提示插件需要更新或者存在不兼容警告這時(shí)候不要點(diǎn)一鍵升級(jí)所有插件而是應(yīng)該先看插件的更新日志。比較穩(wěn)妥的做法是備份當(dāng)前 Jenkins 目錄至少備份plugins目錄和config.xml在測(cè)試實(shí)例上升級(jí) Jenkins 和 stage-view 插件跑一個(gè)冒煙 Pipeline Job確認(rèn)階段視圖正常后再同步到生產(chǎn)環(huán)境。如果你已經(jīng)升級(jí)完且視圖消失可以嘗試把pipeline-stage-view插件升級(jí)到與當(dāng)前 Jenkins 版本相匹配的最新版然后重啟。多數(shù)情況下插件的后續(xù)補(bǔ)丁版本會(huì)修復(fù) UI 兼容性問題。如果升級(jí)后仍然不行再考慮查看系統(tǒng)日志里是否有與該插件相關(guān)的 StackTrace。4.3 其他 UI 干擾與檢查順序還有一類極小概率的情況安裝了一些自定義主題插件、CSS 注入插件或者管理員在全局配置里設(shè)置了某些覆蓋樣式結(jié)果把階段視圖的容器區(qū)域隱藏了。這種問題通常在全管理員狀態(tài)下也復(fù)現(xiàn)而且 wfapi 接口返回正常只有 HTML 渲染異常。遇到這類問題我建議的檢查順序是固定的先看 wfapi 是否有數(shù)據(jù)再開 F12 看請(qǐng)求返回碼然后檢查插件列表和版本最后才懷疑主題或前端資源。把這個(gè)順序記牢你就能在幾分鐘內(nèi)把無(wú)法排查變成可定位。不要一上來(lái)就卸載插件那會(huì)把問題搞得更亂。5. 一整套可復(fù)現(xiàn)的排查流程從現(xiàn)象到結(jié)論5.1 開始之前先收集現(xiàn)場(chǎng)信息排查之前先把現(xiàn)場(chǎng)信息整理清楚這一點(diǎn)在團(tuán)隊(duì)協(xié)作時(shí)尤其有用。最少要記錄四樣?xùn)|西Jenkins 版本系統(tǒng)管理 - 系統(tǒng)信息或者直接訪問/api/json查看版本字段關(guān)鍵插件版本插件管理頁(yè)面里搜索pipeline-stage-view和pipeline-api的版本號(hào)Job 類型和配置方式是單個(gè) Pipeline Job、多分支還是共享庫(kù)調(diào)用腳本是寫在配置里還是從 SCM 加載頁(yè)面表現(xiàn)是完全沒有任何階段視圖區(qū)域還是視圖區(qū)域存在但全部灰色還是提示某個(gè)加載錯(cuò)誤。把這些信息寫下來(lái)再對(duì)照下面的檢查表走。很多時(shí)候光是記錄的過(guò)程就能發(fā)現(xiàn)問題——比如你發(fā)現(xiàn)自己根本分不清 Job 類型那大概率就是類型搞錯(cuò)了。5.2 對(duì)照檢查表逐項(xiàng)驗(yàn)證下面這份檢查表是我在實(shí)際排查中反復(fù)用到的按順序執(zhí)行基本不會(huì)漏檢查項(xiàng)操作方式預(yù)期結(jié)果異常時(shí)的指向Job 類型curl -s .../api/json | jq ._class出現(xiàn)WorkflowJob或WorkflowMultiBranchProjectFreestyle 類型需改寫為 Pipeline Job最小化實(shí)驗(yàn)新建簡(jiǎn)單 Pipeline Job 并構(gòu)建能看到階段視圖環(huán)境或插件問題wfapi 數(shù)據(jù)訪問/job/xxx/構(gòu)建號(hào)/wfapi/describestages數(shù)組非空數(shù)據(jù)為空則排查腳本寫法前端請(qǐng)求F12 Network 搜索wfapi返回 200 且有 JSON404 查插件403 查權(quán)限插件列表插件管理頁(yè)搜pipeline-stage-view已安裝且版本匹配缺失或版本過(guò)舊升級(jí)或重裝權(quán)限驗(yàn)證管理員和普通用戶各登錄一次管理員可見用戶不可見時(shí)是權(quán)限問題調(diào)整角色權(quán)限這個(gè)表不是讓你死記硬背而是提醒你排查時(shí)每確認(rèn)一項(xiàng)就把范圍縮小一圈。我自己就是按照先確認(rèn)數(shù)據(jù)存在 - 再確認(rèn)接口正常 - 再確認(rèn)插件完整 - 最后懷疑權(quán)限和緩存這個(gè)思路來(lái)的幾乎沒有失手過(guò)。5.3 最后的殺手锏留一個(gè)冒煙 Pipeline Job處理完這次問題之后我在每個(gè) Jenkins 實(shí)例上都保留了一個(gè)名為sanity-pipeline的最簡(jiǎn)單 Pipeline Job代碼就是那個(gè)hello world模板。每次 Jenkins 升級(jí)、插件批量升級(jí)或者換了新的節(jié)點(diǎn)我都會(huì)先花 30 秒跑一次這個(gè) Job確認(rèn)階段視圖正常了再讓團(tuán)隊(duì)成員切過(guò)去用。這個(gè)小習(xí)慣幫我避開了好幾次看不見階段視圖引發(fā)的深夜告警。因?yàn)樗循h(huán)境是否健康這個(gè)問題變成了一個(gè)按鍵判斷如果冒煙 Job 有視圖環(huán)境就是好的問題在業(yè)務(wù)腳本里如果冒煙 Job 也沒有視圖那就是環(huán)境本身出了問題跟業(yè)務(wù)代碼無(wú)關(guān)。排查起點(diǎn)一旦清晰后續(xù)步驟就快得多。如果你現(xiàn)在正被這個(gè)問題卡住我的建議很直接先別急著懷疑流水線代碼按上面五步走一遍。尤其是那個(gè)最小化復(fù)現(xiàn)實(shí)驗(yàn)成本最低收益最高。跑完之后你基本就能確定問題出在腳本、插件、權(quán)限還是緩存層然后對(duì)癥下藥就好。