架構
最後更新
本頁以一張圖呈現 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- 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
分層
| 層 | 位置 | 職責 |
|---|---|---|
| 進入點 | cmd/api/main.go | 載入 .env、檢查 PORT/GATEWAY、掛載 /sh 靜態目錄、啟動 Gin |
| Config | internal/config | CORS 中介層與 /api 路由註冊 |
| Handler | internal/handler | 解析參數、ALLOW_IPS 與 VM 狀態前置檢查、選擇純文字/JSON/SSE 回應 |
| Service | internal/service | 所有 qm/pvesh/pvesm/ssh 呼叫、安裝流程、資源配置、SSE 推送 |
| Util | internal/util | 叢集 VM/節點查詢、停用清單、ALLOW_IPS 比對 |
| Model | internal/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。