2026年8月4日 星期二

[專案分享] jt-proxense：給 Proxmox VE 的科幻風戰情室看板

 


身為工程師，一直以來我對系統介面都是實用優先，對酷炫的動畫效果從不認為重要。直到我遇上這幾件事。

很多年前某次社群研討會，有個美術設計兼前端開發者說「Proxmox VE 介面不好看」。

接著是多位甲方承辦人員，無奈地說「我們也不在意介面，但是需要有酷炫的東西給不懂的長官看」。

然後是多位客戶的 IT 主管，緩緩坐下、長嘆一聲說「你幫我們弄了 Grafana PVE 看板，長官還是覺得不夠滿足」。

既然如此，我來搞一個畫面科幻風格又有酷炫動畫效果的套件，放在客戶的戰情室螢幕上不就搞定了嗎？

這就是 jt-proxense 的由來，目前版本 v0.9.4，以 Apache 2.0 授權釋出。










從看板長成控制台


先說明一件事：我最初在社群發布時，它只能做使用狀況檢視，純看板、不能操作，當時我寫的是「日後會逐步加入可管理操作的功能」。

後來一路做下去，現在已經不只是看板了。從 v0.2 加入認證與稽核、v0.3 加入客體機控制，一直到 v0.4 至 v0.8 的機群維運功能，它變成一個帶身分驗證與稽核的控制台，只是外觀仍然維持那個賽博龐克風格。

所以這篇會分兩段講：先講當初那些「給長官看」的檢視畫面，再講後來長出來的維運功能。

還有一點要先講清楚：所有進入頁面、轉場、操作都搭配大量動畫，這些用截圖是傳達不出來的，專案首頁上有一段展示影片，建議直接去看。








六種檢視


同一份即時狀態，六種不同的看法，可以用快速鍵直接切換。這是專為戰情室設計的，哈。

看板檢視（Dashboard）


全域總覽，支援多個叢集與獨立節點，顯示資源錶、基礎架構總量與各叢集的健康狀況。就是本文的首圖。


節點檢視（Nodes）


節點的效能採用心電圖效果呈現，CPU、記憶體、I/O 都畫成即時波形。擺在戰情室效果應該更讚。

節點檢視：每個節點的效能以心電圖波形即時呈現


矩陣檢視（Matrix）


所有客體機以色塊呈現其狀態，例如正在備份或遷移，遷移時還會用線條連接到目的地。可依狀態篩選、依負載排序、依節點分組，密度也可以調整。

矩陣檢視：每台客體機一個色塊，VM 與 CT 分別標示


矩陣檢視底下還有幾種不同的呈現方式：
  • 表格檢視
    可排序、可篩選、欄位可自選。工程師比較習慣這種檢視方式
     
  • 縮圖檢視
    每台執行中的客體機都顯示即時畫面
     
  • 熱區圖檢視
    一眼看出負載熱點
     

矩陣檢視的縮圖模式：每台客體機的即時畫面預覽

這個縮圖功能實作上花了點工夫：QEMU 走精簡版的 RFB 3.8 客戶端取畫面，LXC 則是走 termproxy 搭配 vt100 模擬器，所以容器的卡片顯示的是真實的 shell 輸出，而不是一片黑。點任一張卡片可以放大，還有 CRT 雜訊的載入效果。


雷達檢視（Radar）


異常偵測用的雷達。越外圈且客體機為紅色，表示使用負載越高，點選可彈出卡片顯示細節。突波、超過門檻、節點離線都會跳進視野。

雷達檢視：異常掃描進入視野，越外圈負載越高


儲存檢視（Storage）


顯示所有儲存區的用量，並以顏色區分不同的儲存系統類型。另外還有 Treemap 模式，方便一次看出所有客體機的磁碟大小比例，容量壓力會直接變成看得見的面積。

儲存檢視的 Treemap：面積代表容量，顏色代表是否開機中


Ceph 檢視


觀看 Ceph 分散式儲存的狀況，包含叢集拓樸、即時 IOPS、OSD 與 pool 的狀態，以及回復進度，全部畫在同一張圖上。

Ceph 檢視：拓樸、IOPS 與 OSD 延遲


快速鍵


  • D　看板檢視
  • N　節點檢視
  • M　矩陣檢視
  • R　雷達檢視
  • S　儲存檢視
  • C　Ceph 檢視
  • Space　暫停或繼續動畫
  • Ctrl+S　開關設定面板








認證、權限與稽核


既然後來加入了可以改變狀態的操作，身分驗證與稽核就不能省。這一整層預設關閉，要用才開，開了之後行為與 v0.1 純看板時期一致。

  • 認證
    Argon2id 密碼雜湊、12 小時滑動 session、可選 PAM 後端直接用系統帳號登入、TOTP 雙因素認證附 8 組備用碼，並有依來源 IP 的登入速率限制（5 分鐘內失敗 5 次）
     
  • 角色與範圍
    三種角色 viewer、operator、admin，權限可以同時依叢集與客體機樣式界定，支援名稱萬用字元（如 web-*）與標籤（如 tag:prod），比對到多筆時取權限最高者
     
  • 稽核記錄
    唯附加（append-only）的 SQLite 稽核軌跡，登入、角色變更、設定修改、客體機操作全部記錄，可在 /audit 瀏覽、依日期篩選、匯出 CSV，保留期間可設定
     
  • 緊急復原 CLI
    萬一把自己鎖在門外，jt-proxense auth disable 在服務沒啟動的情況下也能執行，可離線重設密碼、清除遺失的驗證器、修正壞掉的設定；被登入速率限制擋住時用 jt-proxense unlock 清除，且不會動到密碼
     

使用者管理：RBAC 角色授予與 2FA 設定

使用者管理可以完全在網頁介面完成：建立本機帳號、依叢集與客體機樣式授予角色、註冊或重設 TOTP、重新產生備用碼、停用或刪除。後端支援本機、PAM 與 LDAP，而且每一個會改變狀態的動作都會落進稽核記錄。








客體機操作


這一層一樣預設關閉，要在設定檔把 vm_control.enabled 設為 true 才會啟用。

  • 生命週期操作
    VM 與 LXC 的啟動、停止、關機、重開、暫停、繼續
     
  • 批次操作
    單一請求最多 100 個 vmid，VM 與 CT 可以混合
     
  • 分級確認
    強制停止與遷移這類動作需要 admin 確認
     
  • 叢集內遷移
    VM 走線上遷移，容器則是離線遷移後重啟
     
  • 跨叢集遷移精靈
    會自動偵測來源 VM、挑選目標叢集端點、取得 TLS 指紋，並排出磁碟與網卡的對應關係，附驗證、試跑預檢、線上與離線模式、頻寬限制。僅限 admin，且受 PVE API 限制只支援 QEMU
     

遷移失敗時會跳出鎖定復原提示，直接給你可以複製貼上的 qm unlock 指令，這個小細節在實際維運時蠻有感的。








機群維運功能


從管一個叢集，到管一整片機器。這部分是 v0.4 到 v0.8 陸續加上去的，講的是日常維運要做的事，而不只是看著它。

健康監測與 Corosync


一頁彙整所有叢集的主動檢查：節點離線、CPU 與記憶體過高、儲存空間將滿、Ceph 警告、憑證到期、待更新套件、HA 與複寫狀態。

另外還有從記錄推導的硬體發現，會掃描各節點的 syslog 找出 ECC、MCE、OOM、磁碟 I/O 錯誤、檔案系統毀損等徵兆。Corosync 則有獨立面板，顯示 quorum、票數、各節點的連結狀態與 ring 延遲。

健康監測：主動檢查彙整與 Corosync ring 狀態


ZFS 儲存集區維運


這一段是我自己覺得最實用的。Proxmox VE 原生的 WebUI 可以建立儲存集區，然後就把你丟在命令列前面，之後所有維護都得自己下指令。這個功能補的就是後面那一半。

  • 更換磁碟
    包含開機磁碟所需的 ESP 處理
     
  • 擴充
    新增 vdev、加入 log、cache、special 裝置，以及 RAIDZ 線上擴充
     
  • 多 vdev 建置精靈、scrub 與 TRIM
     
  • 影響範圍檢視
    明確列出這個儲存集區掛掉會連帶影響哪些 PVE 儲存與客體機
     

ZFS 儲存集區：拓樸用畫的不是用列的，集區到 vdev 到個別磁碟

拓樸是畫出來的，不是列出來的：從儲存集區到 vdev 到個別磁碟，標示 HDD、SSD、NVMe，並用冗餘點數顯示這一組還能再壞幾顆。

安全性上有兩個設計值得一提：讀取一律走 PVE API，不用 SSH、不動節點，只有維護動作才需要 SSH；而且每個動作都會先用 ZFS 自己的 dry run 預覽一次，再要求你輸入儲存集區名稱確認。像更換開機磁碟這種長時間作業，resilver 進度是記在伺服器端追蹤的，關掉分頁再回來還在。


滾動式主機升級


批次協調器，每台主機依序執行：疏散客體機、apt dist-upgrade 全自動升級、admin 確認後重開機、可選擇遷移回來。

主機升級：滾動批次協調器與即時狀態板

疏散有三種模式（自動、手動、原地），並且是 Ceph 感知的：會先設 noout，並在切換到下一台主機之前等待所有 PG 回到 active+clean。狀態板會即時標示出任何失敗的節點。


備份排程


可以讀取與管理叢集層級的 vzdump 排程工作，也可以從對話框直接發動一次性備份。

如果目標是 Proxmox Backup Server，介面會自動感知：壓縮選項會消失（因為 PBS 本身就做去重），並改為顯示 PBS 專屬的選項，例如註記範本、保護旗標、失敗時寄信。每台客體機也有各自的備份歷史，可以還原與驗證。


其他維運功能


  • 儲存內容瀏覽
    點任何檔案層級的儲存，依內容類型分頁顯示（備份、ISO、CT 範本、Snippets、匯入、磁碟映像、CT root），而且只顯示該儲存實際有的分頁。可排序、可搜尋，刪除會留稽核。區塊層級的儲存（RBD、LVM、ZFSpool）則只提供列表檢視
     
  • 匯出成 OVA 或 Hyper-V
    把 QEMU VM 轉成 VMware 與 VirtualBox 用的 OVA，或 Hyper-V 的 VHDX。透過 SSH 在節點上執行，並有內部工作佇列，所以轉檔不會因為關掉瀏覽器分頁就中斷。附工具自動安裝與版本檢查、空間預檢、串流下載，產出檔 24 小時後自動清除
     
  • 節點維運
    每個節點的網路介面檢視（網卡、bridge、bond 的連結與速率）、NTP 與 chrony 設定、磁碟與 SMART、服務、系統記錄
     
  • SSH 金鑰散布
    手動授權一台節點之後，可以透過節點之間的 SSH 一鍵把主機金鑰散布到其餘節點
     
  • 工作記錄
    叢集操作記錄與即時明細
     
  • 內建主控台
    瀏覽器內的 noVNC framebuffer，也可以在矩陣檢視按右鍵直接對客體機操作
     








設定與語言


設定頁可以調整介面、告警條件等等，也可以方便地開關要檢視的叢集與獨立節點。叢集連線的新增與移除都在這裡完成，不需要手動編輯 config.yaml，存檔後會自動熱重載。

內建英文與繁體中文兩種語言，可即時切換。

同一套介面切換成繁體中文

告警門檻的預設值是 CPU 警告 80%、危險 95%，輪詢間隔預設 2 秒，這些都可以調整。








安裝


一行指令，僅支援 Linux，需要 Python 3.10 以上與 sudo 權限。Debian、Ubuntu、RHEL、Rocky、Arch、openSUSE 都可以。 

curl -fsSL https://raw.githubusercontent.com/jasoncheng7115/jt-proxense/main/install.sh | sudo bash

安裝程式會建立專用的 jt-proxense 系統使用者、安裝 Python 相依套件、部署 systemd unit、產生一組一次性的 admin 密碼，然後在 8098 埠啟動服務。

安裝完成後開 http://<你的伺服器>:8098/，用安裝程式印出的一次性密碼登入，再到「設定」的叢集頁新增 PVE 叢集即可。

更新與移除


更新就是重跑一次安裝指令，這個動作是等冪的，設定與資料都會保留。移除則是： 

curl -fsSL https://raw.githubusercontent.com/jasoncheng7115/jt-proxense/main/uninstall.sh | sudo bash

移除會把服務、程式與資料完整清掉，不可回復，執行時需要輸入 remove 確認。如果日後可能還要還原，請務必先匯出設定。


搬遷到另一台主機


# 舊主機：匯出成單一加密包（設定、資料庫、金鑰）
sudo jt-proxense export-config /root/jt-proxense.enc

# 新主機：先安裝，再匯入
sudo systemctl stop jt-proxense
sudo jt-proxense import-config /root/jt-proxense.enc --force
sudo systemctl restart jt-proxense

請注意這個加密包裡面含有主金鑰與完整資料庫，務必妥善保管，匯入完成後請刪除。


建立 PVE API Token


在每個 PVE 叢集的節點上建立一個唯讀的監控帳號與 token： 

pveum user add monitoring@pve
pveum user token add monitoring@pve mon --privsep=0
pveum aclmod / -user monitoring@pve -role PXEAuditor

把回傳的 token 值填進 jt-proxense 即可。PVEAuditor 是唯讀角色，純看板用途給到這裡就夠了。

每個叢集可以設定多個節點並排定優先序，數字小的優先，達成 API 故障切換：某台節點連不上時會自動換下一台。








反向代理與 HTTPS


內建的伺服器只提供純 HTTP，正式環境務必在前面掛一層反向代理做 TLS 終結。建議的做法是：把 jt-proxense 綁在 127.0.0.1，HTTPS 交給 nginx，登入則沿用程式本身的認證。 

server {
    listen 443 ssl http2;
    server_name proxense.example.com;

    ssl_certificate     /etc/letsencrypt/live/proxense.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/proxense.example.com/privkey.pem;

    client_max_body_size 100M;

    location / {
        proxy_pass         http://127.0.0.1:8098;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection "upgrade";
        proxy_set_header   Host $host;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
        proxy_buffering    off;
    }
}

設定完記得把 8098 埠在防火牆擋掉，只留 80 與 443。這裡有三個地雷要注意：

  • 必須掛在根路徑
    程式不支援掛在子路徑底下
     
  • 請勿再疊 nginx basic-auth
    登入、session、MFA、稽核與角色都由程式本身處理，再疊一層只會互相打架
     
  • noVNC 需要關閉緩衝
    主控台的 /api/console/ 路徑要設 proxy_buffering off 並拉長 proxy_read_timeout（建議 86400s），否則畫面會卡住
     








Telegraf 補充指標


PVE API 提供的指標比較粗，如果想要更細的主機資料，例如各行程的 CPU、溫度感測器、SMART、IPMI，可以走 Telegraf 這條路。

jt-proxense 內建一個 InfluxDB v2 line-protocol 接收器，在 /api/v2/write 收資料，需 token 驗證。在設定檔啟用之後，它會獨立在 8086 埠監聽，就算這個接收器掛掉也不會影響主畫面。

接著在每台 PVE 主機裝 Telegraf，把 outputs.influxdb_v2 指向 jt-proxense 即可，收到的資料會與 API 輪詢來的指標一起呈現。








使用前務必注意


  • 這不是 Proxmox 官方產品
    與 Proxmox Server Solutions GmbH 沒有任何附屬、背書或支援關係。Proxmox 與 Proxmox VE 是該公司的商標
     
  • 會執行改變狀態的操作
    客體機電源、遷移、備份、主機升級、NTP 與儲存與防火牆設定、SSH 金鑰散布等動作，誤用可能造成停機或資料遺失。請務必先在非正式環境測試
     
  • 部分功能需要免密碼的 root SSH
    從 jt-proxense 主機到各 PVE 節點。這條通道的安全性由你自己負責，請審慎評估
     
  • 合規責任自負
    部署與操作是否符合貴公司政策與相關法規，請自行確認
     

另外補充一點：純看板用途的話，只要給唯讀的 PVEAuditor token，把認證與客體機控制都維持預設關閉即可，這樣的風險面最小。要開哪一層是你自己決定的。








結論


這個專案的出發點其實有點好笑：為了解決長官覺得介面不夠酷炫的問題。但做著做著，我發現戰情室看板這個定位本身是有價值的。

多叢集的即時狀態、心電圖式的節點波形、遷移時客體機之間的連線動畫，這些在跟非技術背景的人溝通系統現況時，確實比一張表格有效得多。而快速鍵切換、雷達異常掃描這些設計，實際盯著螢幕的時候也真的好用。

後來加上去的維運功能則是另一回事了。其中我認為最實用的是 ZFS 儲存集區維運：PVE 原生介面只讓你建立儲存集區，換磁碟、加 vdev、RAIDZ 擴充這些事情之後都得回命令列，這個功能把後半段補起來了，而且讀取階段完全不碰 SSH。

專案以 Apache 2.0 授權釋出。需要說明的是，這是我個人維護的專案，不接受 Pull Request，但有問題或功能建議歡迎開 issue。

最後再提醒一次：截圖傳達不出動畫效果，想看實際運作請到專案首頁看展示影片。








參考資料



發佈：
標籤： , , , , , , , , ,