---
title: CloudStack
description: 将Apache CloudStack连接至NexCMP：使用cmk创建专属域、账户与API密钥，然后在设置向导或管理控制台中填入。
url: https://nexcmp.com/zh-cn/docs/infrastructure/cloudstack/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# CloudStack

> **管理控制台位置：**Infrastructure › Cloud provider › CloudStack › API connection（`/infra/cloudstack?tab=connect`）。首次连接也可在[设置向导](https://nexcmp.com/zh-cn/docs/getting-started/setup-wizard/)第2步中完成。

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

NexCMP销售运行在Apache CloudStack云平台上的虚拟机。它通过CloudStack API执行虚拟机的部署、启动、停止、调整配置、快照和删除，从区域中分配公网IP地址，读取账单和带宽使用量，并在管理控制台中展示容量与运行状况。CloudStack始终是虚拟化底座的权威数据源；NexCMP则在其之上提供店面、计费与客户门户。

当CloudStack是（或将是）您的主要虚拟机源时，请使用本页面。若要在此基础上接入第二数据源，请参阅[Proxmox VE](https://nexcmp.com/zh-cn/docs/infrastructure/proxmox/)。

## 前提条件 {#requirements}

| 项目 | 要求 |
|---|---|
| CloudStack版本 | 4.23为经过测试的版本。虚拟机控制台需要4.18或更高版本，运行中虚拟机的CPU/内存热扩容需要4.23搭配KVM。 |
| 区域类型 | 包含至少一个供客户虚拟机使用的访客网络，以及拥有可用空闲地址的公网IP段的区域。 |
| Hypervisor | KVM为经过测试的Hypervisor。 |
| 账户 | 专为NexCMP创建的**专属域和账户**。切勿使用ROOT管理员密钥。 |
| API可达性 | 面板服务器必须能够通过HTTP(S)访问管理服务器的API URL（`https://cloudstack.example.com/client/api`）。虚拟机控制台、带宽和Kubernetes功能使用相同的端点。 |
| 可选只读密钥 | 第二个只读密钥可让管理控制台展示宿主机、存储、系统虚拟机和公网IP网段。单纯销售虚拟机则不需要。 |
| 公网IP | 区域内有空闲的公网IPv4地址。NexCMP可销售的前缀网段在Sales IP pools中配置。 |
| 模板 | 至少一个就绪且启用密码的模板，以及一个您账户可见的service offering。请参阅[Templates](https://nexcmp.com/zh-cn/docs/infrastructure/templates/)。 |
| 存储 | 用于该账户卷的主存储；如果您销售Snapshots或镜像，还需要二级存储。 |
| 依赖项 | 无。Kubernetes、Private Cloud、Images和Bandwidth均依赖此页面。 |

::: warning 请勿使用ROOT管理员密钥
为NexCMP创建专用的域和账户。这样密钥的权限范围将仅限于该域，即使密钥泄露也不会波及云环境的其余部分。设置向导还会检查您选择的网络是否既属于该区域**且**属于拥有该密钥的账户。
:::

## 准备基础设施 {#prepare-the-infrastructure}

以下命令使用以CloudStack管理员身份登录的[CloudMonkey](https://cloudstack.apache.org/)（`cmk`）。请替换其中的示例名称和尖括号中的占位符。

### 创建专用账户和API密钥 {#create-a-dedicated-account-and-api-key}

1. 创建用于存放NexCMP所属全部资源的域。

   ```bash
   cmk create domain name=nexcmp
   ```

   记下输出中的`id`；它将在下文作为`<domain-id>`使用。

2. 找到要赋予该账户的角色。

   ```bash
   cmk list roles type=DomainAdmin filter=id,name
   ```

   | 角色 | 适用场景 |
   |---|---|
   | **Domain Admin**（推荐） | 完整功能集：VM、网络、用于Kubernetes的项目、VPC、镜像。其权限范围仅限于`nexcmp`域。 |
   | User | 仅限VM生命周期。普通用户无法彻底删除VM，除非全局设置`allow.user.expunge.recover.vm`为true；此时NexCMP会停止VM，CloudStack则会在`expunge.delay`后将其彻底删除。 |

3. 创建账户及其首个用户。请使用长随机密码；该密码之后无需再次输入。

   ```bash
   cmk create account name=nexcmp-api username=nexcmp-api \
     password='CHANGE-ME-LONG-RANDOM' email=ops@example.com \
     firstname=NexCMP lastname=API roleid=<role-id> domainid=<domain-id>
   ```

4. 为新用户生成API密钥对。

   ```bash
   cmk list users domainid=<domain-id> username=nexcmp-api filter=id,username
   cmk generate userkeys id=<user-id>
   ```

   复制`apikey`和`secretkey`。它们对应您在NexCMP中输入的**API key**和**Secret key**。NexCMP会加密存储它们，且后续仅显示最后四位字符。

5. 确保该域没有设置限制性的资源限制（Instances、卷、公网IP、网络、Snapshots、模板、项目）。

   ```bash
   cmk list resourcelimits domainid=<domain-id>
   ```

### 为客户VM创建访客网络 {#create-the-guest-network-for-customer-vms}

客户VM会部署在属于该新账户的一个访客网络中。带有虚拟路由器（VR）并启用Static NAT、Firewall和Port Forwarding服务的隔离网络非常适用，因为NexCMP会通过静态NAT为每台VM绑定一个公网IP。

```bash
cmk list networkofferings state=Enabled guestiptype=Isolated filter=id,name
cmk create network name=customers displaytext=customers zoneid=<zone-id> \
  networkofferingid=<offering-id> account=nexcmp-api domainid=<domain-id>
```

检查方案的默认出口策略：如果为“deny”，在添加防火墙出站规则之前，客户VM将无法访问外网。

### 使方案和模板可见 {#make-offerings-and-templates-visible}

- **Service offerings**和**network offerings**必须设为公开或分配给`nexcmp`域，否则该账户无法列出或使用它们。
- 注册或共享至少一个模板（请参阅[Templates](https://nexcmp.com/zh-cn/docs/infrastructure/templates/)）。NexCMP会列出就绪且设为精选（featured）的模板。

### 可选：基础设施页面的只读密钥 {#optional-read-only-key-for-infrastructure-pages}

**Capacity**、**Host**、**Storage**和**System VM**标签页以及公网IP范围列表使用第二个密钥，该密钥只需六个命令的读取权限。请创建受限角色，而不是直接复用完整的管理员密钥：

```bash
cmk create role name=nexcmp-readonly type=Admin
# <role-id> is the id printed above
for api in listHosts listCapacity listSystemVms listVlanIpRanges listClusters listStoragePools; do
  cmk create rolepermission roleid=<role-id> rule=$api permission=allow
done
cmk create rolepermission roleid=<role-id> rule='*' permission=deny
```

然后使用该角色创建一个账户（置于ROOT域中，因为它需要读取整个区域的数据），按照步骤4生成其密钥，并在下一节中将其输入为**RO API key**。

### 检查网络路径 {#check-the-network-path}

在面板服务器上：

```bash
curl -fsS -o /dev/null -w '%{http_code}\n' https://cloudstack.example.com/client/api
```

任何HTTP响应（即使是4xx）都表明端口可达。超时则意味着您这端存在防火墙或DNS问题。

## 在NexCMP中连接 {#connect-in-nexcmp}

### 在设置向导中 {#in-the-setup-wizard}

[设置向导](https://nexcmp.com/zh-cn/docs/getting-started/setup-wizard/)的第2步会要求提供相同的数值。点击**Test connection**将列出该密钥可见的区域与网络；选择区域和来宾网络、区域的显示名称以及国家/地区，然后点击**Save CloudStack**。向导会拒绝不在该区域内或对该密钥不可见的网络。

![向导第2步：已填写CloudStack API URL及密钥、并在点击Test connection后选定区域和网络](https://nexcmp.com/zh-cn/docs/images/infrastructure/cloudstack-01-wizard-step.webp)

### 稍后在管理控制台中 {#later-in-the-admin-console}

1. 打开**Infrastructure › Cloud provider › CloudStack**并选择**API connection**标签页。
2. 填写**Connection**卡片：

   | 字段 | 示例值 |
   |---|---|
   | Endpoint API | `https://cloudstack.example.com/client/api` |
   | API密钥（写入权限） | `XXXX`（留空以保留已保存的密钥） |
   | Secret key | `XXXX` |
   | 只读API密钥 / 只读Secret密钥 | 可选，来自只读账户 |
   | Zone ID | 您的区域UUID |

      ![显示示例端点与已掩码密钥的API connection标签页](https://nexcmp.com/zh-cn/docs/images/infrastructure/cloudstack-02-connect-form.webp)

3. 在保存前点击**Test connection**。它会在不保存的情况下测试您输入的密钥：使用`listZones`和`listCapabilities`测试写入密钥，使用`listSystemVms`测试只读密钥。


4. 点击**Save connection**。请保持**Enable CloudStack connection**处于开启状态；将其关闭会使worker停止所有CloudStack作业，但不会丢失数据。
5. 打开**Services › Virtual Machines › Policy › Provisioning**以设置默认来宾网络、自定义方案以及新虚拟机的默认密钥对。

      ![VM Policy的Provisioning标签页，显示默认网络ID](https://nexcmp.com/zh-cn/docs/images/infrastructure/cloudstack-04-provisioning.webp)

6. 打开**Infrastructure › Cloud provider › Sales IP pools**，在**Configure sales ranges**下设置**Sellable IP range prefixes**（例如`203.0.113.`）；如果该区域中的某些地址绝不能出售，还需设置**Excluded IP prefixes**。若允许出售所有空闲地址，请将前缀留空。

      ![已设置可售前缀203.0.113.的Sales IP pools](https://nexcmp.com/zh-cn/docs/images/infrastructure/cloudstack-05-sales-ip-pool.webp)

### NexCMP读取与写入的内容 {#what-nexcmp-reads-and-writes}

| 模块 | 读取 | 变更 |
|---|---|---|
| VMs | 列表、状态、用量历史、控制台端点 | 部署、启动、停止、重启、重装、销毁、调整配置、重置密码和SSH key |
| 磁盘与快照 | 卷、VM快照、备份 | 创建、挂载、卸载、扩容、删除、创建快照、恢复 |
| 网络 | 网络、路由器、公网IP、防火墙、端口转发、负载均衡器规则 | 关联与释放公网IP、静态NAT、防火墙、端口转发、出站规则，以及Private Cloud的网络与ACL |
| 目录 | 服务方案、磁盘方案与网络方案，模板，ISO，操作系统类型 | 注册与删除模板及ISO（Images），在创建自定义套餐时管理服务方案 |
| Kubernetes | 支持的版本、集群、配置 | 项目、资源限额、网络、集群（Kubernetes模块） |
| 只读密钥 | 主机、集群、存储池、系统虚拟机、容量、VLAN IP范围 | 无 |

### 实时CPU与内存及带宽 {#live-cpu-and-ram-and-bandwidth}

- **热插拔。**仅当模板允许（动态可扩展）且客户机系统使新CPU和内存上线时，运行中的虚拟机才能在不重启的情况下调整规格。对于名称以`vN`结尾且N为6或更大的模板，或者您在模板的**vCPU/RAM hot-plug**字段中手动设置时，NexCMP会开启Auto Scaling。请参阅[模板](https://nexcmp.com/zh-cn/docs/infrastructure/templates/)。
- **带宽统计来源。**在默认设置下，NexCMP会通过CloudStack虚拟机统计信息（`listVirtualMachinesUsageHistory`，每5分钟轮询一次，并按虚拟机网络接口进行汇总）来计量流量。由于该数据包含虚拟机之间的流量，因此可能会略高于边缘路由器的统计值。请保持CloudStack虚拟机统计信息收集处于启用状态；超出统计保留期限的断缺时间段将被跳过。请参阅[带宽](https://nexcmp.com/zh-cn/docs/catalog/bandwidth/)。

## 验证 {#verify}

1. **Test connection**返回“Write key: OK”以及您的资源域和CloudStack版本。
2. **Infrastructure › Cloud provider › Providers**中显示该提供商处于活动状态且包含最近的测试时间。仪表盘运行状况面板不再显示“CloudStack: not connected”。
3. **Sales IP pools**列出空闲地址（约每分钟刷新一次）。
4. 从客户门户或管理控制台订购一台小型虚拟机，检查其状态是否变为Running、已获取公网IP且可以打开控制台。

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

- 在此NexCMP版本中仅可连接一个CloudStack集群。**Add cloud provider**对话框可以测试第二个集群的密钥，但无法保存。
- 一个CloudStack资源域会挂接到NexCMP的默认资源域；拥有多个资源域的CloudStack将仅限于您输入的资源域，因此其他资源域的虚拟机、IP和网络都将被忽略。
- 在CloudStack中删除客户机网络会导致所有新部署失败。当该网络消失时，管理控制台会显示红色提示。
- 凭据绝不会离开服务器。API仅返回最后4个字符。

## 故障排查 {#troubleshooting}

| 症状 | 原因 | 解决办法 |
|---|---|---|
| `listCapabilities: cloudstack 401: unable to verify user credentials and/or request signature` | API key或secret错误、密钥属于其他用户，或面板服务器存在时钟偏差 | 使用`cmk generate userkeys`重新生成密钥并粘贴两者。检查面板服务器时间。 |
| 测试：`listZones: …`或超时 | 面板服务器无法访问API URL | 检查DNS、防火墙以及准确的`/client/api`路径。 |
| 向导：“network not found in that zone for this API key” | 所选网络属于其他账户或资源域 | 在专用账户中创建网络（见上文）并重新运行**Test connection**。 |
| 向导：“pick a zone and a network” | 未运行测试，或未选择资源域或网络 | 点击**Test connection**并在两个列表中进行选择。 |
| 横幅提示“CloudStack key not configured” | 尚未保存密钥（“Connect later”） | 填写Connection卡片，点击**Save connection**，然后点击**Test connection**。 |
| 横幅提示“CloudStack connection is OFF” | **Enable CloudStack connection**开关处于关闭状态 | 开启该开关并保存。 |
| 只读密钥：测试中提示“unusable …” | 缺少角色权限或账户错误 | 检查6个允许的命令，并确认该账户位于ROOT域中。 |
| “Zone public IP ranges not measured yet”或“no public IP ranges declared” | 没有只读密钥，或者该资源域确实没有公网IP范围 | 添加只读密钥，或在CloudStack中添加公网IP段。 |
| “资源池为空 — 等待60秒vmd同步” | IP列表由worker每分钟刷新一次 | 等待一分钟后重新加载。 |
| “网段203.0.113.中空闲IP已耗尽” | 可售前缀中的所有地址均已被占用 | 向区域添加地址、扩大前缀或释放未使用的IP。 |
| “获取网络数据失败（CloudStack未响应或密钥缺少权限）” | 密钥失去访问权限，或CloudStack已宕机 | 运行**Test connection**；检查该账户是否已启用。 |
| “来宾网络不存在” | 该网络已在CloudStack中被删除 | 重新创建该网络并在Provisioning下将其设为默认。 |