佈建流程
最後更新
本頁逐階段說明
POST /api/vm/install 從收到請求到 VM 可 SSH 登入之間做了什麼。階段總覽
每個步驟的 SSE 事件
step 欄位格式為 <階段> > <步驟>。| 階段 | 步驟 | 動作 |
|---|---|---|
preparation | checking VMID | 未指定 id 時執行 VMID 配置;指定時直接使用,不檢查是否已被占用 |
assigning IP | GATEWAY 前三段 + VMID,加 /24 | |
validating CPU and RAM | CPU ≤ 0 → 1;超過 VM_MAX_CPU 則壓回。RAM < 512 → 512;超過 VM_MAX_RAM 則壓回 | |
validating disk size | 去掉結尾 G 解析數字;< 16 → 16G;≥ VM_MAX_DISK → 上限值 | |
setting default config values | 名稱加上 -<vmid>、填入預設使用者與密碼 | |
checking storage pool | pvesm status 確認 ASSIGN_STORAGE 啟用中且類型為 dir/zfspool/lvmthin/nfs | |
OS preparation | getting OS image | 依 os/version 決定映像網址 |
validating OS image URL | 以 HEAD 請求確認 200,逾時 15 秒 | |
downloading OS image | 下載到 /tmp;檔案已存在則略過(using OS image) | |
SSH preparation | checking SSH key | 主節點找不到公鑰時以 ssh-keygen -t ed25519 產生 |
VM creation | creating VM | qm create,CPU 類型取 叢集基準,偵測失敗時用 kvm64 |
importing disk image | qm importdisk 到 ASSIGN_STORAGE | |
VM initialization | initializing configuration | 依序 qm set:SSH 金鑰、密碼、--ciupgrade 0、OS tag、scsi0、Cloud-Init 磁碟、開機順序,qm resize 至目標大小(失敗重試 3 次、間隔 5 秒),最後設定 ipconfig0 |
migrating VM | 請求帶 node 時才執行 qm migrate --with-local-disks | |
waiting for ready | 開機後每 5 秒嘗試 SSH,最多 60 次 | |
SSH initialization | 在 VM 內執行 OS 初始化腳本,輸出逐行轉成 SSE | |
rebooting VM | qm reboot 後再次等待 SSH 就緒 | |
finalizing | 輸出總耗時、VMID、IP、使用者 |
qm create 參數
| 參數 | 值 |
|---|---|
--cores | 請求的 cpu(已套用上下限) |
--cpu | 叢集基準,或 kvm64 |
--memory | 請求的 ram(已套用上下限) |
--scsihw | virtio-scsi-pci |
--ostype | l26 |
--agent | 1 |
--net0 | virtio,bridge=vmbr0 |
--serial0 | socket |
--numa / --balloon | 依 Balloon 規則 |
--ciupgrade 0 關閉 Cloud-Init 開機時的套件升級,避免與初始化腳本搶套件鎖。失敗處理
| 失敗位置 | 處理 |
|---|---|
準備、映像、SSH 金鑰、qm create | 送出 error 事件後結束,不留下 VM(尚未建立或建立失敗) |
importing disk image、initializing configuration、SSH initialization | 強制停止並 qm destroy --purge --skiplock 清除半成品 VM |
| 遷移、開機、重開指令失敗 | 直接結束,VM 保留在叢集中 |
| 等待 SSH 逾時 | 送出 error 事件後結束,VM 保留,可登入節點排查 |
不論成功或失敗,Handler 最後都會送出
event: close。映像快取
下載檔案以版本命名存放在
/tmp(例如 /tmp/debian-12-generic-amd64.qcow2),之後相同版本的安裝直接重用。上游映像更新後若要取得新版,需手動刪除該檔。