Proxmox VE

**管理員位置：**Infrastructure › Cloud provider › Providers（/infra/providers），然後是提供者頁面（/infra/providers/<id>），其中包含Overview、Clusters、VMs、Servers和Credentials分頁。方案設定於Services › Virtual Machines › Plans & pricing（/vm/catalog）。

功能

NexCMP 可以銷售執行於一個或多個 Proxmox VE 叢集上的虛擬機器，作為 CloudStack 的替代方案或補充。虛擬機器是透過完整複製 OS 範本來建立的，然後透過 cloud-init 進行設定：大小、來自您定義的池中的 IP 位址、root 密碼與 SSH key。客戶可在入口網站中進行電源控制、主控台、快照、重新安裝、密碼重設與指標查看。他們永遠不會看到叢集、節點或來源名稱。

當您已經執行 Proxmox VE，或是想要提供第二個不同定價的 VM 池時請使用它。

需求

項目	需求
Proxmox VE	PVE 9.x。此整合已在 9.2 版本上驗證。它需要 import 儲存空間內容與 import-from 磁碟選項（PVE 8.2 或更新版本）。
來自面板的網路	HTTPS 連線至叢集 API，https://<host or IP>:8006。無路徑、使用者名稱或查詢字串。面板和 worker 皆會連線；瀏覽器主控台會透過面板進行代理。
帳號	具有 API token 的專用 PVE 使用者，並搭配具有下列權限的自訂角色。切勿使用 root@pam。
儲存	支援複製（例如 local-lvm）的 VM 磁碟儲存空間。對於內建範本建立器，儲存空間名稱為 local，其內容類型包含 import 與 snippets。
網路	可連線至客戶 IP 所在網路的 Linux 橋接器（例如 vmbr0）。若您輸入 VLAN 標籤，請使用支援 VLAN 的橋接器。
IP	路由至該橋接器的 IPv4 區塊（/16 至 /30），並附帶閘道。NexCMP 會自行指派位址；Proxmox 沒有 IP 管理功能。
範本	每個您要部署的節點上，每種作業系統需要一個 cloud-init 範本 VM，並安裝 QEMU guest agent。
區域	用於附加叢集的現有區域。請參閱 Zones。
相依於	無。

準備基礎設施

在任何叢集節點上以 root 身分執行指令。

1. 建立最小權限角色、使用者與 API token

1. 建立角色。權限清單正是 NexCMP 所使用的內容；它不包含任何會編輯使用者、儲存空間定義或資料中心的項目。

   pveum role add NexCMP -privs "VM.Allocate VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Cloudinit VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.PowerMgmt VM.Audit VM.Console VM.Snapshot VM.Snapshot.Rollback VM.Backup VM.GuestAgent.Audit VM.GuestAgent.Unrestricted Datastore.Audit Datastore.AllocateSpace Datastore.AllocateTemplate Sys.Audit Sys.AccessNetwork SDN.Use SDN.Audit Pool.Audit Mapping.Audit Mapping.Use"

   下載雲端映像需要 Sys.AccessNetwork。PVE 9 沒有 VM.Monitor 權限；請勿新增它。

2. 建立使用者與 token。--privsep 1 意指 token 的權限為使用者自身權限與 token 自身權限的交集。

   pveum user add nexcmp@pve --comment "NexCMP"
   pveum user token add nexcmp@pve api --privsep 1

   此指令會印出 secret once（一個 UUID）這個 token。請立即複製。token id 為 nexcmp@pve!api。

3. 將角色同時指派給使用者與權杖。這是最容易被遺漏的步驟：在權限隔離架構下，若使用者沒有權限，只有權杖會收到如Datastore.Audit的403錯誤。

   pveum acl modify / --roles NexCMP --users nexcmp@pve
   pveum acl modify / --roles NexCMP --tokens 'nexcmp@pve!api'

4. 從面板伺服器進行測試：

   curl -sk -H 'Authorization: PVEAPIToken=nexcmp@pve!api=<secret>' https://192.0.2.10:8006/api2/json/version

   出現帶有 version 的 JSON 文件代表 token 正常運作。（-k 僅用於此快速檢查；NexCMP 會自行釘選憑證，詳見下方。）

2. 檢查網橋與儲存空間

pvesm status          # storages, type, content and free space
ip -br link show type bridge

• 客戶虛擬機器將在你在 NexCMP 中輸入的網橋上取得 virtio 個網路介面。若你設定了 VLAN，該網橋必須支援 VLAN。
• 將客戶虛擬機器放在與節點管理位址分開的網橋或 VLAN 上。若它們共用網路，Proxmox 防火牆的自動管理 IP 集合會將節點的連接埠 22、8006、3128、5900-5999 與 60000-60050 開放給該網路中的每一個虛擬機器。若無法將它們分開，請在管理 ACCEPT 規則上方，為虛擬機器子網新增針對這些連接埠的明確 DROP 規則。

3. 儲存空間注意事項 (LVM-thin)

• 將 thin-pool zeroing 保持預設值。將其關閉（lvchange -Zn）可能會在新配置的區塊中殘留舊資料，並損毀已複製虛擬機器的分割表或檔案系統。
• 回報「write cache: disabled」的硬碟只能以每秒幾 MB 的速度複製。請使用 hdparm -W /dev/sdX 檢查，若硬碟具備斷電保護功能，請啟用寫入快取。

4. 啟用 import 內容（僅限內建範本建構器）

內建建構器會將雲端映像檔下載至名為 local 的儲存空間，並從中建立範本。將 import（與 snippets）新增至該儲存空間的內容清單中。保留你原本就在使用的類型；--content 會取代整個清單：

pvesm status --storage local     # note the current content
pvesm set local --content iso,vztmpl,backup,import,snippets

5. 從雲端映像檔建構作業系統範本

範本是供 NexCMP 進行複製的 cloud-init 虛擬機器。每個範本都會以簡短的 OS key（例如 ubuntu-24.04）及其 VM id 進行註冊。在每個將接收虛擬機器的節點上建立一個作業系統範本，因為複製作業會在所選的節點上執行。

選項 A，建議做法：自行建構。 標準的 Ubuntu 與 Debian 雲端映像檔不包含客體代理程式，也不允許 root 登入，而 NexCMP 是透過 cloud-init 設定 root 密碼。請先準備映像檔：

apt install -y libguestfs-tools
wget -O noble.qcow2 https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
virt-customize -a noble.qcow2 --install qemu-guest-agent \
  --write /etc/cloud/cloud.cfg.d/99-nexcmp.cfg:$'ssh_pwauth: true\ndisable_root: false\n' \
  --write /etc/ssh/sshd_config.d/00-nexcmp.conf:$'PermitRootLogin yes\nPasswordAuthentication yes\n'

然後建立範本虛擬機器（id 9000 為範例；請將範本 id 保持在 vmid from 值（預設 1000）以下）：

qm create 9000 --name tpl-ubuntu-24-04 --memory 2048 --cores 2 --cpu host --ostype l26 \
  --scsihw virtio-scsi-single --net0 virtio,bridge=vmbr0 --agent 1 --serial0 socket --vga serial0
qm set 9000 --scsi0 local-lvm:0,import-from=$PWD/noble.qcow2,discard=on,iothread=1
qm set 9000 --ide2 local-lvm:cloudinit --boot order=scsi0
qm template 9000

選項 B：內建建構器。 位於「叢集」分頁上的 Create OS template from cloud image 卡片（見下方）會下載 qcow2 映像檔、建構範本並進行註冊。它會以 cloud-init 與客體代理程式旗標建立虛擬機器，但不會改變映像檔內部的內容。請僅在映像檔已經允許 root 登入並執行客體代理程式時使用，或者在你同時提供 cloud-init vendor-data 程式碼片段時使用。

客體代理程式是 Reset password 以及顯示虛擬機器 IP 位址所需的元件。

6. 了解憑證指紋（選填）

NexCMP 透過釘選其 TLS 憑證的 SHA-256 指紋來信任叢集，因此自簽憑證即可適用。若要查看 NexCMP 將會釘選的值：

openssl x509 -in /etc/pve/local/pve-ssl.pem -noout -fingerprint -sha256

在 NexCMP 中連線

1. 開啟 Infrastructure › Cloud provider › Providers 並點擊 Add cloud provider。選擇 Proxmox VE 並填入：

   欄位	範例值
   Name	Proxmox cluster 1
   Endpoint	https://192.0.2.10:8006
   Token id	nexcmp@pve!api
   Token secret	XXXX（步驟 1 中印出的 UUID）
   Slug	pve-1（a-z、0-9、連字號，2-32 個字元）
   Default node	pve1（留空：擁有最多剩餘 RAM 的線上節點）
   儲存	local-lvm
   Bridge	vmbr0

   

2. 按一下 Save & open provider，並在出現提示時輸入原因。權杖在儲存前會進行加密。

3. 在 Overview 分頁上按一下 Test connection。第一次成功的測試會釘選叢集的 TLS 指紋；此後將拒絕其他憑證。

4. 開啟 Clusters 分頁。Node · storage · bridge 卡片列出 API 所看到的內容；Cluster configuration 卡片則包含相關設定：

   欄位	含意
   Default node	用於新虛擬機器的節點。留空代表擁有最多剩餘 RAM 的線上節點。
   Storage, Bridge, VLAN	磁碟儲存空間、NIC 橋接器與選用的 VLAN 標籤（0 代表無）。
   CPU type	預設為 host。當節點具備不同 CPU 世代時請使用 x86-64-v2-AES。
   vmid from	指派給客戶虛擬機器的第一個 VM ID（預設為 1000）。
   Storage ISO, Storage backup	除非您要使用，否則請保持空白；留空表示不提供 ISO 與備份功能。
   Template OS	每行一個，os-key=vmid，例如 ubuntu-24.04=9000。
   Pinned TLS fingerprint (SHA-256)	由第一次測試填入。更換叢集憑證後，請清除它並再次測試。

   

5. 選填：如果您使用上述選項 B，請填寫 Create OS template from cloud image（作業系統金鑰 ubuntu-24.04、vmid 9000、節點 pve1、qcow2 映像檔 URL），然後按一下 Create template。它會在背景執行數分鐘；結果可在稽核記錄中檢視。

   

6. 點擊 Add pool（位於 Cluster IP pool），並建立供虛擬機器取得位址的集區：

   欄位	範例值
   Name	customers-1
   CIDR	198.51.100.0/24
   Gateway	198.51.100.1（絕不指派給虛擬機器）
   DNS	1.1.1.1,8.8.8.8（1 到 4 個 IPv4 位址）
   Bridge, VLAN	vmbr0, 0
   Already used IPs	每行一個，ip note，例如 198.51.100.10 monitoring

   NexCMP 絕不會指派網路位址、廣播位址、閘道或保留位址。相同叢集的集區不可重疊。唯有當集區中沒有任何位址正在使用時，才能刪除該集區。

   

7. 在 Attach cluster to zone 中，選擇區域並可選擇性填入節點名稱，然後按一下 Attach to zone。此叢集將加入已在販售虛擬機器的區域，因此單一區域可同時擁有 CloudStack 與 Proxmox。新來源預設不會販售，且不會改變現有方案的運作方式。

   

8. 開啟 Services › Virtual Machines › Plans & pricing 並按一下 Add plan。在 Infrastructure source 中選擇 Proxmox 叢集，然後設定 CPU、RAM、磁碟與價格。Proxmox 方案不需要 CloudStack 供應項目。若要從兩個來源販售相同組態，請在方案上使用 Clone 並選擇另一個來源。方案的磁碟大小必須大於或等於範本的磁碟大小；Proxmox 無法縮小磁碟。

匯入已存在的虛擬機器

開啟 Servers 分頁以列出叢集上的虛擬機器。Import 會免費將現有虛擬機器指派給客戶帳戶：時數、關機時間或流量均不收費。客戶可以啟動、停止、重新開機並開啟主控台，但無法刪除，只有管理員可以。NexCMP 在匯入時僅從叢集讀取。

• 叢集必須附加至具備該虛擬機器節點名稱的區域（若將節點留空，匯入時會回報未設定區域）。

• 若要將虛擬機器設為受保護狀態（將拒絕停止、重新開機、重新安裝、快照還原、銷毀與方案變更），請透過命令列進行匯入：--protect

  sudo -u nexcmp /opt/nexcmp/bin/nexcmp px-import --provider pve-1 --server-ref pve1/101 --account-id 12 --hostname web-1 --protect

Proxmox 支援與不支援的功能

功能	Proxmox VE
建立、開機/關機/重新開機、刪除	是
調整 CPU 與 RAM 大小、擴充磁碟	可以，但虛擬機器會先停止、變更後再啟動（不支援線上調整大小）
Snapshots	可以，每個虛擬機器最多 5 個：建立、列出、還原、刪除
重新安裝	可以：虛擬機器將根據範本重建，並保留其 ID、IP 與設定，同時產生新密碼
重設密碼	可以，透過客體代理程式
主控台	可以，透過面板代理的瀏覽器主控台
度量指標	可以：CPU、記憶體、網路與磁碟
ISO 掛載、備份、防火牆、IPv6、通訊埠轉送、變更 IP、額外儲存卷、Auto Scaling、DDoS Shield、VPC、頻寬計量	無法使用。客戶虛擬機器頁面會隱藏來源不支援的功能。

驗證

1. Test connection 顯示正常，且提供者狀態為啟用。
2. Clusters 列出您的節點為線上狀態，並顯示儲存空間與橋接器。
3. Cluster IP pool 顯示可用、已使用與保留的數量。
4. 附加叢集後，OS 金鑰會顯示在 Services › Virtual Machines › Template 的區域範本下方。
5. 從使用該叢集的方案訂購測試虛擬機器。它應該會從集區取得位址、root 密碼與正常運作的主控台；集區會顯示一個已使用的位址。

限制與注意事項

混合來源區域

自NexCMP 1.4.0起，當CloudStack與Proxmox VE共用同一個區域時，公開的Cloud Server價格表也能正常運作。每個方案皆使用各自的Infrastructure source。連接叢集後，請檢查公開價格表並針對每個來源建立測試訂單。

• 可以新增多個 Proxmox 叢集。每個叢集都是一個提供者。
• 一個區域提供一個預設來源；擁有自身 Infrastructure source 的方案會部署至該特定叢集，前提是該叢集處於啟用狀態且位於方案的區域中。
• 位於 CloudStack 相同區域背後的叢集會保留其在 CloudStack 上的舊版方案。請在推出前進行端對端訂購測試。
• API 金鑰只能替換，無法檢視。請在 Credentials 分頁中進行替換：先在 Proxmox 中建立新金鑰、輸入金鑰、執行 Test connection，然後再撤銷舊金鑰。
• 測試、同步與叢集資訊動作每個管理員每分鐘限制呼叫六次。
• NexCMP 負責向您的客戶收費；叢集的硬體與授權成本由您負擔。

故障排除

症狀	原因	修正方式
測試：「金鑰遭到拒絕（存取金鑰/密鑰錯誤或已被撤銷）」或 HTTP 401/403	權杖 ID 或密鑰錯誤，或 ACL 僅授予該權杖	重新執行兩個 pveum acl modify 指令（使用者 and token）並檢查 token id 是否為 user@realm!tokenid。
測試：「Could not connect to the provider」或「Timed out」	防火牆、主機或連接埠錯誤	從面板伺服器檢查 https://host:8006。
測試：「Invalid endpoint or not on the allowlist」	端點包含路徑、使用者、查詢參數，或並非 HTTPS	請確切使用 https://host:8006。
「叢集 TLS憑證與釘選的憑證指紋不符」	叢集憑證已被更換	清除 Clusters 標籤頁上的 Pinned TLS fingerprint，儲存後再次執行 Test connection。
代稱（Slug）被拒絕	非 a-z、0-9、連字號，或長度不在 2-32 個字元之間	請使用類似 pve-1 的格式。
「Token id格式：user@realm!tokenid，且需要secret」	缺少 token id 或密鑰	請兩者皆填；密鑰是建立 token 時所列印出的 UUID。
「無效的範本行：…」	Template OS 中的某行並非 key=vmid	在鍵中使用字母、數字、.、_、-，且 vmid 至少為 100。
「OS key：a-z 0-9 . _ - 且 vmid ≥ 100」	Create template 中的鍵或 id 無效	修正 OS 鍵並使用未被佔用的 vmid。
建立範本時出現「vmid … already exists」	vmid 已被佔用	請選擇其他 id。
「url指向內部位址」	映像檔 URL 為內部 IP	請使用公開 URL；名稱會由 Proxmox 解析。
範本任務在下載時失敗	儲存空間 local 沒有 import 內容	pvesm set local --content …,import,snippets，然後重試。檔名必須以 .qcow2、.raw、.vmdk、.ova 或 .ovf 結尾。
「cluster has no online nodes」或「node … is not online」	預設節點已離線或拼寫錯誤	修正 Default node 或保持空白。
「映像檔不屬於此叢集」	方案的 OS 不在 Template OS 中	將該鍵新增至列表並儲存。
部署等待中，隨後在複製時失敗	範本虛擬機器不在所選節點上	在該節點上建立範本，或將 Default node 設定為擁有該範本的節點。
客戶無法以 root 登入	映像檔阻擋了 root 登入	依照選項 A 重新建構範本。
重設密碼沒有任何作用	客體作業系統中沒有 guest agent	在範本中安裝並啟用 qemu-guest-agent。
「名稱、CIDR 與閘道器為必填」	缺少 pool 欄位	請填寫全部三個。
Pool create: "overlaps with pool …", "gateway must be within range (not network/broadcast address)" 或 "cidr: network address must be …"	重疊的 pool、錯誤的 gateway，或不在網路邊界的 CIDR	使用未使用的範圍、其中的 gateway 以及寫成網路位址的 CIDR（例如 198.51.100.0/24）。
匯入："region is not set up"	附加叢集時未包含 VM 的節點名稱	將包含節點名稱的叢集附加至區域。