---
title: CloudStack
description: 將 Apache CloudStack 連線至 NexCMP：透過 cmk 建立專屬網域、帳號與 API 金鑰，然後在安裝精靈或管理主控台中輸入它們。
url: https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# CloudStack

> **Where in the admin:** Infrastructure › Cloud provider › CloudStack › API connection (`/infra/cloudstack?tab=connect`)。首次連線亦可在 [setup wizard](https://nexcmp.com/zh-tw/docs/getting-started/setup-wizard/) 的步驟 2 進行。

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

NexCMP 銷售執行於您的 Apache CloudStack 雲端上的虛擬機器。它透過 CloudStack API 部署、啟動、停止、調整大小、快照及刪除虛擬機器，從區域分派公用 IP 位址，讀取計費與頻寬使用量，並在管理主控台中顯示容量與健康狀態。CloudStack 保持作為hypervisor的真實資料來源；NexCMP 則是其上的店面、計費與入口網站。

當 CloudStack 是（或將成為）您的主要 VM 來源時，請使用此頁面。若要設定次要來源，請參閱 [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/)。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| CloudStack 版本 | 4.23 為經過測試的發行版本。VM 主控台需要 4.18 或更新版本，而執行中 VM 的 CPU/RAM 即時調整大小則需要搭配 KVM 的 4.23 版本。 |
| 區域類型 | 包含至少一個供客戶 VM 使用的客端網路以及擁有可用位址之公用 IP 範圍的區域。 |
| Hypervisor | KVM 為經過測試的 hypervisor。 |
| 帳號 | 為 NexCMP 建立的**專屬網域與帳號**。切勿使用 ROOT 管理員金鑰。 |
| API 連線能力 | 面板伺服器必須能夠透過 HTTP(S) 存取管理伺服器 API URL (`https://cloudstack.example.com/client/api`)。VM 主控台、頻寬與 Kubernetes 功能皆使用相同的端點。 |
| 選用的唯讀金鑰 | 第二組唯讀金鑰可讓管理主控台顯示主機、儲存、系統 VM 與公用 IP 範圍。銷售 VM 時不需要此項。 |
| 公用 IP | 區域中的可用公用 IPv4 位址。NexCMP 可銷售的前綴可在 Sales IP pools 下進行設定。 |
| 範本 | 至少一個就緒、啟用密碼的範本，以及您的帳戶能看見的一個服務方案。請參閱 [Templates](https://nexcmp.com/zh-tw/docs/infrastructure/templates/)。 |
| 儲存 | 帳戶磁碟區的主要儲存空間，如果您銷售快照或映像，則需次要儲存空間。 |
| 相依於 | 無。Kubernetes、私有雲、映像和頻寬皆依賴此頁面。 |

::: 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**（建議） | 完整功能集：虛擬機器、網路、Kubernetes 專案、VPC、映像。其權限範圍止於 `nexcmp` 網域。 |
   | 使用者 | 僅限虛擬機器生命週期。一般使用者無法刪除虛擬機器，除非全域設定 `allow.user.expunge.recover.vm` 為 true；隨後 NexCMP 會停止虛擬機器，而 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. 請確保該網域沒有嚴格的資源限制（實例、磁碟區、公用 IP、網路、快照、範本、專案）。

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

### 為客戶虛擬機器建立客體網路 {#create-the-guest-network-for-customer-vms}

客戶虛擬機器會部署至屬於該新帳戶的單一客體網路中。具有虛擬路由器 (VR) 以及靜態 NAT、防火牆和連接埠轉送服務的隔離網路運作良好，因為 NexCMP 會透過靜態 NAT 將公用 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」，則在新增防火牆對外傳輸規則之前，客戶虛擬機器將無法進行對外連線。

### 讓方案與範本可見 {#make-offerings-and-templates-visible}

- **服務方案**與**網路方案**必須設為公開或指派至 `nexcmp` 網域，否則帳戶將無法列出或使用它們。
- 註冊或共用至少一個範本（請參閱 [Templates](https://nexcmp.com/zh-tw/docs/infrastructure/templates/)）。NexCMP 會列出就緒且設為精選的範本。

### 選用：用於基礎設施頁面的唯讀金鑰 {#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-tw/docs/getting-started/setup-wizard/)的步驟 2 會要求輸入相同的數值。**Test connection** 會列出金鑰能看到的區域與網路；請選擇區域與訪客網路、區域的顯示名稱與國家，然後按一下 **Save CloudStack**。若網路不在該區域或金鑰無法存取，精靈將會拒絕。

![填入 CloudStack API URL 與金鑰，並在 Test connection 後選擇區域與網路的精靈步驟 2](https://nexcmp.com/zh-tw/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` |
   | RO API金鑰 / RO秘密金鑰 | 選擇性，來自唯讀帳號 |
   | Zone ID | 您的區域 UUID |

      ![帶有範例端點與遮罩金鑰的 API connection 標籤頁](https://nexcmp.com/zh-tw/docs/images/infrastructure/cloudstack-02-connect-form.webp)

3. 儲存前請先按一下 **Test connection**。它會測試您輸入的金鑰但不進行儲存：使用 `listZones` 和 `listCapabilities` 測試寫入金鑰，並使用 `listSystemVms` 測試唯讀金鑰。


4. 按一下 **Save connection**。請保持開啟 **Enable CloudStack connection**；將其關閉會使背景工作停止所有 CloudStack 作業，但不會遺失資料。
5. 開啟 **Services › Virtual Machines › Policy › Provisioning** 以設定預設訪客網路、自訂方案以及新虛擬機器的預設金鑰對。

      ![具有預設網路 ID 的 VM Policy、Provisioning 標籤頁](https://nexcmp.com/zh-tw/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-tw/docs/images/infrastructure/cloudstack-05-sales-ip-pool.webp)

### NexCMP 讀取與寫入的內容 {#what-nexcmp-reads-and-writes}

| 區域 | 讀取 | 變更 |
|---|---|---|
| VMs | 清單、狀態、使用歷史記錄、主控台端點 | 部署、啟動、停止、重新開機、重新安裝、銷毀、調整大小、重設密碼與 SSH key |
| 磁碟與快照 | 儲存卷、虛擬機器快照、備份 | 建立、掛載、卸載、調整大小、刪除、快照、還原 |
| 網路 | 網路、路由器、公用 IP、防火牆、連接埠轉發、負載平衡器規則 | 關聯與釋放公用 IP、靜態 NAT、防火牆、連接埠轉發、出口規則、私有雲網路與 ACL |
| 目錄 | 服務、磁碟與網路方案、範本、ISO、作業系統類型 | 註冊與刪除範本和 ISO（映像檔）、建立自訂方案時的服務方案 |
| Kubernetes | 支援的版本、叢集、組態 | 專案、資源限制、網路、叢集（Kubernetes 模組） |
| 唯讀金鑰 | 主機、叢集、儲存池、系統虛擬機器、容量、VLAN IP範圍 | 無 |

### 即時CPU與RAM以及頻寬 {#live-cpu-and-ram-and-bandwidth}

- **熱插拔。** 執行中的虛擬機器只有在模板允許（動態可擴展）且客體作業系統將新CPU與RAM上線時，才能在不重新啟動的情況下調整大小。當模板名稱以`vN`結尾且N大於或等於6，或當您在模板的**vCPU/RAM hot-plug**欄位中手動設定時，NexCMP會啟用Auto Scaling。請參閱[Templates](https://nexcmp.com/zh-tw/docs/infrastructure/templates/)。
- **頻寬來源。** 在預設設定下，NexCMP會從CloudStack虛擬機器統計資料中測量流量（`listVirtualMachinesUsageHistory`，每5分鐘輪詢一次並按虛擬機器網路介面加總）。這些數據包含虛擬機器之間的流量，因此可能會比邊界路由器計算的數值稍高。請保持啟用CloudStack虛擬機器統計資料收集功能；長於統計資料保留時間的間隔將被略過。請參閱[Bandwidth](https://nexcmp.com/zh-tw/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僅傳回最後四個字元。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| `listCapabilities: cloudstack 401: unable to verify user credentials and/or request signature` | API金鑰或密鑰錯誤、來自其他使用者的金鑰，或面板伺服器上的時鐘問題 | 使用`cmk generate userkeys`重新產生金鑰並貼上兩者。檢查面板伺服器時間。 |
| 測試：`listZones: …`或逾時 | 面板伺服器無法連線至API URL | 檢查DNS、防火牆與確切的`/client/api`路徑。 |
| 精靈：「在該區域中找不到此API金鑰的網路」 | 所選網路屬於其他帳戶或區域 | 在專用帳戶中建立網路（見上方）並再次執行**Test connection**。 |
| 精靈：「挑選區域與網路」 | 未執行測試，或未選取區域或網路 | 按一下**Test connection**並選擇這兩個清單。 |
| 橫幅「CloudStack key not configured」 | 尚未儲存金鑰（「Connect later」） | 填寫連線卡片、**Save connection**，然後**Test connection**。 |
| 橫幅「CloudStack connection is OFF」 | **Enable CloudStack connection**開關已關閉 | 將其切換為開並儲存。 |
| 唯讀金鑰：測試中出現「unusable …」 | 缺少角色權限或帳戶錯誤 | 檢查六個允許的指令以及帳戶是否位於ROOT網域中。 |
| 「Zone public IP ranges not measured yet」或「no public IP ranges declared」 | 沒有唯讀金鑰，或該區域確實沒有公用範圍 | 新增唯讀金鑰，或在 CloudStack 中新增公開 IP 範圍。 |
| "集Pool為空——等待60秒進行vmd同步" | Worker 每分鐘會重新整理一次 IP 清單 | 等待一分鐘後重新載入。 |
| "範圍203.0.113.中的免費IP已耗盡" | 可銷售的前綴中的所有位址均已被佔用 | 將位址新增至區域、擴大前綴或釋放未使用的 IP。 |
| "無法取得網路資料（CloudStack無回應或金鑰權限不足）" | 金鑰失去存取權限，或者 CloudStack 離線 | 執行 **Test connection**；檢查帳戶是否已啟用。 |
| "訪客網路不存在" | 該網路已在 CloudStack 中刪除 | 重新建立網路並在 Provisioning 下將其設為預設值。 |