文件
首頁 GitHub

架構

本頁說明 go-pve-qemu API 的執行期分層與邊界。

系統概覽

graph TB
  Client[HTTP 用戶端] -->|HTTP / SSE| Gin[GIN 路由]
  Gin --> Handler[Handler]
  Handler --> Service[Service]
  Service --> Util[Util]
  Service -->|qm / pvesh| Main[Proxmox 主節點]
  Service -->|SSH + qm| Remote[遠端節點]
  Service -->|下載 qcow2| Images[Cloud 映像來源]
  Main --> VM[虛擬機]
  Remote --> VM

cmd/api/main.go 的可執行程式會載入環境變數、建立 Gin engine、掛載 config.CORS、建立 service.Service，並以 config.NewRoutes 註冊路由。

分層

分層 位置 職責
進入點 cmd/api/main.go 程序啟動、環境載入、Gin 設定
Config internal/config 路由註冊與 CORS 政策
Handler internal/handler HTTP 解析、驗證、JSON／純文字／SSE 回應
Service internal/service VM 生命週期工作流與 Proxmox 指令執行
Model internal/model 請求、VM、節點、回應與 SSE 資料型別
Util internal/util 叢集清單、VM ID、IP 與使用者輔助函式

請求路徑

  1. 用戶端呼叫 /api 下的 Endpoint。
  2. Gin 套用 CORS middleware 並派送至 handler。
  3. Handler 解析 VM ID 或 JSON body，呼叫 service 層。
  4. Service 依 VM 所在節點選擇本機 qm 或 SSH 派送。
  5. 指令結果以純文字或 JSON 回傳；長時間操作則以 SSE 發送事件。

叢集路由

Service 會先判斷 VM 所在節點。主節點指令直接執行；遠端節點則以 SSH options 組成 root@<node-ip> qm ... 指令。這讓 REST 介面不需暴露叢集拓撲。

佈建工作流

Service.Install 會完整執行：配置 ID、依 gateway 推導靜態 IP、驗證資源、解析及下載 cloud image、建立並設定 VM、視需要遷移、等待 SSH、套用初始化，再重啟並驗證。

資料契約

model.Config 是佈建請求契約，包含 VM 身分、目標節點、OS/version、CPU、磁碟、RAM、網路與 SSH 設定。model.SSE 以 step、status、message 表示串流進度；model.VM 與 model.Node 支援叢集清單回應。

請參閱核心概念了解生命週期行為，以及 API 參考了解 Endpoint 契約。

EN