前言¶

用 DSH 的 Web GUI 排查集羣問題時，常見的做法是開着終端敲 kubectl，回頭再把結果貼回對話。kubeconfig 裏的憑證可能是客戶端證書、bearer token、exec 憑證插件（aws / gcloud / azure）或 auth-provider 片段，插件要自己重寫一遍這套邏輯很容易出錯，而且集羣一多就要反覆切換文件和 context。

下面介紹的 atticuswx/dsh-kube-lens 就是爲這件事做的插件。它讓插件側邊欄多一個 Kubernetes 圖標，主區是資源瀏覽器，同一套操作也暴露成 Agent 工具，免去在終端和 Web 界面之間來回切換。

這是什麼¶

一句話定位：通過 kubeconfig 訪問集羣的 DSH 插件，把 kubectl 包裝成面板和 Agent 工具，默認只讀。

• 維護者：atticuswx
• 許可證：MIT
• 版本：代碼裏標註爲 0.3.0（package.json 的 version 字段，以及 dsh plugin add 支持的 v0.3.0 tag）
• 分類：admin-security 方向，面向集羣讀操作與權限控制
• 不引入額外依賴：所有集羣訪問都走宿主機上的 kubectl，插件本身不重寫憑證邏輯

需要先明確一點：它依賴宿主機已有 kubectl（Rancher Desktop 通常在 ~/.rd/bin/kubectl），以及支持 Web client bundle 的 DSH。包裏沒有構建步驟，client.js 由瀏覽器直接加載。

安裝與啓用¶

從 GitHub 安裝：

dsh plugin --profile web add github:atticuswx/dsh-kube-lens

裝完刷新頁面，側邊欄會出現 Kubernetes 圖標，點開就是集羣瀏覽器。想鎖定版本，在地址後面加 tag：

dsh plugin --profile web add github:atticuswx/dsh-kube-lens#v0.3.0

本地開發（改代碼即時生效）：

git clone https://github.com/atticuswx/dsh-kube-lens.git ~/dsh-plugins/dsh-kube-lens
dsh plugin --profile web add ~/dsh-plugins/dsh-kube-lens

插件掛到 --profile web 上，意味着只有 Web GUI 會有這個面板；Agent 工具在同一個宿主進程裏可用。

裝完之後有什麼¶

• 側邊欄出現 Kubernetes 圖標，點開是集羣瀏覽器。
• Agent 多出 6 個只讀工具：kube_contexts、kube_get、kube_describe、kube_logs、kube_events、kube_diagnose。
• 默認只讀。寫操作關閉時，kube_write 工具和麪板上的寫按鈕都不出現。

配置¶

配置寫在 cordis.patch.yml 的 config 裏，改完後需要重新加載插件。

如果不想動配置文件，面板右上角的 kubeconfig 按鈕可以隨時增刪 kubeconfig，改完立即生效。幾個坑 README 裏寫得很具體：每個 context 只用它所屬的那個文件，不做跨文件按名合併，原因是兩個 kubeconfig 常常都把 cluster 叫作 kubernetes，kubectl 合併時只保留第一個，另一個 context 會被指向錯誤的 API server，表現爲 Unauthorized。列表爲空時回落到 $KUBECONFIG，再回落到 ~/.kube/config。保存位置是 $DSH_HOME/kube-lens.json（默認 ~/.dsh/kube-lens.json），可以手改，自定義的顯示名也存在這裏，按 kubeconfig 文件記錄，換路徑後不會錯位。

瀏覽與搜索¶

面板的交互按集羣瀏覽器的常見習慣做，幾條值得記的：

• 頂部顯示 kubeconfig 文件名（如 prod-cluster），而不是那串 123456789012345678-… 的 context id；hover 能看到完整 context、server 和文件路徑。
• 一個過濾條同時管命名空間和搜索，左邊是命名空間觸發器（「全部命名空間」或某個具體命名空間），右邊直接過濾資源名稱；/ 聚焦輸入框，Esc 清空或關閉菜單。
• 「只看異常」按 READY / STATUS 列篩選：未就緒（0/N）或處於 CrashLoopBackOff、ImagePullBackOff、Pending、Error 等狀態的對象，用來第一時間定位問題實例。
• 計數顯示爲 匹配數/總數，篩選是純客戶端的，不會因爲輸入而反覆請求集羣，切換命名空間纔會重新請求。

鍵盤方面，點擊列頭在 升序 → 降序 → 取消 之間循環，CLUSTER-IP、PORT(S)、CAPACITY 不可排序；表格中 ↑ / ↓ 移動行焦點，Home / End 跳首尾行，Enter 或 Space 打開詳情；詳情頁用 Esc 或左上角返回回到列表，焦點落回進入詳情的那一行。

詳情頁：YAML 與日誌¶

詳情頁有兩個 tab：YAML 和 日誌（0.3.0 新增）。

YAML tab 的編輯器是 CodeMirror 6（@codemirror/lang-yaml），打包在插件的 viewer.js 裏，不走 CDN，離線可用；只在第一次打開時按需加載，加載失敗自動退回只讀的 <pre> 視圖。支持語法高亮、行號、摺疊、括號匹配、撤銷/重做、自動換行和 ⌘F 查找，另有複製、下載爲 <kind>-<name>.yaml、格式化（保留註釋）、還原四項操作。編輯時實時做 YAML 語法校驗，錯誤行內畫波浪線，有未保存改動時 tab 上出現小黃點。

「保存到集羣」只在 allowWrites: true 時可用，點擊後出現顯示 kubectl apply -f - 的確認條，確認後才執行。三種情況自動只讀，避免把脫敏或不完整的內容寫回集羣：Secret、清單超過 24k 字符被截斷、讀取失敗。

日誌 tab 通過 SSE 持續接收 kubectl logs -f --timestamps 的輸出，默認滾底，向上翻看時暫停並顯示「回到最新」。搜索框高亮全部匹配，Enter / Shift+Enter 跳到下一個/上一個。支持 200–2000 行 tail、複製全部、下載帶時間戳的原始日誌；多容器 Pod 會列出容器 tab，有重啓時多出「上一次運行」快照。連接斷開後自動重連，用上一次時間戳 --since-time 補漏並按時間戳去重，只保留最近 5000 行。離開該 tab 會斷開 kubectl 子進程，避免後臺一直 tail。

寫操作與 Secret 保護¶

配置裏 allowWrites: true 之後：

• kube_write 的每次調用都先向用戶發一次性審批，和 bash 工具的審批同一個通道；拒絕、取消、通道不可用，一律不執行。
• 面板上的滾動重啓、擴縮容、刪除 Pod 先彈確認框，再走 /kube-lens/api/write。
• 詳情頁 YAML 的「保存到集羣」先出現確認條，再走 /kube-lens/api/apply；服務端還會再次檢查 allowWrites、拒絕 Secret、拒絕一個清單裏出現多個頂層 kind。

Secret 的處理是獨立的一層：Secrets 的內容從不返回，kube_get 的 YAML 和麪板 YAML 頁對 Secret 只顯示 type 和鍵名，面板 YAML 頁對 Secret 強制只讀，保存接口也會拒絕。日誌、事件、清單照常返回。對一個面向運維場景的插件來說，這條策略比「先讀出來再說」更省事——誤貼 secret 到對話的風險從一開始就不存在。

Agent 工具與 kube_diagnose¶

六個工具都是對同一套 kubectl 調用的封裝。其中 kube_diagnose 的設計值得單獨講：一次調用返回容器狀態、重啓次數、上次退出碼與終止原因、調度失敗事件、Service 的 Endpoints 覆蓋、上一次運行和當前的日誌尾巴，並給出結論化的 findings。

判斷規則是啓發式，每條結論都附證據：

• ImagePullBackOff / ErrImagePull → 鏡像或倉庫憑證
• CrashLoopBackOff → 重啓次數 + 上次退出碼
• OOMKilled → 內存 limit
• CreateContainerConfigError → 引用的 ConfigMap/Secret
• Pending + FailedScheduling → 調度器原話
• Running 但未 Ready → 就緒探針
• Service 無 Endpoints → 區分「selector 打錯」和「Pod 不 Ready」
• Node 的 Ready / MemoryPressure / DiskPressure / PIDPressure

對 Agent 工作流來說，這個輸出格式比直接扔一段 kubectl describe 更容易被下一步動作消費。

已知邊界¶

• 只實現 Pod / 工作負載 / Service / Node 的深度診斷；其它資源回退到 kubectl describe。
• 還沒有 exec、port-forward；YAML 保存走 kubectl apply，只在 allowWrites: true 時出現，並且需要面板確認。
• 集羣不可達時，工具返回「集羣不可達 + server 地址 + 下一步」，而不是 kubectl 的原始堆棧。

適用場景與注意¶

適合已經在用 DSH Web GUI、希望 Agent 能直接讀集羣狀態再做判斷的場景，尤其是集羣數量不多、已有 kubectl 環境的團隊。診斷工具對 Pod / Service / Node 這幾類資源比較有針對性，其它資源只是 describe 轉發，不要指望它做全套審計。

安裝前照例注意兩點：插件以當前 dsh 進程的權限運行，等價於該進程能訪問你配置的 kubeconfig 裏的全部集羣，所以裝之前先過一遍源碼（倉庫文件列表裏已列出 index.js、kube.js、diagnose.js、cordis.patch.yml 等）和 MIT 許可證；另外確認宿主機的 kubectl 位置可用，Rancher Desktop 用戶如果 PATH 裏沒有，可以顯式配置 kubectlPath。

項目還很早期，公開倉庫的星標數據很少，主要是作者個人維護，遇到問題傾向於在倉庫 Issues 裏反饋。

小結¶

dsh-kube-lens 的價值在於把「瀏覽器裏看集羣」和「Agent 讀集羣做診斷」合成一處，並且只做了一件事——用 kubectl 已有的憑證處理能力，把只讀瀏覽做透，寫操作一律收窄到顯式開關加逐次審批後面。目錄頁在 https://www.skillhub.cn/plugins/atticuswx/dsh-kube-lens ，源碼在 https://github.com/atticuswx/dsh-kube-lens 。