專案分享

jt-proxense：給 Proxmox VE 的科幻風戰情室看板

Jason Cheng 2026.08.04

Ceph jt-proxense Proxmox VE PVE

本文目錄

從看板長成控制台
六種檢視
認證、權限與稽核
客體機操作
機群維運功能
設定與語言
安裝
反向代理與 HTTPS
Telegraf 補充指標
使用前務必注意
結論
參考資料

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

很多年前某次社群研討會，有個美術設計兼前端開發者說「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）

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

矩陣檢視底下還有幾種不同的呈現方式：

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

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

雷達檢視（Radar）

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

儲存檢視（Storage）

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

Ceph 檢視

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

快速鍵

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 清除，且不會動到密碼

使用者管理可以完全在網頁介面完成：建立本機帳號、依叢集與客體機樣式授予角色、註冊或重設 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 延遲。

ZFS 儲存集區維運

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

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

拓樸是畫出來的，不是列出來的：從儲存集區到 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，把認證與客體機控制都維持預設關閉即可，這樣的風險面最小。要開哪一層是你自己決定的。