# 架構

本頁以一張圖呈現 QemuRun-pve 各層與 Proxmox 叢集之間的關係。

## 系統概覽

```mermaid
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` 讀取；本地只有三個 [狀態檔](/zh/state-files)
- **長時間操作一律串流**：安裝、開機、重開、遷移以 [SSE](/zh/sse-events) 回報每一步，短操作直接回 `ok`
- **VMID 決定網路**：IP 末段等於 VMID，因此不需要 DHCP 或 IP 管理表，見 [VMID 與 IP 配置](/zh/vmid-ip-allocation)

## 延伸閱讀

模組內部結構、序列圖與 VM 狀態機見 [doc/architecture.zh.md](https://github.com/pardnchiu/QemuRun-pve/blob/main/doc/architecture.zh.md)。