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