操作系统模板与ISO

**管理后台位置：**Services › Virtual Machines › Template（/vm/templates）。Proxmox模板按集群列在Infrastructure › Cloud provider › Providers › (cluster) › Clusters上。

功能说明

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

前提条件

项目	要求
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。
Proxmox VE	带有QEMU guest agent的Cloud-init模板虚拟机，每个操作系统及每个节点各一个。参见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可植入可选的首次启动监控Agent，该Agent会自动向您的面板注册（仅限HTTPS）。如果不加该参数，则不会添加Agent。其他选项：--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。
swap文件服务	磁盘扩容后创建`/swapfile`，大小为RAM的50%与4 GiB中的较小者。`touch /etc/cmp-swap.disabled`可将其关闭。
cloud-init `growpart`与`resizefs`	较小的根磁盘在首次启动时自动扩容至套餐规定的磁盘大小。
清空machine-id，无SSH主机密钥	每台虚拟机都会生成自身独有的标识。

将模板命名为<OS> <version> <vN>

NexCMP会为名称以vN或vN.M结尾且N大于等于6（Ubuntu 24.04 v7、Rocky Linux 9 v7.1）的模板开启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：制作模板

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

ISO镜像

客户可通过Images模块（CloudStack）或独立服务器模块挂载自己的ISO镜像。这些镜像独立于本页中的操作系统模板。参见模块与独立服务器。

在NexCMP中连接

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

点击新模板上的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)

编辑模板对话框，包含面向客户的名称、操作系统系列、登录用户和热插拔选项

启用该模板。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（可用空间小于swap大小加2 GiB的磁盘会跳过）；
- systemctl is-active qemu-guest-agent输出active。
如果您预装了agent，虚拟机在首次启动一分钟后便会出现在面板的受监控主机列表中。虚拟机需要拥有独立的公网IP：面板通过其公网源IP进行识别。

限制与注意事项

构建器仅支持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。

故障排查

症状	原因	解决办法
`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分钟周期同步。

操作系统模板与ISO ​

功能说明 ​

前提条件 ​

准备基础设施 ​

CloudStack：构建模板 ​

Proxmox VE：制作模板 ​

ISO镜像 ​

在NexCMP中连接 ​

用更新的构建版本替换模板 ​

验证 ​

限制与注意事项 ​

故障排查 ​