WEWhaleEngine Hyper-V
零基础 · 一步一步操作

Windows 与 Linux
Hyper-V 模板制作教程

从下载系统、创建虚拟机、安装系统,到封装 VHDX、生成校验文件、写 Manifest、让 Agent 扫描入库,全流程都写清楚。

最终要得到 3 个同名文件
  1. 系统模板.vhdx:模板系统盘
  2. 系统模板.vhdx.sha256:完整性校验
  3. 系统模板.vhdx.template.json:模板说明
最重要:VHDX 封装完成后必须设为“只读”,并且不能再次启动模板虚拟机。

先选择:自己制作,还是下载现成模板?

如果只是想尽快测试开通,优先下载已经验证过的现成模板。如果要安装自己的软件、补丁或安全策略,再自己制作。

方式 A:下载现成模板

适合第一次部署。下载 VHDX、Manifest 和 SHA-256 三个文件,放进模板目录后扫描。

打开模板下载站
方式 B:自己制作模板

适合需要预装软件或定制系统。请完整走完本页对应系统的全部步骤,不要跳过封装与验证。

安全提醒:本教程中的“清理、Sysprep、删除机器标识、删除 SSH Host Key”只能在专门创建的模板虚拟机内执行。不要在宿主机、生产 VM 或客户 VM 内执行。

开始前准备

1
使用专用模板 VM
不要拿正在运营的客户 VM 制作。
2
预留磁盘空间
ISO、临时 VM、最终 VHDX 至少预留 100GB。
3
准备临时网络
安装更新时需要联网,封装前再清理固定网络信息。
4
记录模板参数
系统版本、Generation、管理员账号、启动方式必须和 Manifest 一致。
推荐目录:ISO 放在 D:\Templates\ISO,制作中的临时 VM 放在 D:\Hyper-V\TemplateBuild,最终模板放在 Manager“存储与模板”页面显示的模板目录。

软件与系统官方下载地址

以下只放官方来源。系统版本会更新,因此使用官方选择页,不使用来源不明的网盘镜像。

Windows Server 2025Microsoft Evaluation Center可下载简体中文 ISO;评估版仅用于测试,正式商用请使用合法授权介质。

Windows Server 模板制作:完整流程

推荐组合:Windows Server 2022/2025、第二代虚拟机、UEFI 安全启动、60GB VHDX、Administrator、RDP 3389。
1

下载 ISO,并验证文件没有损坏

  1. 从上面的 Microsoft 官方页面下载简体中文 64 位 ISO。
  2. 把 ISO 放到 D:\Templates\ISO。
  3. 以管理员身份打开 PowerShell,执行下面命令。能正常返回 64 位 SHA-256 就说明文件可读取。
在 Hyper-V 宿主机执行
Get-FileHash -Algorithm SHA256 "D:\Templates\ISO\Windows_Server_2022.iso"
2

在 Hyper-V 管理器创建专用模板 VM

按界面逐项点击
  1. 打开“服务器管理器”→“工具”→“Hyper-V 管理器”。
  2. 右侧点击“新建”→“虚拟机”→“下一步”。
  3. 名称填写 TEMPLATE-WIN2022,位置选择 D:\Hyper-V\TemplateBuild。
  4. “指定代数”选择第二代。创建后不能再改代数。
  5. 启动内存建议 4096MB;制作时可以不开动态内存。
  6. 网络选择一个能临时访问互联网的外部虚拟交换机。
  7. 创建 VHDX,路径放在临时 VM 目录,大小填写 60GB。
  8. 安装选项选择“从可启动映像文件安装”,选中刚下载的 ISO。
  9. 确认摘要,点击“完成”。
安全启动:右键 VM →“设置”→“安全性”,勾选“启用安全启动”,模板选择 Microsoft Windows。
3

安装 Windows Server

  1. 连接 VM,点击“启动”。出现“Press any key to boot from CD or DVD”时马上按 Enter。
  2. 选择语言、时间和键盘,点击“现在安装”。
  3. 选择带“桌面体验”的版本(需要图形界面时),不要误选 Server Core。
  4. 选择“自定义:仅安装 Windows”。
  5. 选中 60GB 未分配空间,直接点击“下一步”,让安装程序自动分区。
  6. 等待安装完成,设置 Administrator 临时密码并登录。
4

更新系统并做基础检查

  1. 反复运行 Windows Update,直到没有必须安装的更新。
  2. 设备管理器中不能有未知设备。
  3. 确认系统盘是 C 盘,且系统能正常关机、重启。
  4. 不要加入域,不要写入客户 IP、客户密码、授权码和业务数据。
  5. 需要预装软件时现在安装;安装完成后重启一次,确认软件正常。
在 Windows 模板 VM 内,以管理员 PowerShell 执行
Get-ComputerInfo | Select-Object WindowsProductName,WindowsVersion,OsBuildNumber
Get-Disk | Format-Table Number,FriendlyName,PartitionStyle,OperationalStatus
Get-NetAdapter | Format-Table Name,Status,MacAddress,LinkSpeed
5

封装前清理

  1. 卸载只用于制作模板的临时工具。
  2. 清空回收站和临时文件。
  3. 确认 Windows 没有等待重启的更新。
  4. 把网络改回 DHCP;不要保留模板制作网络的固定 IP。
  5. 关闭所有程序,只保留管理员 PowerShell。
在 Windows 模板 VM 内执行
Get-NetIPInterface -AddressFamily IPv4 | Format-Table InterfaceAlias,Dhcp,ConnectionState
powercfg /h off
Dism.exe /Online /Cleanup-Image /StartComponentCleanup
不要手工删除网卡驱动。Agent 会在克隆后的 VM 第一次启动时写入主机名、管理员密码、IP、RDP 端口和防火墙配置。
6

运行 Sysprep 通用化,并让 VM 自动关机

这是 Windows 模板最关键的一步。必须带 /generalize,否则复制出来的 VM 会保留 SID 和设备身份。

在 Windows 模板 VM 内,以管理员 CMD 或 PowerShell 执行
C:\Windows\System32\Sysprep\Sysprep.exe /generalize /oobe /shutdown /mode:vm
  1. 命令执行后耐心等待,VM 会自动关机。
  2. Hyper-V 管理器状态必须显示“已关闭”。
  3. 从现在开始绝对不要再次启动这个模板 VM。一旦误启动,应重新执行本步骤后再取盘。

Microsoft 官方说明:Sysprep 命令行选项。

7

在宿主机复制系统盘,生成最终 VHDX

  1. 先在 VM“设置”→“SCSI 控制器”→“硬盘驱动器”里确认系统 VHDX 的真实路径。
  2. 确认 VM 已关闭,没有检查点,没有挂载 ISO。
  3. 把系统 VHDX复制到 Manager 显示的模板目录。
  4. 文件名只用英文、数字、短横线,避免空格和特殊符号。
在 Hyper-V 宿主机管理员 PowerShell 执行;先修改源路径
$source = "D:\Hyper-V\TemplateBuild\TEMPLATE-WIN2022\Virtual Hard Disks\TEMPLATE-WIN2022.vhdx"
$target = "D:\Templates\Windows-Server-2022-Template.vhdx"

if ((Get-VM "TEMPLATE-WIN2022").State -ne "Off") { throw "模板 VM 尚未关机" }
Copy-Item -LiteralPath $source -Destination $target
Get-Item -LiteralPath $target | Select-Object FullName,Length,IsReadOnly
8

创建 Windows Manifest

在 VHDX 旁边创建 Windows-Server-2022-Template.vhdx.template.json,内容如下。imageCode 是业务系统真正使用的模板编号。

Windows Manifest(UTF-8 JSON)
{
  "schemaVersion": 2,
  "imageCode": "windows-server-2022-dc-gui-zh-cn",
  "displayName": "Windows Server 2022 Datacenter GUI zh-CN",
  "enabled": true,
  "generation": 2,
  "secureBootEnabled": true,
  "secureBootTemplate": "MicrosoftWindows",
  "guestOs": "windows",
  "osFamily": "windows",
  "osDistribution": "windows-server",
  "adminUsername": "Administrator",
  "defaultLoginUser": "Administrator",
  "defaultLoginProtocol": "rdp",
  "defaultLoginPort": 3389,
  "provisioningMode": "windows-unattend",
  "supportsReinstall": true,
  "supportsPasswordChange": true,
  "supportsCustomRemotePort": true,
  "supportsAdditionalIpAddresses": true,
  "supportsSecurityGroup": true,
  "supportsConsole": true,
  "cloudInitRequired": false,
  "dataDiskSupported": true,
  "minimumSystemDiskGB": 60,
  "maximumSystemDiskGB": 65536
}
9

生成 SHA-256、设置只读、扫描验收

在 Hyper-V 宿主机管理员 PowerShell 执行
$vhdx = "D:\Templates\Windows-Server-2022-Template.vhdx"
$hash = (Get-FileHash -Algorithm SHA256 -LiteralPath $vhdx).Hash
Set-Content -LiteralPath ($vhdx + ".sha256") -Value $hash -Encoding Ascii
Set-ItemProperty -LiteralPath $vhdx -Name IsReadOnly -Value $true

Get-Item -LiteralPath $vhdx | Select-Object FullName,Length,IsReadOnly
Get-Content -LiteralPath ($vhdx + ".sha256")
  1. 打开 WhaleEngine Manager。
  2. 进入“存储与模板”。
  3. 确认模板目录就是 VHDX 所在目录。
  4. 点击“扫描模板目录”。
  5. 结果必须显示“可用”,不能出现只读、SHA-256 或 Manifest 错误。
  6. 在业务系统执行“同步节点模板”,再用测试 IP 创建一台 VM。
  7. 验证主机名、管理员密码、IP、网关、DNS、RDP 随机端口、控制台和系统盘扩容。

Linux 模板制作:完整流程

推荐组合:Ubuntu 24.04 LTS / Rocky Linux 9 / AlmaLinux 9、第二代虚拟机、30GB VHDX、cloud-init NoCloud、root、SSH 22。
1

选择一个仍在维护的 Linux 版本

新模板优先 Ubuntu LTS、Rocky Linux 或 AlmaLinux 当前受支持版本。CentOS 7 已结束生命周期,只用于兼容旧业务,不建议新部署。

  1. 从本页“软件下载”中的官方地址下载 x86_64/amd64 Server 或 Minimal ISO。
  2. 下载同目录的 CHECKSUM/SHA256SUMS。
  3. 把 ISO 放进 D:\Templates\ISO 并校验 SHA-256。
在 Hyper-V 宿主机执行
Get-FileHash -Algorithm SHA256 "D:\Templates\ISO\ubuntu-24.04-live-server-amd64.iso"
2

创建 Linux 模板 VM

Hyper-V 管理器设置
  1. 新建 VM,名称例如 TEMPLATE-UBUNTU2404。
  2. 选择第二代。
  3. 分配 2 个 vCPU、2048–4096MB 内存。
  4. 系统盘创建 30GB VHDX。
  5. 连接能临时上网的虚拟交换机。
  6. 挂载下载的 Linux ISO。
  7. 右键 VM →“设置”→“安全性”→启用安全启动,模板选择 Microsoft UEFI 证书颁发机构。
如果发行版无法从 ISO 启动,先确认安全启动模板是否选对。只有确实不兼容时才关闭安全启动,并把 Manifest 的 secureBootEnabled 改为 false。
3

安装 Ubuntu:按安装界面逐项选择

  1. 启动 VM,选择“Try or Install Ubuntu Server”。
  2. 语言可选 English;键盘按实际选择。
  3. 网络先使用 DHCP,保证安装阶段能上网。
  4. Proxy 留空;Mirror 使用默认或可访问的镜像源。
  5. Storage 选择“Use an entire disk”,确认只操作这台模板 VM 的 30GB 虚拟盘。
  6. Profile 临时创建 templateadmin 用户和临时密码;主机名填写 template-linux。
  7. SSH Setup 勾选“Install OpenSSH server”。
  8. 不需要安装额外 Snap 软件,等待安装完成后重启。
  9. 重启前如果提示移除安装介质,在 Hyper-V 设置中弹出 ISO,再按 Enter。

Rocky/AlmaLinux 安装时选择 Minimal Install、自动分区、启用网络并设置 root 临时密码;其余流程相同。

4

安装并启用 cloud-init、SSH 和扩盘工具

下面两组命令只能选与你系统匹配的一组,不要两组都执行。

Ubuntu / Debian:在 Linux 模板 VM 内执行
sudo apt update
sudo apt -y full-upgrade
sudo apt -y install cloud-init cloud-guest-utils openssh-server python3 e2fsprogs
sudo systemctl enable --now ssh
cloud-init --version
systemctl is-enabled ssh
ss -lntp | grep ':22'
Rocky / AlmaLinux:在 Linux 模板 VM 内执行
sudo dnf -y update
sudo dnf -y install cloud-init cloud-utils-growpart openssh-server python3 e2fsprogs
sudo systemctl enable --now cloud-init sshd
cloud-init --version
systemctl is-enabled sshd
ss -lntp | grep ':22'
必须满足:cloud-init 能运行、SSH 22 正在监听、系统有 Python 3、系统盘能使用 growpart 扩容。Agent 首次启动会设置 root 密码、随机 SSH 端口、网络和防火墙。
5

确认 NoCloud 数据源可用

WhaleEngine 会给新 VM 挂载标签为 CIDATA 的 NoCloud ISO。模板必须允许 cloud-init 从 NoCloud 读取配置。

在 Linux 模板 VM 内执行
cloud-init status --long
test -d /etc/cloud && echo "cloud-init 配置目录存在"
grep -R "NoCloud" /etc/cloud/cloud.cfg /etc/cloud/cloud.cfg.d 2>/dev/null || true
不要把 cloud-init 卸载掉,也不要把 datasource 强制锁定成 Azure。没有 NoCloud,Agent 会一直等待在 90%,最终报 not_ready:cloud_init。
6

禁用文本控制台自动黑屏

这样 HTML5 控制台长时间打开后仍能看到登录界面,不需要先按 Enter 唤醒。

Ubuntu / Debian:在 Linux 模板 VM 内执行
sudo sed -i 's/^GRUB_CMDLINE_LINUX_DEFAULT="\(.*\)"/GRUB_CMDLINE_LINUX_DEFAULT="\1 consoleblank=0"/' /etc/default/grub
sudo update-grub
Rocky / AlmaLinux:在 Linux 模板 VM 内执行
sudo grubby --update-kernel=ALL --args="consoleblank=0"

如果命令提示参数已经存在,不需要重复添加。Agent 首次开通时也会再次保证 consoleblank=0。

7

封装前清理 Linux 唯一身份

再次确认:以下命令只在即将封装的 Linux 模板 VM 内执行。执行后不要再拿这台 VM 当普通服务器使用。
  1. 确认系统更新完毕并重启一次。
  2. 重新登录,确认 SSH、cloud-init 都存在。
  3. 清理 cloud-init 状态、机器 ID、SSH Host Key、日志和 Shell 历史。
  4. 执行关机,之后不要再次启动。
在 Linux 模板 VM 内执行;最后一行会关机
sudo cloud-init clean --logs --machine-id
sudo rm -rf /var/lib/cloud/instances/* /var/lib/cloud/instance
sudo rm -f /etc/ssh/ssh_host_*
sudo truncate -s 0 /etc/machine-id
sudo rm -f /var/lib/dbus/machine-id
sudo ln -s /etc/machine-id /var/lib/dbus/machine-id
sudo rm -f /root/.bash_history /home/*/.bash_history
sudo find /var/log -type f -exec truncate -s 0 {} \;
sudo sync
sudo fstrim -av || true
sudo shutdown -h now

cloud-init clean --machine-id 会把系统恢复到可克隆状态;新 VM 首次启动时会生成新的机器身份和 SSH Host Key。

8

在宿主机复制 Linux 系统盘

在 Hyper-V 宿主机管理员 PowerShell 执行;先修改源路径
$source = "D:\Hyper-V\TemplateBuild\TEMPLATE-UBUNTU2404\Virtual Hard Disks\TEMPLATE-UBUNTU2404.vhdx"
$target = "D:\Templates\ubuntu-24.04-x86_64.vhdx"

if ((Get-VM "TEMPLATE-UBUNTU2404").State -ne "Off") { throw "模板 VM 尚未关机" }
Copy-Item -LiteralPath $source -Destination $target
Get-Item -LiteralPath $target | Select-Object FullName,Length,IsReadOnly
9

创建 Linux Manifest

在 VHDX 旁边创建 ubuntu-24.04-x86_64.vhdx.template.json:

Ubuntu 24.04 Manifest(UTF-8 JSON)
{
  "schemaVersion": 2,
  "imageCode": "ubuntu-24.04-x86_64",
  "displayName": "Ubuntu 24.04 LTS x86_64",
  "enabled": true,
  "generation": 2,
  "secureBootEnabled": true,
  "secureBootTemplate": "MicrosoftUEFICertificateAuthority",
  "guestOs": "linux",
  "osFamily": "linux",
  "osDistribution": "ubuntu-24.04",
  "adminUsername": "root",
  "defaultLoginUser": "root",
  "defaultLoginProtocol": "ssh",
  "defaultLoginPort": 22,
  "provisioningMode": "cloud-init-nocloud",
  "supportsReinstall": true,
  "supportsPasswordChange": true,
  "supportsCustomRemotePort": true,
  "supportsAdditionalIpAddresses": true,
  "supportsSecurityGroup": true,
  "supportsConsole": true,
  "cloudInitRequired": true,
  "dataDiskSupported": true,
  "minimumSystemDiskGB": 30,
  "maximumSystemDiskGB": 65536,
  "linuxInitSystem": "systemd",
  "linuxFirewall": "ufw",
  "sshConfigMode": "dropin-or-main-config"
}

Rocky/AlmaLinux 只需要对应修改 imageCode、displayName、osDistribution,并把 linuxFirewall 改成 firewalld。

10

生成 SHA-256、设置只读、扫描验收

在 Hyper-V 宿主机管理员 PowerShell 执行
$vhdx = "D:\Templates\ubuntu-24.04-x86_64.vhdx"
$hash = (Get-FileHash -Algorithm SHA256 -LiteralPath $vhdx).Hash
Set-Content -LiteralPath ($vhdx + ".sha256") -Value $hash -Encoding Ascii
Set-ItemProperty -LiteralPath $vhdx -Name IsReadOnly -Value $true

Get-Item -LiteralPath $vhdx | Select-Object FullName,Length,IsReadOnly
Get-Content -LiteralPath ($vhdx + ".sha256")
  1. Manager →“存储与模板”→确认模板目录。
  2. 点击“扫描模板目录”,必须显示“可用”。
  3. 业务系统执行“同步节点模板”。
  4. 创建测试 VM,观察任务应从 90% 进入 100%,不能超时。
  5. 验证 root 密码、随机 SSH 端口、IP、网关、DNS、防火墙、系统盘扩容、数据盘和 HTML5 控制台。
  6. 在测试 VM 执行 cloud-init status --long,状态必须是 done。
  7. 检查 /var/lib/fastmos/provisioning.json,必须包含 ready。

把模板放入 WhaleEngine:最后 5 步

  1. 确认目录:打开 Manager →“存储与模板”,查看“模板目录”,不要凭感觉写死为 D 盘。
  2. 复制 3 个文件:VHDX、.sha256、.template.json 放在同一目录。
  3. 扫描:点击“扫描模板目录”,Manager 会核对并把目录中的 VHDX 设置为只读。
  4. 同步:回到业务系统执行“同步节点模板”。Agent 扫描成功不代表业务系统已同步。
  5. 真实开通:用独立测试 IP 开一台最小规格 VM,验证成功后才允许正式售卖。
文件名规则:
D:\Templates\ubuntu-24.04-x86_64.vhdx
D:\Templates\ubuntu-24.04-x86_64.vhdx.sha256
D:\Templates\ubuntu-24.04-x86_64.vhdx.template.json

常见错误:看到提示后怎么处理

Golden template must be read-only

VHDX 没有只读属性。Manager 中点击“扫描模板目录”,或执行 Set-ItemProperty -LiteralPath "模板.vhdx" -Name IsReadOnly -Value $true。

Template SHA-256 sidecar file was not found

缺少 模板.vhdx.sha256。重新执行本页生成 SHA-256 的命令。不要把文件命名成只有 模板.sha256。

Template manifest was not found / invalid JSON

Manifest 缺失、文件名不对应或 JSON 多了逗号。最简单的命名是 模板.vhdx.template.json;用本页完整示例修改,不要删除必填字段。

Windows VM 一直停在 OOBE 或开通失败

通常是没有正确执行 Sysprep,或 Sysprep 后又启动过模板 VM。重新在模板 VM 执行 /generalize /oobe /shutdown /mode:vm,关机后重新复制 VHDX。

Linux 开通停在 90%,提示 not_ready:cloud_init

模板缺少 cloud-init、数据源被锁定成非 NoCloud,或封装前没有 clean。回到 Linux 第 4、5、7 步逐项核对。

Linux 提示 not_ready:fastmos_marker

cloud-init 已启动,但 Agent 注入的首次启动脚本没有执行完。先看 cloud-init status --long、/var/log/cloud-init-output.log 和 SSH/防火墙状态,不要反复点击重开。

下载模板后扫描不到

先确认 Manager 配置的模板目录和下载保存目录完全一致;Agent 只扫描配置目录顶层的 *.vhdx,不会递归扫描子文件夹。扫描成功后还要在业务系统同步节点模板。

修改过 VHDX 后又提示 SHA-256 错误

任何 VHDX 内容变化都会让旧哈希失效。先取消只读、完成修改并重新封装,然后重新计算 SHA-256,最后再设为只读。

正式上线前逐项打勾

检查项WindowsLinux
VHDX 位于 Manager 配置的模板目录顶层必须必须
VHDX 已设为只读必须必须
同名 .sha256 存在且与当前文件一致必须必须
同名 .template.json 字段正确必须必须
虚拟机代数与 Manifest 一致第二代推荐第二代
通用化/首次启动组件Sysprep generalizecloud-init NoCloud
默认管理入口Administrator / RDP 3389root / SSH 22
Manager 扫描结果可用可用
测试开通结果100% 且 RDP 可登录100% 且 SSH 可登录
网络、密码、随机端口、扩盘、控制台全部验证全部验证
全部通过才算模板制作完成。不要只看“扫描成功”;最终标准是从业务系统创建一台全新的 VM,并完整验证登录和网络。