镜像管理

镜像是创建实例时使用的操作系统模板。Novaix 支持多种方式来管理镜像，您可以从远程仓库导入、从 URL 下载、手动上传，或者将远程镜像拉取到指定节点缓存。

镜像分组

镜像可以按分组组织管理。分组用于在用户购买页面中对镜像进行分类展示，例如「Linux」「Windows」「面板镜像」等。

在管理面板的「镜像管理」页面，您可以创建和管理镜像分组。创建镜像时选择所属分组即可归类。

TIP

分组名称会直接展示给用户，建议使用用户能理解的名称。未分组的镜像会归入默认分组。

镜像来源

来源	说明
远程仓库	从镜像仓库导入（如 images.linuxcontainers.org）
URL 下载	从指定 URL 下载镜像文件（最大 20GB）
手动上传	通过浏览器上传本地镜像文件
节点拉取	从远程镜像服务器拉取镜像到指定节点的本地缓存（不会创建全局镜像记录）

TIP

上传功能基于 TUS 协议实现断点续传，支持最大 50GB 的镜像文件。即使网络中断也可以继续上传，无需重新开始。

分发镜像

镜像导入到 Novaix 后，需要分发到具体的节点才能用于创建实例。在镜像详情页面，您可以选择要分发的目标节点。

分发是一个异步任务，对于较大的镜像文件可能需要一些时间，您可以在任务列表中查看进度。

如果目标节点上已存在相同的镜像，分发时会提示「目标节点上已存在该镜像」。此时可以选择覆盖分发，系统会在上传新镜像成功后自动切换别名，确保不会因上传失败而丢失旧镜像。

WARNING

导入 ≠ 可用。镜像导入到 Novaix 只是在管理平台中注册了一条记录，您还需要将镜像分发到具体的节点上才能用于创建实例。常见的操作遗漏是：导入了镜像、在套餐中选择了该镜像，但忘了将镜像分发到套餐所关联的节点上，导致用户创建实例时失败。

运行模式

创建或编辑镜像时，您可以配置镜像的运行模式：

字段	说明
运行模式	容器（Container）或虚拟机（VM）
启动模式	UEFI 或 BIOS（仅虚拟机）
磁盘模式	磁盘驱动类型（仅虚拟机）
CPU 模式	CPU 模拟模式（仅虚拟机）
TPM 2.0	启用虚拟 TPM 设备（仅虚拟机，Windows 11 和 Windows Server 2025 需要）

WARNING

运行模式需要与镜像的实际格式匹配。容器镜像不能以虚拟机模式运行，反之亦然。如果选择了错误的运行模式，实例创建将会失败。

Windows 镜像

Novaix 支持创建 Windows 虚拟机。由于 Windows 镜像无法从公共 Linux 镜像仓库获取，您需要自行准备镜像。

准备 Windows 镜像

推荐两种方式：

方式一：上传预构建 qcow2 镜像（推荐）

提前在本地构建好包含 VirtIO 驱动的 Windows qcow2 镜像，通过「上传镜像」功能导入 Novaix，分发到节点后即可用于创建实例。

方式二：从 ISO 安装

1. 在管理面板创建一台空盘虚拟机（镜像源类型选择「空盘」）
2. 上传 Windows 安装 ISO 和 VirtIO 驱动 ISO 到 ISO 管理
3. 在实例详情页同时挂载两个 ISO（系统 ISO + 驱动 ISO）
4. 通过控制台（VNC）完成 Windows 安装，安装时加载 VirtIO 存储驱动

TIP

您也可以使用 distrobuilder 的 repack-windows 命令预先将 VirtIO 驱动注入到 Windows ISO 中，这样只需挂载一个 ISO 即可完成安装。

推荐配置

创建 Windows 镜像时，建议按如下方式配置：

字段	推荐值	说明
操作系统	Windows 或 Windows Server
默认用户	Administrator	Windows 默认管理员账户
Cloud-Init	关闭	Windows 不支持 cloud-init
启动模式	UEFI 或 UEFI 安全启动
TPM 2.0	启用	Windows 11 和 Windows Server 2025 必须
磁盘模式	默认（virtio-scsi）	需镜像内已安装 VirtIO 驱动
最小磁盘	40 GB	Windows 系统盘建议不低于 40 GB
最小内存	2048 MB

虚拟机代理

Windows 镜像需预装虚拟机代理客户端工具。安装后，系统可通过虚拟机代理在实例运行期间直接执行密码重置和网络配置，无需依赖 cloud-init。

如果镜像未安装虚拟机代理，密码重置和网络变更操作将无法自动在实例内生效，用户需通过 VNC 控制台手动操作。

WARNING

关闭 Cloud-Init 后，系统不会自动注入密码和 SSH 密钥。用户购买 Windows 实例时，购买页面会提示需要在安装过程中手动设置密码。首次密码可在安装过程中设置，后续可通过面板的「重置密码」功能远程修改（需实例处于运行状态且已安装虚拟机代理）。

开机脚本

镜像支持配置 cloud-init 格式的开机脚本。实例创建时，系统会自动将镜像的开机脚本与用户的 SSH 公钥合并，注入到实例中。

TIP

开机脚本适用于需要在实例首次启动时自动执行初始化操作的场景，如安装软件包、配置服务等。编写时请遵循 cloud-init 的配置格式。

隐藏镜像

您可以将某些镜像标记为「隐藏」。隐藏的镜像不会在用户的购买页面中展示，但管理员仍可以在管理面板中查看和操作。

TIP

隐藏功能适用于已废弃但仍有存量实例在使用的镜像，或者仅供管理员内部使用的特殊镜像。

镜像存储

上传和下载的镜像文件存储在 config.yaml 中 storage.image_dir 指定的目录下（默认 data/images）。请确保该目录有足够的磁盘空间。

TIP

如果您同时使用多个节点，镜像只需上传一次到 Novaix，然后分发到各个节点即可。无需在每个节点上单独操作。

如果您配置了对象存储，镜像文件会异步归档到对象存储中。当本地文件因磁盘故障丢失时，系统会尝试从对象存储恢复；归档或恢复失败时仅记录告警日志，不影响其他功能。

ISO 管理

除了镜像，Novaix 还支持 ISO 文件管理。ISO 文件可以挂载到实例上，用于自定义安装操作系统或其他软件。

ISO 文件需要管理员手动放置到服务器上并在后台标记就绪（当前不支持浏览器上传和 URL 下载）。挂载和卸载 ISO 都是异步操作，可以在任务列表中查看进度。

TIP

ISO 挂载后，您需要通过控制台（Console）进入实例进行安装操作。安装完成后，记得卸载 ISO 并重启实例，否则实例可能会一直从 ISO 引导启动。