---
title: 操作系统模板与ISO
description: 准备供客户部署的操作系统镜像：构建并注册CloudStack模板，制作Proxmox VE cloud-image模板。
url: https://nexcmp.com/zh-cn/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}

模板是新虚拟机启动所基于的操作系统镜像。NexCMP本身不存储镜像：它读取CloudStack上报的内容（就绪的精选模板）或您为Proxmox集群列出的内容，并让您选择售卖哪些镜像，同时配置面向客户的名称、图标和登录用户。本页介绍如何准备与NexCMP良好协同的镜像：密码登录、CPU和内存动态热缩放、swap交换文件，以及自动扩容至套餐规格的根磁盘。

## 前提条件 {#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机器。 |
| Web服务器 | CloudStack二级存储虚拟机可访问的任意HTTP(S)服务器，用于发布生成好的`.qcow2`文件。无需暴露至公网。 |
| CloudStack | 具备模板注册权限的账户，以及对应区域和匹配操作系统类型的ID。参见[CloudStack](https://nexcmp.com/zh-cn/docs/infrastructure/cloudstack/)。 |
| Proxmox VE | 带有QEMU guest agent的Cloud-init模板虚拟机，每个操作系统及每个节点各一个。参见[Proxmox VE](https://nexcmp.com/zh-cn/docs/infrastructure/proxmox/)。 |
| 依赖项 | 需先连接[CloudStack](https://nexcmp.com/zh-cn/docs/infrastructure/cloudstack/)或[Proxmox VE](https://nexcmp.com/zh-cn/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`可植入可选的首次启动监控Agent，该Agent会自动向您的面板注册（仅限HTTPS）。如果不加该参数，则不会添加Agent。其他选项：`--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。 |
| swap文件服务 | 磁盘扩容后创建`/swapfile`，大小为RAM的50%与4 GiB中的较小者。`touch /etc/cmp-swap.disabled`可将其关闭。 |
| cloud-init `growpart`与`resizefs` | 较小的根磁盘在首次启动时自动扩容至套餐规定的磁盘大小。 |
| 清空machine-id，无SSH主机密钥 | 每台虚拟机都会生成自身独有的标识。 |

::: warning 将模板命名为`<OS> <version> <vN>`
NexCMP会为名称以`vN`或`vN.M`结尾且**N大于等于6**（`Ubuntu 24.04 v7`、`Rocky Linux 9 v7.1`）的模板开启**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}

在部署的目标各节点上按操作系统分别构建已安装guest agent并启用root登录的cloud-init虚拟机模板，然后将其注册为`os-key=vmid`。完整命令参见[Proxmox VE](https://nexcmp.com/zh-cn/docs/infrastructure/proxmox/)。上述CloudStack构建器**不适用于**Proxmox：它针对的是CloudStack数据源来配置cloud-init。

### ISO镜像 {#isos}

客户可通过**Images**模块（CloudStack）或独立服务器模块挂载自己的ISO镜像。这些镜像独立于本页中的操作系统模板。参见[模块](https://nexcmp.com/zh-cn/docs/infrastructure/modules/)与[独立服务器](https://nexcmp.com/zh-cn/docs/infrastructure/dedicated/)。

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

1. 打开**Services › Virtual Machines › Template**。点击**Sync now**或等待最多15分钟。同步会添加在CloudStack中已就绪且推荐的模板。

      ![Template页面列出了已同步的模板及其就绪状态和CPU热插拔列](https://nexcmp.com/zh-cn/docs/images/infrastructure/templates-01-list.webp)

2. 点击新模板上的**Edit**，设置客户看到的内容：

   | 字段 | 示例值 |
   |---|---|
   | 客户显示名称 | `Ubuntu 24.04 LTS` |
   | 操作系统系列 | `ubuntu`（图标和默认用户） |
   | 版本 | `24.04` |
   | 登录用户名 | `ubuntu`（Windows：`Administrator`；其他：`root`） |
   | 图标 | 图片URL、路径或名称 |
   | 排序 | `10` |
   | 启用 | 开启 |
   | vCPU/RAM热插拔（在线扩容） | **Auto by name (v6 or later)**、**Yes**或**No (needs a restart)** |

      ![编辑模板对话框，包含面向客户的名称、操作系统系列、登录用户和热插拔选项](https://nexcmp.com/zh-cn/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`（可用空间小于swap大小加2 GiB的磁盘会跳过）；
   - `systemctl is-active qemu-guest-agent`输出`active`。
3. 如果您预装了agent，虚拟机在首次启动一分钟后便会出现在面板的受监控主机列表中。虚拟机需要拥有独立的公网IP：面板通过其公网源IP进行识别。

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

- 构建器仅支持Linux并构建Linux镜像。其他镜像（例如Windows）可以通过其他方式在CloudStack中注册；NexCMP会列出CloudStack上报的内容。
- 仅附带amd64架构的agent；其他架构会跳过agent安装。
- 镜像会通过`guestfish`进行检查，但构建器绝不会启动它。在上架新镜像前，请务必先部署一台测试虚拟机。
- 在首次启动前使用`touch /etc/cmp-agent.disabled`跳过单台虚拟机上的agent。后续可使用`systemctl disable --now cmp-agent cmp-agent-install; rm -rf /etc/cmp-agent /usr/local/bin/cmp-agent`将其移除，然后在管理控制台中删除该agent。

## 故障排查 {#troubleshooting}

| 症状 | 原因 | 解决办法 |
|---|---|---|
| `virt-customize`下载软件包失败 | 构建机无法访问外网 | 修复该机器上的DNS或代理，或者在已包含这些软件包的基础镜像上使用`--offline`进行构建。 |
| `libguestfs: error: /usr/bin/supermin exited with error status 1` | 当前用户对宿主机内核没有读取权限（Ubuntu） | `sudo chmod +r /boot/vmlinuz*`，或以root身份运行构建。 |
| 校验和不一致，或上游镜像已不存在 | 上游厂商移动了其“latest”文件 | 自行下载该镜像，对照厂商的校验和文件进行核对，并通过`--base`传入。 |
| Rocky：较新版本的XFS无法挂载 | 宿主机内核版本过旧 | 在内核版本较新的机器上进行构建。 |
| `--version must be v6 or higher` | 名称必须为`vN`且N大于或等于6 | 使用`--version v7`。 |
| `--panel-url must be a plain https:// URL` | agent以root身份下载并运行，因此拒绝使用明文HTTP | 使用不含空格、引号或查询参数的`https://` URL。 |
| 模板一直处于**not ready**状态 | CloudStack尚未完成下载 | 等待显示**Download Complete**，检查二级存储虚拟机能否访问该URL。 |
| 该行显示**no-pass** | 注册模板时未添加`passwordenabled=true` | 带上该参数重新注册。 |
| CPU热插拔显示为**unsupported** | 名称未以`vN`结尾（N大于或等于6） | 重命名该模板，或者若镜像已包含udev规则，在Edit中将**vCPU/RAM hot-plug**设置为**Yes**。 |
| 首次连接后显示“Empty template list” | 同步尚未运行 | 点击**Sync now**（需要worker处于运行状态）或等待15分钟周期同步。 |