架構

本頁以一張圖呈現 QemuRun-pve 各層與 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

分層

層	位置	職責
進入點	`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 配置

延伸閱讀

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