作業系統範本與 ISO

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

功能

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

需求

項目	需求
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。
Proxmox VE	搭配 QEMU 訪客代理程式的 Cloud-init 範本 VM，每個 OS 與每個節點一個。請參閱 Proxmox VE。
相依於	需先連線 CloudStack 或 Proxmox VE。

準備基礎設施

CloudStack：建置範本

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

映像檔	`--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）。

將建置工具複製到建置機器並執行：
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 用於略過套件安裝。
結果為 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 主機金鑰	每個虛擬機器都會取得其專屬識別身分。

將範本命名為 <OS> <version> <vN>

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

發布檔案並在 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 則可保持磁碟控制器可攜性。

等待範本達到 Download Complete / Ready。

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

Proxmox VE：製作範本

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

ISOs

客戶透過 Images 模組（CloudStack）或「獨立伺服器」模組掛載自己的 ISO。這些與本頁面上的作業系統範本是分開的。請參閱 Modules 與 Dedicated servers。

在 NexCMP 中連線

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

點擊新範本上的 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)

編輯範本對話方塊，包含客戶端名稱、作業系統家族、登入使用者與熱插拔選項

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

將範本替換為較新的建置版本

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

驗證

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

限制與注意事項

建置工具僅限 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 將其移除，然後在管理員主控台中刪除該代理程式。

故障排除

症狀	原因	修正方式
`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 分鐘的循環週期。

作業系統範本與 ISO ​

功能 ​

需求 ​

準備基礎設施 ​

CloudStack：建置範本 ​

Proxmox VE：製作範本 ​

ISOs ​

在 NexCMP 中連線 ​

將範本替換為較新的建置版本 ​

驗證 ​

限制與注意事項 ​

故障排除 ​