---
title: Proxmox VE
description: 新增 Proxmox VE 叢集作為虛擬機器來源：最小權限 API Token、儲存空間、雲端映像範本、IP 池、TLS 憑證釘選與依方案來源。
url: https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Proxmox VE

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

## 功能 {#what-it-does}

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

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

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| 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](https://nexcmp.com/zh-tw/docs/infrastructure/zones/)。 |
| 相依於 | 無。 |

## 準備基礎設施 {#prepare-the-infrastructure}

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

### 1. 建立最小權限角色、使用者與 API token {#_1-create-a-least-privilege-role-user-and-api-token}

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

   ```bash
   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 自身權限的**交集**。

   ```bash
   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錯誤。

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

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

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

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

### 2. 檢查網橋與儲存空間 {#_2-check-the-bridge-and-the-storage}

```bash
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) {#_3-storage-notes-lvm-thin}

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

### 4. 啟用 `import` 內容（僅限內建範本建構器） {#_4-enable-the-import-content-only-for-the-built-in-template-builder}

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

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

### 5. 從雲端映像檔建構作業系統範本 {#_5-build-an-os-template-from-a-cloud-image}

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

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

```bash
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）以下）：

```bash
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. 了解憑證指紋（選填） {#_6-know-the-certificate-fingerprint-optional}

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

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

## 在 NexCMP 中連線 {#connect-in-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` |

      ![已選取 Proxmox VE 並帶有範例端點、權杖與儲存空間值的新增雲端提供者對話方塊](https://nexcmp.com/zh-tw/docs/images/infrastructure/proxmox-01-add-provider.webp)

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) | 由第一次測試填入。更換叢集憑證後，請清除它並再次測試。 |

      ![Clusters 分頁，包含範例節點、儲存空間、橋接器與作業系統範本清單的叢集組態卡片](https://nexcmp.com/zh-tw/docs/images/infrastructure/proxmox-03-cluster-config.webp)

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

      ![包含範例 Ubuntu 映像檔 URL 的「從雲端映像檔建立作業系統範本」卡片](https://nexcmp.com/zh-tw/docs/images/infrastructure/proxmox-04-template-from-image.webp)

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

      ![帶有範例 /24 與閘道的新增 IP 集區對話方塊](https://nexcmp.com/zh-tw/docs/images/infrastructure/proxmox-05-ip-pool.webp)

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

      ![已選取現有區域的將叢集附加至區域卡片](https://nexcmp.com/zh-tw/docs/images/infrastructure/proxmox-06-attach-zone.webp)

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


### 匯入已存在的虛擬機器 {#import-a-vm-that-already-exists}

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

- 叢集必須附加至具備該虛擬機器**節點名稱**的區域（若將節點留空，匯入時會回報未設定區域）。
- 若要將虛擬機器設為**受保護**狀態（將拒絕停止、重新開機、重新安裝、快照還原、銷毀與方案變更），請透過命令列進行匯入：`--protect`

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



### Proxmox 支援與不支援的功能 {#what-is-and-is-not-supported-on-proxmox}

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

## 驗證 {#verify}

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

## 限制與注意事項 {#limits-and-notes}

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

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


## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| 測試：「金鑰遭到拒絕（存取金鑰/密鑰錯誤或已被撤銷）」或 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 的節點名稱 | 將包含節點名稱的叢集附加至區域。 |