# 環境變數

本頁列出 QemuRun-pve 讀取的全部環境變數、預設值與未設定時的實際行為。

啟動時以 `godotenv` 載入工作目錄的 `.env`；檔案不存在時只印警告，改讀行程環境變數。啟動階段只檢查 `PORT` 與 `GATEWAY`，其餘變數在被使用時才讀取。

## 必填

| 變數 | 範例 | 用途 | 未設定時 |
|---|---|---|---|
| `PORT` | `8080` | API 監聽埠；也用來組出初始化腳本網址 | 啟動失敗 |
| `GATEWAY` | `192.168.0.1` | VM 網關；前三段作為 VM IP 前綴 | 啟動失敗 |
| `MAIN_NODE` | `pve1` | 服務所在節點名稱 | 所有 VM 操作無法判斷在哪個節點執行；SSH 初始化找不到腳本網址 |
| `NODE_<name>` | `NODE_pve2=192.168.0.12` | 每個節點（含主節點）的管理 IP | 該節點上的 VM 無法操作 |
| `ALLOW_IPS` | `192.168.0.10,192.168.0.20` | 可呼叫寫入端點的來源 IP，逗號分隔；`0.0.0.0` 全部放行 | 空字串會被切成 `[""]`，寫入端點全部拒絕 |
| `ASSIGN_STORAGE` | `local-zfs` | 匯入磁碟與 Cloud-Init 使用的儲存池 | 安裝在「檢查儲存池」步驟失敗 |

## 選填

| 變數 | 預設 | 用途 |
|---|---|---|
| `ASSIGN_IP_START` | `100` | 自動配置 VMID 的下限；`0` 或低於 `100` 時以 `100` 計 |
| `ASSIGN_IP_END` | `254` | 自動配置 VMID 的上限；`0` 或高於 `254` 時以 `254` 計；起訖顛倒時自動交換 |
| `VM_MAX_CPU` | 不限 | 安裝時 vCPU 上限，超過時壓回 |
| `VM_MAX_RAM` | 不限 | 安裝時記憶體上限（MB） |
| `VM_MAX_DISK` | 不限 | 安裝時磁碟上限（GB），大於等於此值時設為此值 |
| `VM_BALLOON_MIN` | 停用 | Balloon 保留記憶體（MB），規則見下節 |
| `VM_ROOT_PASSWORD` | 腳本預設 | 傳給 OS 初始化腳本的 root 密碼；留空時腳本使用內建值 `0123456789` |

數值型變數無法解析成整數時，一律視為未設定。

## Balloon 規則

設定 `VM_BALLOON_MIN` 後，記憶體符合下列條件時會一併加上 `--numa 1` 與 `--balloon`：

| 記憶體（MB） | `--balloon` 值 |
|---|---|
| ≥ 65536 | `49152` |
| ≥ `VM_BALLOON_MIN` + 1024 | 記憶體 − `VM_BALLOON_MIN` |
| 其他 | 不設定 |

安裝與 [`/set/memory`](/zh/api-resources) 共用此規則。

## `.env` 範例

```bash
PORT=8080
MAIN_NODE=pve1
GATEWAY=192.168.0.1
ALLOW_IPS=192.168.0.10,192.168.0.20

NODE_pve1=192.168.0.11
NODE_pve2=192.168.0.12
NODE_pve3=192.168.0.13

ASSIGN_IP_START=100
ASSIGN_IP_END=254
ASSIGN_STORAGE=local-zfs

VM_MAX_CPU=32
VM_MAX_DISK=64
VM_MAX_RAM=32768
VM_BALLOON_MIN=2048

VM_ROOT_PASSWORD=
```

工作目錄中的其他設定檔見 [狀態檔](/zh/state-files)。