Proxmox VE

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

功能说明

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

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

前提条件

项目	要求
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。
依赖项	无。

准备基础设施

以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"

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

   该命令仅会打印一次令牌密钥（UUID）。请立即复制。令牌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文档即表示令牌工作正常。（-k仅用于本次快速检查；NexCMP自身会固定证书，详见下文。）

2. 检查网桥和存储

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）

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

**方案A（推荐）：自行构建。**原版Ubuntu和Debian云镜像不包含guest agent且不允许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：内置构建器。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. 获取证书指纹（可选）

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

   字段	示例值
   名称	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

   

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)	首次测试时自动填入。更换集群证书后，请将其清除并重新测试。

   

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

   

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池不可重叠。仅当池中所有地址均未被占用时，方可删除该池。

   

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

验证

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

限制与注意事项

混合源区域

自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向您的客户计费；集群的硬件和许可证成本由您承担。

故障排查

症状	原因	解决办法
测试："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”	附加集群时未指定虚拟机的节点名称	将包含节点名称的集群附加到该区域。