Proxmox VE 操作參考 (版本 9.1.2)
節點、來賓和服務可能在下線、無法連線或操作中途消失。永遠不要假設某個元件是正常運作的：請重新查詢真實狀態、在超時限制內重試，並優雅降級。有關自我修復模式，請參閱 bitranox:coding-resilience。
1. 叢集配置（自動偵測）
| 檢查項目 | 命令 |
|---|---|
| 環境 | pveversion --verbose (完整元件版本：kernel, pve-manager, corosync, qemu-server) |
| 節點 | pvecm nodes (計數、名稱、ID) / pvecm status (IP、仲裁、傳輸、連結狀態) |
| 仲裁 | pvecm status -- 檢查「Quorate」欄位。門檻值：floor(總節點數/2) + 1 |
| API 存取 | pvesh (本機 CLI), pveproxy (HTTPS :8006), REST API。腳本化處理請使用 --output-format json |
| 儲存 | pvesm status (作用中儲存設備) / cat /etc/pve/storage.cfg (完整配置) |
| 網路 | pvesh get /nodes/{node}/network --output-format json / cat /etc/network/interfaces |
| 訂閱 | pvesubscription get (檢查狀態) / pvesubscription set <key> (套用金鑰) |
2. 安全協定
| 規則 | 詳細說明 |
|---|---|
| 無破壞性批次操作 | 影響超過 1 個節點的命令（重新啟動、關機、大量 VM 停止）需要明確的使用者確認。 |
| 仲裁檢查 | 在節點重新啟動/維護前：pvecm status。如果 (current - 1) < floor(total/2) + 1 -- 中止。在 2 節點叢集上，檢查 QDevice。 |
| 先備份 | 在 VM 配置變更或升級前，驗證備份是否存在：pvesm list {storage} --content backup |
| 不要強制刪除 | 在未驗證資源 ID 的情況下，絕不使用 --purge 或 --force：qm config {vmid} 或 pct config {vmid} |
| HA 狀態 | 在 HA 資源變更前：ha-manager status -- 確認沒有正在進行中的遷移或圍籬操作。 |
| 網路變更 | 始終先進行試運行：ifreload -a -n (ifupdown2 沒有 --test)。絕不要在承載來賓流量的橋接器上執行 ifdown。遠端套用及 DHCP/bond/WLAN 陷阱：references/host-networking.md。 |
| Corosync 配置 | 先複製，編輯副本，備份當前配置，然後再移動。始終遞增 config_version。 |
| 儲存操作 | 在移除儲存設備前：pvesm list {storage} 以確認沒有 VM/CT 參考到它。 |
| 保護標誌 | qm set {vmid} --protection 1 / pct set {vmid} --protection 1 以防止意外刪除。 |
| ZFS 屬性清理 | PVE 將來賓配置的磁碟大小儲存為資料集的 refquota。一個清理所有資料集上 refquota/refreservation 的動作會默默移除每個來賓的磁碟限制，而 pct config 仍會報告舊的大小，導致一個容器可填滿整個儲存池。請排除以 subvol- 或 vm- 開頭的葉子名稱。 |
3. 行動審查協定
強制執行。 在每次直接對 Proxmox 節點、VM 或容器執行操作（命令、配置變更、服務操作）前，都必須進行此審查。
例外情況： 唯讀操作 - 讀取日誌、查詢狀態、收集資訊而不做任何變更 - 被視為安全，可以在不經此審查的情況下立即執行。
在
opus上執行此關卡。 這個鋼鐵人/紅隊判斷會對 LIVE 基礎設施的變更進行把關 - 較弱的模型會低估停機、資料遺失和仲裁風險。請在opus上進行審查：將其委託給一個固定為opus的子代理，設定努力程度為medium（審查分派，請參閱 bitranox:process-agents-subagent-driven-development「審查分派」），或者（如果你保持內嵌）在執行前提供切換模型或繼續的選項。絕對不要在未知的較低層級上執行此關卡。請參閱bitranox:process-agents-subagent-driven-development（「會話模型是固定的」/「具體層級」）。
3.1 鋼鐵人提示
考慮計劃在 Proxmox 伺服器上執行的動作或配置，以其最理想、最成功的形式呈現。想像此動作代表最安全、最有效率且最佳整合的解決方案。闡述此動作如何完美達成系統管理的目標、增加穩定性，並完全滿足使用者需求。
3.2 紅隊提示
以經驗豐富的管理員或安全分析師的角度審查計劃的 Proxmox 動作，試圖找出潛在風險。辨識配置中可能存在的弱點，考慮停機風險、資料遺失或非預期的副作用。在最壞情況下測試計劃的穩健性，以確保其在壓力下仍然安全可靠。
3.3 決策
在紅隊審查結束時，評估已辨識的風險或弱點是否嚴重到足以阻止計劃的動作。如果動作看起來安全、合理且穩健，則可以立即執行。如果仍有重大不確定性，則必須明確要求使用者確認。最後做出明確的決定：「執行動作」 或 「向使用者請求確認」。
4. 程式碼與回覆風格
- 回覆： 簡短、精確、以 CLI 為導向 (
pvesh,pvecm,pvesm,qm,pct,ha-manager,vzdump,pvesr,pvenode,pveceph,pveum,pveam)。 - 疑難排解： 始終先查詢日誌：
journalctl -u pvedaemon -n 50,pvenode task list --errors 1,/var/log/pveproxy/access.log。 - JSON 偏好： 使用
--output-format json或json-pretty。對於腳本化解析，使用--noborder --noheader。 - 回退計畫： 每個變更都必須包含回退措施。先備份配置檔案。在進行儲存/VM 變更前，確保備份存在。
5. 叢集大小速查表
| 大小 | 行為 |
|---|---|
| 單節點 | 無叢集操作。無 HA。專注於本地儲存 + 外部備份。 |
| 2 節點 | 強烈建議使用 QDevice。沒有它：失去 1 個節點 = 失去仲裁。緊急情況使用 pvecm expected 1。 |
| 3 個以上節點 | 完整 HA。能容忍 floor((N-1)/2) 個故障（3 節點：1 個，5 節點：2 個）。 |
偵測節點數量： pvecm nodes | grep -c '^\s*[0-9]'
6. 疑難排解快速參考
| 問題 | 診斷 |
|---|---|
| 叢集無法定足 | pvecm status > "Quorate: No"。檢查連線，systemctl status corosync。緊急情況：pvecm expected 1。 |
| 節點無法加入 | 驗證 UDP 5405-5412、時間同步、SSH (TCP 22)。嘗試：pvecm add {IP} --fingerprint {SHA256}。 |
| 虛擬機無法啟動 | 檢查鎖定：qm unlock {vmid}。檢查儲存空間：pvesm status。查看日誌：journalctl -u pvedaemon。 |
| 備份失敗 | 檢查儲存空間：pvesm status。檢查權限。嘗試手動執行：vzdump {vmid} --storage {storage} --mode snapshot。 |
| HA 資源無法啟動 | ha-manager status、ha-manager resource-status。從超過 5 次嘗試的節點上清除：ha-manager cleanup {node}。 |
| 儲存池已滿 | df -h、zfs list -o name,used,avail,refer,mountpoint、pvesm status。尋找孤兒快照：zfs list -t snapshot。 |
| Ceph 健康狀態 | ceph -s、ceph health detail、ceph osd tree。檢查 OSD：ceph osd stat。 |
| SDN 問題 | 驗證 VNet：pvesh get /cluster/sdn/vnets。檢查子網：pvesh get /cluster/sdn/subnets。重新載入 SDN：pvesh set /cluster/sdn。 |
7. 常見動作
| 類別 | 動作 | 範例命令 |
|---|---|---|
| VM | 建立 | qm create {vmid} --name {name} --memory {MB} --net0 virtio,bridge=vmbr0 --scsihw virtio-scsi-pci --virtio0 {storage}:{size} |
| 啟動/停止 | qm start {vmid} / qm stop {vmid} | |
| 遷移 | qm migrate {vmid} {target-node} --online | |
| 快照 | qm snapshot {vmid} {snapname} | |
| 備份 | vzdump {vmid} --storage {storage} --mode snapshot | |
| 設定 | qm set {vmid} --{option} {value} | |
| 取消鎖定 | qm unlock {vmid} | |
| CT | 建立 | pct create {vmid} {template} --storage {storage} --memory {MB} --net0 name=eth0,bridge=vmbr0,ip=dhcp |
| 啟動/停止 | pct start {vmid} / pct stop {vmid} | |
| 遷移 | pct migrate {vmid} {target-node} | |
| 備份 | vzdump {vmid} --storage {storage} --mode snapshot | |
| 設定 | pct set {vmid} --{option} {value} | |
| 復原（還原） | pct restore {vmid} {backup-file} --storage {storage} | |
| 取消鎖定 | pct unlock {vmid} | |
| 節點 | 重新啟動 | pvenode reboot (需要確認) |
| 關機 | pvenode shutdown (需要確認) | |
| 任務列表 | pvenode task list | |
| 儲存 | 列出 | pvesm status |
| 內容 | pvesm list {storage} | |
| 添加 | pvesm add {type} {name} --{option} {value} | |
| 移除 | pvesm remove {storage} (需要先驗證沒有使用中的 VM/CT) | |
| 掃描磁碟 | pvesm scan | |
| Ceph | 狀態 | ceph -s |
| OSD 樹狀圖 | ceph osd tree | |
| 池列表 | ceph osd lspools | |
| 新增 OSD | pveceph osd create /dev/{disk} | |
| 移除 OSD | pveceph osd remove {osd-id} | |
| 網路 | 橋接器 | pvesh get /nodes/{node}/network |
| 重新載入 | ifreload -a (需要先試運行) | |
| 使用者 | 列出 | pveum user list |
| 添加 | pveum user add {username}@{realm} --password | |
| 權限 | pveum acl modify / --user {username}@{realm} --role {role} |
8. 環境變數與路徑
PVE_CLUSTER_CONFIG_DIR:/etc/pve(叢集檔案系統掛載點)PVE_NODE: 目前節點名稱PVE_LOG_DIR:/var/log/pvePVE_DB_DIR:/var/lib/pve-cluster
9. 相關技能
bitranox:infra-linux: 一般 Linux 系統管理、網路、儲存bitranox:coding-resilience: 自我修復與優雅降級模式bitranox:process-agents-subagent-driven-development: 子代理分派與模型分層