---
title: Proxmox VE
description: 将Proxmox VE集群添加为虚拟机源：最小权限API token、存储、cloud-image模板、IP池、TLS固定以及按方案配置源。
url: https://nexcmp.com/zh-cn/docs/infrastructure/proxmox/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Proxmox VE

> **管理后台位置：**Infrastructure › Cloud provider › Providers（`/infra/providers`），然后是包含Overview、Clusters、VMs、Servers和Credentials选项卡的提供商页面（`/infra/providers/<id>`）。方案在Services › Virtual Machines › Plans & pricing（`/vm/catalog`）下设置。

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

NexCMP可以销售运行在一个或多个Proxmox VE集群上的虚拟机，既可与CloudStack并存，也可替代CloudStack。虚拟机通过完整克隆操作系统模板创建，然后通过cloud-init进行配置：规格、自定义池中的IP地址、root密码和SSH密钥。客户可在门户中进行电源控制、控制台访问、Snapshots、重装系统、密码重置并查看监控指标。他们绝不会看到集群、节点或源名称。

当您已经在运行Proxmox VE，或希望提供第二个定价不同的虚拟机资源池时，可以使用此功能。

## 前提条件 {#requirements}

| 项目 | 要求 |
|---|---|
| Proxmox VE | PVE 9.x。该集成已在9.2上完成验证。它需要`import`存储内容类型以及`import-from`磁盘选项（PVE 8.2或更高版本）。 |
| 来自面板的网络 | 通过HTTPS连接到集群API，`https://<host or IP>:8006`。不包含路径、用户名或查询参数。面板和worker均会发起连接；浏览器控制台通过面板进行代理。 |
| 账户 | 一个专用的PVE用户，带有**API token**以及具备下列权限的自定义角色。切勿使用`root@pam`。 |
| 存储 | 用于虚拟机磁盘且支持克隆的存储（例如`local-lvm`）。对于内置模板构建器，需要名为`local`且包含内容类型`import`和`snippets`的存储。 |
| 网络 | 能够通达客户IP所在网络的Linux网桥（例如`vmbr0`）。如果输入了VLAN标签，请使用VLAN-aware网桥。 |
| IP | 路由到该网桥的IPv4网段（/16至/30），并配置网关。NexCMP自行分配地址；Proxmox没有IP管理功能。 |
| 模板 | 在部署到的每个节点上，为每个操作系统准备一个配置了QEMU guest agent的cloud-init模板虚拟机。 |
| 区域 | 用于挂接集群的现有区域。参见[Zones](https://nexcmp.com/zh-cn/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"
   ```

   cloud-image下载需要`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
   ```

   该命令仅会打印一次令牌**密钥**（UUID）。请立即复制。令牌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文档即表示令牌工作正常。（`-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-aware）。
- 将客户虚拟机放置在**与节点管理地址隔离**的网桥或VLAN上。如果它们共享网络，Proxmox防火墙的自动管理IP集会向该网络中的所有虚拟机开放节点的22、8006、3128、5900-5999以及60000-60050端口。如果无法隔离，请在管理ACCEPT规则上方，针对虚拟机子网添加到这些端口的显式DROP规则。

### 3. 存储注意事项（LVM-thin） {#_3-storage-notes-lvm-thin}

- 保持精简池的**清零功能为默认设置**。将其关闭（`lvchange -Zn`）可能会在新建分配的数据块中残留旧数据，并损坏克隆虚拟机的分区表或文件系统。
- 显示“write cache: disabled”的磁盘克隆速度可能只有几MB/s。请使用`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`）及其虚拟机ID进行注册。请**在每个将接收虚拟机的节点上**为每种操作系统构建一个模板，因为克隆操作是在选定节点上执行的。

**方案A（推荐）：自行构建。**原版Ubuntu和Debian云镜像不包含guest agent且不允许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：内置构建器。**Clusters选项卡中的**Create OS template from cloud image**卡片（见下文）会下载qcow2镜像、构建模板并进行注册。它会在创建虚拟机时配置cloud-init和guest agent标志，但不会更改镜像内部的内容。仅当镜像已允许root登录并运行guest agent，或您同时提供了cloud-init vendor-data代码片段时，方可使用此方式。


**Reset password**以及显示虚拟机的IP地址均需要guest agent。

### 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**并填写：

   | 字段 | 示例值 |
   |---|---|
   | 名称 | `Proxmox cluster 1` |
   | 端点 | `https://192.0.2.10:8006` |
   | 令牌ID | `nexcmp@pve!api` |
   | 令牌密钥 | `XXXX`（步骤1中打印的UUID） |
   | Slug | `pve-1`（a-z、0-9、连字符，2-32个字符） |
   | 默认节点 | `pve1`（留空：空闲RAM最多的在线节点） |
   | 存储 | `local-lvm` |
   | Bridge | `vmbr0` |

      ![已选择Proxmox VE并包含示例端点、Token和存储值的添加云提供商对话框](https://nexcmp.com/zh-cn/docs/images/infrastructure/proxmox-01-add-provider.webp)

2. 点击**Save & open provider**，并在提示时输入原因。Token在存储前会被加密。
3. 在**Overview**标签页中点击**Test connection**。首次测试成功后将**锁定集群的TLS指纹**；此后若证书不一致将被拒绝。


4. 打开**Clusters**标签页。**Node · storage · bridge**卡片列出了API检测到的内容；**Cluster configuration**卡片包含各项配置：

   | 字段 | 说明 |
   |---|---|
   | 默认节点 | 用于新虚拟机的节点。留空表示选择空闲RAM最多的在线节点。 |
   | Storage, Bridge, VLAN | 磁盘存储、网卡网桥及可选的VLAN标签（0表示无）。 |
   | CPU type | 默认为`host`。当各节点的CPU代际不同时，请使用`x86-64-v2-AES`。 |
   | vmid from | 分配给客户虚拟机的首个虚拟机ID（默认为1000）。 |
   | Storage ISO, Storage backup | 除非需要使用，否则请留空；留空表示不提供ISO和备份功能。 |
   | Template OS | 每行一个，`os-key=vmid`，例如`ubuntu-24.04=9000`。 |
   | Pinned TLS fingerprint (SHA-256) | 首次测试时自动填入。更换集群证书后，请将其清除并重新测试。 |

      ![Clusters标签页，包含示例节点、存储、网桥和操作系统模板列表的Cluster configuration卡片](https://nexcmp.com/zh-cn/docs/images/infrastructure/proxmox-03-cluster-config.webp)

5. 可选：若上方采用了方案B，请填写**Create OS template from cloud image**（OS key `ubuntu-24.04`、vmid `9000`、node `pve1`及qcow2镜像URL），然后点击**Create template**。该任务将在后台运行几分钟；执行结果可在Audit log中查看。

      ![包含示例Ubuntu镜像URL的Create OS template from cloud image卡片](https://nexcmp.com/zh-cn/docs/images/infrastructure/proxmox-04-template-from-image.webp)

6. 点击**Add pool**（位于**Cluster IP pool**中），并创建供虚拟机获取地址的池：

   | 字段 | 示例值 |
   |---|---|
   | 名称 | `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绝不分配网络地址、广播地址、网关或保留地址。同一集群内的IP池不可重叠。仅当池中所有地址均未被占用时，方可删除该池。

      ![包含示例/24和网关的Add IP pool对话框](https://nexcmp.com/zh-cn/docs/images/infrastructure/proxmox-05-ip-pool.webp)

7. 在**Attach cluster to zone**中选择区域，也可选填节点名称，然后点击**Attach to zone**。该集群将加入已销售虚拟机的区域，因此一个区域可同时包含CloudStack与Proxmox。新来源**默认不出售**，且不会改变现有方案的运作方式。

      ![已选择现有区域的Attach cluster to zone卡片](https://nexcmp.com/zh-cn/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与内存规格、扩容磁盘 | 支持，但虚拟机会先停止、调整后再重新启动（不支持热调整） |
| Snapshots | 支持，每台虚拟机最多5个：创建、列出、恢复、删除 |
| 重装系统 | 支持：虚拟机将从模板重新构建，并保留其ID、IP和设置，同时生成新密码 |
| 重置密码 | 支持，通过guest agent实现 |
| 控制台 | 支持，由控制面板代理的浏览器控制台 |
| 监控指标 | 支持：CPU、内存、网络和磁盘 |
| ISO挂载、Backups、防火墙、IPv6、端口转发、更换IP、额外卷、Auto Scaling、DDoS Shield、VPC、带宽计量 | 不支持。客户虚拟机页面会隐藏源不支持的功能。 |

## 验证 {#verify}

1. **Test connection**显示OK且提供商状态为active。
2. **Clusters**中您的节点显示为online，并包含存储和网桥。
3. **Cluster IP pool**显示空闲、已用和保留的数量。
4. 集群附加后，OS key将显示在**Services › Virtual Machines › Template**中的对应区域模板下。
5. 从使用该集群的套餐中订购一台测试虚拟机。它应从地址池获取一个IP地址、root密码并具备可用的控制台；地址池显示已使用一个地址。

## 限制与注意事项 {#limits-and-notes}

::: tip 混合源区域
自NexCMP 1.4.0起，当CloudStack与Proxmox VE共用同一个区域时，公开的Cloud Server价格表同样有效。每个套餐均使用各自的**Infrastructure source**。挂载集群后，请检查公开价格表并针对每个来源提交测试订单。
:::

- 可以添加多个Proxmox集群。每个集群对应一个提供商。
- 区域提供一个默认源；只要集群处于active状态且位于套餐所属区域内，具有独立**Infrastructure source**的套餐就会精确部署到该集群。
- 与CloudStack位于同一区域的集群会将其原有的旧套餐保留在CloudStack上。上线前请端到端测试一次订购流程。
- API令牌只能替换，无法查看。在**Credentials**选项卡中进行替换：先在Proxmox中创建新令牌并输入，运行**Test connection**，然后再吊销旧令牌。
- 每个管理员每分钟最多可调用6次Test、Sync和cluster-info操作。
- NexCMP向您的客户计费；集群的硬件和许可证成本由您承担。


## 故障排查 {#troubleshooting}

| 症状 | 原因 | 解决办法 |
|---|---|---|
| 测试："Key rejected (wrong access key / secret, or revoked)"或HTTP 401/403 | 令牌ID或密钥错误，或者ACL仅授予了令牌 | 重新运行两条`pveum acl modify`命令（用户**和**令牌），并检查令牌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为必填项” | 令牌ID或密钥缺失 | 两者均需输入；密钥是创建令牌时打印的UUID。 |
| “无效的模板行：…” | **Template OS**中的某一行不是`key=vmid`格式 | 在Key中使用字母、数字、`.`、`_`、`-`，且vmid不小于100。 |
| “OS key：a-z 0-9 . _ -且vmid ≥ 100” | **Create template**中的Key或ID无效 | 修正OS Key并使用未占用的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**或将其留空。 |
| “镜像不属于集群” | 套餐的操作系统不在**Template OS**中 | 将该Key添加到列表中并保存。 |
| 部署等待后在克隆阶段失败 | 模板虚拟机不在所选节点上 | 在该节点上创建模板，或将**Default node**设置为包含该模板的节点。 |
| 客户无法以root身份登录 | 镜像阻止了root登录 | 按照方案A重新构建模板。 |
| 重置密码无效果 | 客户机内未安装guest agent | 在模板中安装并启用`qemu-guest-agent`。 |
| “名称、CIDR和网关为必填项” | 缺少地址池字段 | 填写全部三项内容。 |
| 创建地址池：“overlaps with pool …”、“gateway must be within range (not network/broadcast address)”或“cidr: network address must be …” | 地址池重叠、网关错误，或CIDR未对齐网络边界 | 使用未被占用的范围、包含在该范围内的网关，以及按网络地址书写的CIDR（例如`198.51.100.0/24`）。 |
| 导入：“region is not set up” | 附加集群时未指定虚拟机的节点名称 | 将包含节点名称的集群附加到该区域。 |