---
title: 作業系統範本與 ISO
description: 準備客戶部署時使用的作業系統映像檔：建置並註冊 CloudStack 範本，以及製作 Proxmox VE 雲端映像檔範本。
url: https://nexcmp.com/zh-tw/docs/infrastructure/templates/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# 作業系統範本與 ISO {#os-templates-and-isos}

> **管理後台位置：**Services › Virtual Machines › Template（`/vm/templates`）。Proxmox 範本會依叢集列於 Infrastructure › Cloud provider › Providers › (cluster) › Clusters。

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

範本是新 VM 啟動時所使用的作業系統映像檔。NexCMP 本身不儲存映像檔：它會讀取 CloudStack 回報的內容（就緒且精選的範本），或是讀取您為 Proxmox 叢集所列出的內容，並讓您選擇要銷售哪些項目，同時提供對客端名稱、圖示與登入使用者。本頁面說明如何準備能與 NexCMP 搭配良好的映像檔：密碼登入、即時 CPU 與 RAM 調整大小、置換檔案（swap file），以及會擴展至方案大小的根磁碟。

## 需求 {#requirements}

| 項目 | 需求 |
|---|---|
| CloudStack 範本建置工具 | 一台具備 `libguestfs-tools`（`virt-customize`、`virt-sparsify`、`guestfish`）、`qemu-utils`、`curl` 且約有 5 GB 可用磁碟空間的 Linux 機器。不需要 KVM 與 root 權限。需要網際網路存取權來安裝套件（或使用 `--offline` 建置）。 |
| 建置工具的位置 | 它隨面板伺服器上的 `/opt/nexcmp/releases/<version>/share/templates/` 隨附於每個版本中。您不需要在那裡執行它：將資料夾複製到任何 Linux 機器即可。 |
| 網頁伺服器 | 任何 CloudStack 次要儲存空間 VM 可以存取的 HTTP(S) 伺服器，用於發布完成的 `.qcow2` 檔案。它不需要從網際網路存取。 |
| CloudStack | 可註冊範本的帳戶，以及您的區域 ID 和相應的 OS 類型 ID。請參閱 [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/)。 |
| Proxmox VE | 搭配 QEMU 訪客代理程式的 Cloud-init 範本 VM，每個 OS 與每個節點一個。請參閱 [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/)。 |
| 相依於 | 需先連線 [CloudStack](https://nexcmp.com/zh-tw/docs/infrastructure/cloudstack/) 或 [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/)。 |

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

### CloudStack：建置範本 {#cloudstack-build-a-template}

支援的基礎映像檔（在變更任何內容之前，會先下載廠商映像檔並驗證其總和檢查碼）：

| 映像檔 | `--distro` | 登入使用者 |
|---|---|---|
| Ubuntu 22.04 | `ubuntu-22.04` | `ubuntu` |
| Ubuntu 24.04 | `ubuntu-24.04` | `ubuntu` |
| Debian 12 | `debian-12` | `debian` |
| Rocky Linux 9 | `rocky-9` | `rocky` |

更多發行版本：將一行新增至 `distros.conf`（映像檔 URL、總和檢查碼檔案、系列 `deb` 或 `rpm`）。

1. 將建置工具複製到建置機器並執行：

   ```bash
   cp -r /opt/nexcmp/releases/<version>/share/templates ~/templates && cd ~/templates
   ./build-template.sh --distro ubuntu-24.04 --version v7 --work ./out
   ```

   新增 `--panel-url https://cloud.example.com` 以植入選配的首日啟動監控代理程式，該代理程式會向您的面板註冊（僅限 HTTPS）。若沒有它，將不會新增任何代理程式。其他選項：`--base <file>` 用於使用您下載的映像檔，`--offline` 用於略過套件安裝。

2. 結果為 `out/ubuntu-24.04-v7.qcow2` 及其 `.sha256`。建置結束時會執行 `verify-image.sh`，以唯讀方式檢查完成的映像檔並拒絕不良的映像檔（它會保留為 `.unverified`）。您可以隨時再次執行它：`./verify-image.sh out/ubuntu-24.04-v7.qcow2 --no-agent`。

建置工具放入映像檔中的內容：

| 項目 | 原因 |
|---|---|
| `qemu-guest-agent` | CloudStack 可以向虛擬機器詢問 CPU 與 IP 資訊，並為快照將其靜止化。 |
| 具備 CloudStack 資料來源的 cloud-init、每次開機時的 `set_passwords`、SSH 密碼登入 | 產生的密碼從虛擬路由器取得，且 **Reset password** 可以正常運作。 |
| 用於動態新增 CPU 與 RAM 的 udev 規則 | 動態新增的 vCPU 與 RAM 會自動上線，因此即時調整大小與 Auto Scaling 能夠運作。 |
| 交換檔服務 | 在磁碟擴充後，建立 `/swapfile` 相當於 RAM 的 50% 與 4 GiB 中較小者。`touch /etc/cmp-swap.disabled` 可將其關閉。 |
| cloud-init `growpart` 與 `resizefs` | 小型的根磁碟會在首次開機時自動擴充至方案的磁碟大小。 |
| 空的 machine-id，無 SSH 主機金鑰 | 每個虛擬機器都會取得其專屬識別身分。 |

::: warning 將範本命名為 `<OS> <version> <vN>`
對於名稱結尾為 `vN` 或 `vN.M` 且 **N 為 6 或以上**（`Ubuntu 24.04 v7`、`Rocky Linux 9 v7.1`）的範本，NexCMP 會開啟 **Auto Scaling** 開關。建構工具會對 `--version` 強制執行此規則。請使用完全相符的列印名稱來註冊範本。
:::

3. 發布檔案並在 CloudStack 中註冊。使用建構時列印出的 SHA-256，且必須在檔案完全寫入後再進行註冊：

   ```bash
   cmk list ostypes keyword="Ubuntu 24.04" filter=id,description
   cmk register template name="Ubuntu 24.04 v7" displaytext="Ubuntu 24.04 v7" \
     url=https://files.example.com/ubuntu-24.04-v7.qcow2 zoneid=<zone-id> format=QCOW2 hypervisor=KVM \
     ostypeid=<os-type-id> passwordenabled=true sshkeyenabled=true isdynamicallyscalable=true \
     requireshvm=true isextractable=false ispublic=true isfeatured=true \
     checksum="{SHA-256}<sha256 of the file>" \
     details[0].guest.cpu.mode=host-passthrough details[0].rootDiskController=osdefault
   ```

   - `passwordenabled=true` 可讓 CloudStack 產生虛擬機器密碼。
   - `isdynamicallyscalable=true` 允許即時調整大小。
   - 當前的 Rocky 與 Alma 映像檔需要 `host-passthrough` 才能開機；`osdefault` 則可保持磁碟控制器可攜性。

4. 等待範本達到 **Download Complete / Ready**。

廠商映像檔會保持其原本的小虛擬大小（Ubuntu 與 Debian 約 3.5 GiB，Rocky 約 10 GiB）。請記住，方案的磁碟大小不得小於範本的磁碟大小。

### Proxmox VE：製作範本 {#proxmox-ve-make-a-template}

在我部署的每個節點上為每個作業系統建立一個 cloud-init 虛擬機器範本，並安裝 guest agent 並啟用 root 登入，然後將其註冊為 `os-key=vmid`。完整的指令位於 [Proxmox VE](https://nexcmp.com/zh-tw/docs/infrastructure/proxmox/) 中。上面的 CloudStack 產生器**不**適用於 Proxmox：它為 CloudStack 資料來源設定 cloud-init。

### ISOs {#isos}

客戶透過 **Images** 模組（CloudStack）或「獨立伺服器」模組掛載自己的 ISO。這些與本頁面上的作業系統範本是分開的。請參閱 [Modules](https://nexcmp.com/zh-tw/docs/infrastructure/modules/) 與 [Dedicated servers](https://nexcmp.com/zh-tw/docs/infrastructure/dedicated/)。

## 在 NexCMP 中連線 {#connect-in-nexcmp}

1. 前往**Services › Virtual Machines › Template**。點擊**Sync now**或等待最多 15 分鐘。同步功能會加入已就緒且在 CloudStack 中標記為精選的範本。

      ![顯示已同步範本及其就緒狀態與 CPU 熱插拔欄位的範本頁面](https://nexcmp.com/zh-tw/docs/images/infrastructure/templates-01-list.webp)

2. 點擊新範本上的 **Edit** 並設定客戶看到的內容：

   | 欄位 | 範例值 |
   |---|---|
   | 對客戶顯示的名稱 | `Ubuntu 24.04 LTS` |
   | OS family | `ubuntu`（圖示與預設使用者） |
   | Version | `24.04` |
   | Login username | `ubuntu`（Windows：`Administrator`；其他：`root`） |
   | Icon | 映像檔URL、路徑或名稱 |
   | 順序 | `10` |
   | 啟用 | 開啟 |
   | vCPU/RAM熱插拔（線上調整規格） | **Auto by name (v6 or later)**、**Yes** 或 **No (needs a restart)** |

      ![編輯範本對話方塊，包含客戶端名稱、作業系統家族、登入使用者與熱插拔選項](https://nexcmp.com/zh-tw/docs/images/infrastructure/templates-02-edit.webp)

3. 啟用範本。CloudStack 不再列出的範本會自動隱藏（如果已設定，您將會在 Telegram 中收到警報）；它永遠不會從 NexCMP 中刪除。

### 將範本替換為較新的建置版本 {#replace-a-template-with-a-newer-build}

對已販售的範本使用 **More › Replace with new version**。挑選新的、就緒且目前停用的範本。該販售項目隨即指向新建置版本並保留其名稱、順序與圖示；舊版本會被停用作為退回途徑（若要返回，請對新項目使用 **Replace**）。執行中的虛擬機器不會受到影響。若新建置版本屬於不同的作業系統家族，請先勾選確認。

## 驗證 {#verify}

1. 該列顯示 **ready**，對於名稱以 `vN` 結尾且 N 為 6 或以上的建置版本，則顯示 **CPU hot-plug: supported**。
2. 從該範本部署一臺測試虛擬機器並在虛擬機器內部檢查：
   - 您可以使用門戶中顯示的密碼登入；
   - `df -h /` 顯示方案的磁碟大小；
   - 在線上調整規模（執行不需重開機的 **Change plan**）後，`nproc` 與 `free -m` 會增長；
   - `swapon --show` 列出 `/swapfile`（可用空間小於置換空間加 2 GiB 的磁碟會被略過）；
   - `systemctl is-active qemu-guest-agent` 印出 `active`。
3. 如果您將代理程式打包進去，虛擬機器會在首次開機一分鐘後出現在面板的監控主機中。該虛擬機器需要專屬的公開 IP：面板透過其公開來源 IP 來識別它。

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

- 建置工具僅限 Linux 且用於建置 Linux 映像檔。其他映像檔（例如 Windows）可透過其他方式在 CloudStack 中註冊；NexCMP 會列出 CloudStack回報的內容。
- 僅隨附 amd64 代理程式；其他架構會略過代理程式安裝。
- 映像檔會透過 `guestfish` 進行檢查，但建置工具絕不會開機它。在販售新映像檔之前，務必先部署一臺測試虛擬機器。
- 在首次開機前使用 `touch /etc/cmp-agent.disabled` 在一臺虛擬機器上略過代理程式。稍後使用 `systemctl disable --now cmp-agent cmp-agent-install; rm -rf /etc/cmp-agent /usr/local/bin/cmp-agent` 將其移除，然後在管理員主控台中刪除該代理程式。

## 故障排除 {#troubleshooting}

| 症狀 | 原因 | 修正方式 |
|---|---|---|
| `virt-customize` 下載套件失敗 | 建置機器沒有對外網路 | 修正該機器上的 DNS 或代理伺服器，或在已具備這些套件的基礎映像檔上使用 `--offline` 進行建置。 |
| `libguestfs: error: /usr/bin/supermin exited with error status 1` | 主機核心無法被目前的使用者讀取（Ubuntu） | `sudo chmod +r /boot/vmlinuz*`，或以 root 身分執行建置。 |
| 檢查碼不同，或者供應商映像檔已不存在 | 供應商移動了他們的「最新」檔案 | 請自行下載映像檔，對照供應商的檢查碼檔案進行檢查，並透過 `--base` 傳遞。 |
| Rocky：較新的 XFS 無法掛載 | 主機核心過舊 | 在具有較新核心的機器上建置。 |
| `--version must be v6 or higher` | 名稱必須是 `vN` 且 N 為 6 或以上 | 使用 `--version v7`。 |
| `--panel-url must be a plain https:// URL` | 代理程式是以 root 身分下載並執行，因此拒絕純 HTTP | 使用不含空格、引號或查詢字串的 `https://` URL。 |
| 範本保持 **not ready** 狀態 | CloudStack 尚未完成下載 | 等待 **Download Complete**，檢查次要儲存虛擬機器是否能連線至該 URL。 |
| 該列顯示 **no-pass** | 註冊範本時未帶入 `passwordenabled=true` | 使用該旗標再次註冊。 |
| CPU 熱插拔顯示 **unsupported** | 名稱未以 `vN` 結尾（N 為 6 或以上） | 重新命名範本，若映像檔具備 udev 規則，則可在編輯中將 **vCPU/RAM hot-plug** 設定為 **Yes**。 |
| 首次連線後出現「Empty template list」 | 同步尚未執行 | 點擊 **Sync now**（需要背景工作程序執行中）或等待 15 分鐘的循環週期。 |