v0.1.7

架構

最後更新


本頁以一張圖呈現 QemuRun-pve 各層與 Proxmox 叢集之間的關係,以及本服務在 Go Proxmox 工具中的定位。

系統概覽


graph TB
    Client[客戶端] -->|HTTP / SSE| Gin[Gin 路由 + CORS]
    Gin --> Handler[Handler 層<br/>ALLOW_IPS / 狀態檢查]
    Handler --> Util[Util<br/>VM / 節點查詢]
    Handler --> Service[Service 層]
    Util -->|pvesh| PVE[(Proxmox 叢集 API)]
    Util --> Disabled[.go_qemu_disabled]
    Service -->|qm / pvesh / pvesm| Main[主節點]
    Service -->|SSH root@NODE_x + qm| Remote[遠端節點]
    Service -->|HTTP| Mirror[官方 Cloud Image 鏡像站]
    Service -->|SSH| VM[新 VM]
    VM -->|curl /sh/os_version.sh| Gin
  1. graph TB
  2. Client[客戶端] -->|HTTP / SSE| Gin[Gin 路由 + CORS]
  3. Gin --> Handler[Handler 層<br/>ALLOW_IPS / 狀態檢查]
  4. Handler --> Util[Util<br/>VM / 節點查詢]
  5. Handler --> Service[Service 層]
  6. Util -->|pvesh| PVE[(Proxmox 叢集 API)]
  7. Util --> Disabled[.go_qemu_disabled]
  8. Service -->|qm / pvesh / pvesm| Main[主節點]
  9. Service -->|SSH root@NODE_x + qm| Remote[遠端節點]
  10. Service -->|HTTP| Mirror[官方 Cloud Image 鏡像站]
  11. Service -->|SSH| VM[新 VM]
  12. VM -->|curl /sh/os_version.sh| Gin

分層


層位置職責
進入點cmd/api/main.go載入 .env、檢查 PORT/GATEWAY、掛載 /sh 靜態目錄、啟動 Gin
Configinternal/configCORS 中介層與 /api 路由註冊
Handlerinternal/handler解析參數、ALLOW_IPS 與 VM 狀態前置檢查、選擇純文字/JSON/SSE 回應
Serviceinternal/service所有 qm/pvesh/pvesm/ssh 呼叫、安裝流程、資源配置、SSE 推送
Utilinternal/util叢集 VM/節點查詢、停用清單、ALLOW_IPS 比對
Modelinternal/model請求、回應與 SSE 結構

跨層原則


  • Proxmox CLI 即 API:不呼叫 Proxmox HTTP API,也不保存 token;所有操作都是主節點上的 qm/pvesh/pvesm,或經 SSH 在其他節點執行的 qm
  • 無資料庫:叢集狀態每次即時從 pvesh get /cluster/resources 與 /etc/pve/nodes 讀取;本地只有三個 狀態檔
  • 長時間操作一律串流:安裝、開機、重開、遷移以 SSE 回報每一步,短操作直接回 ok
  • VMID 決定網路:IP 末段等於 VMID,因此不需要 DHCP 或 IP 管理表,見 VMID 與 IP 配置

在 Go Proxmox 工具中的定位


多數 Proxmox VE 的 Go 工具是透過 Proxmox VE HTTP API 運作。Telmate/proxmox-api-go 是該 API 的 Go 客戶端函式庫,Telmate/terraform-provider-proxmox 的 Terraform provider 即建立在它之上。bpg/terraform-provider-proxmox 是 Terraform/OpenTofu provider,幾乎所有操作同樣以 API token 經 Proxmox VE API 執行,只有少數操作需要 SSH。這些工具在你自己的電腦或 CI 上描述 VM,再套用到叢集。
QemuRun-pve 則常駐在叢集主節點,對外提供自己的精簡 REST API:一次 POST /api/vm/install 就會挑選可用的 VMID 與 IP、下載官方雲端映像、在本機執行 qm create 與 cloud-init,並以 SSE 串流回報每個階段,不需要保存 Proxmox API token。

延伸閱讀


模組內部結構、序列圖與 VM 狀態機見 doc/architecture.zh.md。
EN