images-2

Debian 13 Minimal SolusVM v1 KVM 模板制作完整教程

本文介绍如何制作一个适用于 SolusVM v1.29.x 的 Debian 13 amd64 Minimal KVM 模板，包含系统安装、磁盘分区、网络配置、SSH 登录、模板清理、QCOW2 压缩、SolusVM 参数设置、上传和故障排查。

推荐最终结构：Debian 13 Minimal、Generation 2、Virtio 磁盘、MBR 分区表、Legacy BIOS、ext4 根分区、独立 Swap 分区。

一、最终模板参数

项目 推荐值
系统 Debian 13 amd64 Minimal
虚拟化 KVM
Generation 2
磁盘驱动 virtio
启动模式 Legacy BIOS / SeaBIOS
分区表 MBR / msdos
根分区 /dev/vda1
Swap 分区 /dev/vda2
Partition # to Resize 1
Swap Partition # 2
模板文件名 linux-debian-13-x86_64-minimal-gen2-v1.gz

二、为什么推荐 MBR 和 Legacy BIOS

SolusVM v1 的 Generation 2 模板最适合标准 Linux 分区。为了避免安装后出现“Boot failed: not a bootable disk”，建议第一次制作 Debian 13 模板时使用 MBR 和 Legacy BIOS。

不建议首次制作时使用以下结构：

  • UEFI-only
  • GPT + EFI-only
  • LVM
  • RAID
  • 加密磁盘
  • Extended Partition
  • Logical Partition
  • Btrfs 或 ZFS

推荐的磁盘结构如下：

磁盘：/dev/vda

/dev/vda1    ext4    /
/dev/vda2    swap

如果使用 GPT 并包含 EFI 分区，根分区可能变成第 2 个分区，Swap 变成第 3 个分区，SolusVM 参数也必须改为 2 和 3。为了降低兼容问题，推荐使用 MBR。

三、创建制作模板的临时虚拟机

建议创建一台专门用于制作模板的临时 KVM 虚拟机。

项目 推荐值
CPU 1 vCPU
内存 1 GB 或以上
磁盘 建议 8 GB 或 10 GB
磁盘驱动 virtio
网卡 virtio
启动模式 Legacy BIOS
系统 ISO Debian 13 amd64 netinst

6 GB 可以安装 Debian 13 Minimal，但如果后续执行系统升级、安装内核或安装大量软件，剩余空间可能不足。推荐使用 8 GB 或以上磁盘。

重要：模板的虚拟容量不能大于新虚拟机的磁盘容量。如果模板虚拟容量为 8 GB，新虚拟机只能分配 6 GB，则安装可能失败或无法启动。

四、安装 Debian 13 Minimal

  1. 使用 Debian 13 amd64 安装 ISO 启动。
  2. 确认使用 Legacy BIOS 模式启动安装程序。
  3. 选择手动分区。
  4. 不要选择 LVM、RAID 或加密磁盘。
  5. 创建 MBR/msdos 分区表。
  6. 创建 ext4 根分区和 Swap 分区。
  7. 将 GRUB 安装到整个磁盘。

推荐分区：

分区 用途 文件系统
/dev/vda1 / ext4
/dev/vda2 Swap swap

如果使用 8 GB 磁盘，可以分配：

/dev/vda1    约 7 GB    ext4    /
/dev/vda2    512 MB     swap

安装 GRUB 时选择：

/dev/vda

不要选择：

/dev/vda1

五、安装完成后的基础检查

登录临时虚拟机后执行：

cat /etc/os-release
cat /etc/debian_version
uname -a
lsblk -f
findmnt /
swapon --show
df -h

应确认：

  • 系统为 Debian 13。
  • 根分区是 ext4。
  • Swap 已启用。
  • 磁盘设备为 vda 或经过确认的实际设备名。
  • 根分区没有使用 LVM。

六、安装模板所需软件

apt-get update

apt-get install -y \
  openssh-server \
  sudo \
  ca-certificates \
  curl \
  wget \
  vim-tiny \
  less \
  iproute2 \
  iputils-ping \
  dnsutils \
  net-tools \
  ifupdown \
  isc-dhcp-client \
  bash-completion \
  rsync \
  qemu-guest-agent

启用 SSH：

systemctl enable ssh
systemctl restart ssh
systemctl status ssh --no-pager

如果宿主机支持 QEMU Guest Agent，可以启用：

systemctl enable --now qemu-guest-agent

七、配置 Debian 13 软件源

首先确认系统代号：

. /etc/os-release
echo "$VERSION_CODENAME"

Debian 13 通常使用 trixie 代号。可以创建 Debian 13 的软件源配置：

cat >/etc/apt/sources.list.d/debian.sources <<'EOF'
Types: deb
URIs: http://deb.debian.org/debian
Suites: trixie trixie-updates
Components: main contrib non-free non-free-firmware

Types: deb
URIs: http://security.debian.org/debian-security
Suites: trixie-security
Components: main contrib non-free non-free-firmware
EOF

删除旧的软件源文件：

rm -f /etc/apt/sources.list

重新生成软件索引：

rm -rf /var/lib/apt/lists/*
mkdir -p /var/lib/apt/lists/partial
apt-get update

必须确保执行结果没有以下错误：

  • 404 Not Found
  • GPG error
  • Splitting up failed
  • Temporary failure resolving
  • Failed to fetch

如果出现 “Splitting up ... failed”，通常是磁盘空间不足，而不是软件源地址错误。检查：

df -h
df -i

清理 APT 缓存：

apt-get clean
rm -rf /var/lib/apt/lists/*
mkdir -p /var/lib/apt/lists/partial
apt-get update

八、配置 root 远程 SSH 登录

如果希望新虚拟机可以使用 Xshell 通过 root 密码登录，需要安装 SSH，并允许 root 密码认证。

设置临时 root 密码：

passwd root

创建 SSH 配置：

cat >/etc/ssh/sshd_config.d/99-solusvm-template.conf <<'EOF'
PermitRootLogin yes
PasswordAuthentication yes
KbdInteractiveAuthentication no
UsePAM yes
EOF

检查 SSH 配置是否正确：

sshd -t

重新启动 SSH：

systemctl restart ssh
systemctl enable ssh

确认最终配置：

sshd -T | grep -E 'permitrootlogin|passwordauthentication'

应看到：

permitrootlogin yes
passwordauthentication yes

模板制作前删除旧的 SSH 主机密钥：

rm -f /etc/ssh/ssh_host_*

新虚拟机第一次启动后，系统会重新生成 SSH 主机密钥。这样每台虚拟机都拥有独立的 SSH 指纹。

九、网络配置要求

模板中不要保留制作虚拟机的静态 IP、MAC 地址、网关和 DNS。新虚拟机的网络参数应该由 SolusVM 重新分配。

检查当前网络：

ip link
ip addr
ip route
cat /etc/resolv.conf

删除可能残留的旧网卡规则：

rm -f /etc/udev/rules.d/70-persistent-net.rules

不要同时启用多个网络管理器。以下组件不要重复管理同一块网卡：

  • NetworkManager
  • ifupdown
  • systemd-networkd
  • cloud-init 网络模块

在 SolusVM 模板设置中应启用：

Configure Networking: 勾选

新虚拟机启动后检查：

ip addr
ip route
ping -c 4 网关地址
ping -c 4 软件源域名

十、Hostname 和机器身份清理

模板不能保留制作虚拟机的唯一机器身份。

设置临时主机名：

hostnamectl set-hostname debian13-template

检查：

cat /etc/hostname
cat /etc/hosts
hostnamectl

清理 machine-id：

truncate -s 0 /etc/machine-id
rm -f /var/lib/dbus/machine-id

如果系统需要符号链接：

ln -s /etc/machine-id /var/lib/dbus/machine-id 2>/dev/null || true

十一、清理敏感信息、日志和临时文件

模板中不能保留密码、密钥、测试历史或生产环境信息。

rm -f /root/.bash_history
find /home -maxdepth 2 -name .bash_history -type f -delete
rm -f /root/.ssh/authorized_keys
rm -f /etc/ssh/ssh_host_*
rm -f /etc/machine-id
rm -f /var/lib/dbus/machine-id

清理日志：

journalctl --rotate || true
journalctl --vacuum-time=1s || true
find /var/log -type f -exec truncate -s 0 {} \;

清理临时文件：

find /tmp -mindepth 1 -maxdepth 1 -exec rm -rf {} +
find /var/tmp -mindepth 1 -maxdepth 1 -exec rm -rf {} +

清理 APT 缓存：

apt-get clean
rm -rf /var/lib/apt/lists/*
mkdir -p /var/lib/apt/lists/partial

不要删除以下目录：

  • /var/lib/dpkg
  • /etc/passwd
  • /etc/shadow
  • /boot
  • /etc
  • 整个 /var/lib

十二、检查 fstab

查看当前 fstab：

cat /etc/fstab

对于 Virtio 磁盘，推荐确认根分区和 Swap 对应关系：

/dev/vda1  /     ext4  defaults,noatime  0 1
/dev/vda2  none  swap  sw                 0 0

如果系统实际使用 sda，则应改成：

/dev/sda1  /     ext4  defaults,noatime  0 1
/dev/sda2  none  swap  sw                 0 0

确认设备名：

lsblk

测试 fstab：

mount -a
swapon -a
swapon --show

如果 mount 或 swapon 报错，不能继续制作模板。

十三、检查和安装 GRUB

针对 MBR/Legacy BIOS 模板，执行：

apt-get install -y grub-pc grub-pc-bin

确认磁盘设备：

lsblk

如果磁盘是 /dev/vda：

grub-install --target=i386-pc /dev/vda
update-grub

如果磁盘是 /dev/sda：

grub-install --target=i386-pc /dev/sda
update-grub

必须安装到整个磁盘，不要安装到分区：

正确：/dev/vda
错误：/dev/vda1

十四、制作前最终检查

cat /etc/os-release
uname -r
lsblk -f
findmnt /
swapon --show
ip addr
ip route
df -h
free -h
systemctl is-enabled ssh
sshd -t
apt-get update

确认以下项目全部正常：

  • Debian 13 版本正确。
  • 根分区为 ext4。
  • Swap 已启用。
  • SSH 服务正常。
  • 网络有默认路由。
  • APT 更新无错误。
  • 没有源虚拟机静态 IP。
  • 没有敏感信息。
  • 磁盘没有 100% 满。
  • GRUB 安装到了整个磁盘。

检查完成后关闭虚拟机：

sync
poweroff

不要在虚拟机运行状态下直接读取磁盘制作模板。

十五、使用 SolusVM 官方脚本制作

在宿主机上确认虚拟机已经关机，然后执行预扫描：

/scripts/kvmtemplate \
  --mode=prescan \
  --vmid=kvm9568 \
  --generation=2

如果输出类似：

/dev/vda1 filesystem ext4
/dev/vda2 filesystem swap

则 SolusVM 参数为：

Partition # to Resize: 1
Swap Partition #: 2

执行模板准备：

/scripts/kvmtemplate \
  --mode=prepare \
  --vmid=kvm9568 \
  --generation=2

准备过程可能会清理 SSH 主机密钥、旧 MAC 地址和部分网络规则。执行完成后，仍应人工检查 fstab、Hostname、网络和日志。

制作模板：

mkdir -p /home/solusvm/template-tmp

/scripts/kvmtemplate \
  --mode=package \
  --vmid=kvm9568 \
  --generation=2 \
  --tmpdir=/home/solusvm/template-tmp

脚本通常会输出一个临时模板文件，例如：

/home/solusvm/kvm/template/template-xxxxxxxx.gz

将它改名：

mv \
  /home/solusvm/kvm/template/template-xxxxxxxx.gz \
  /home/solusvm/kvm/template/linux-debian-13-x86_64-minimal-gen2-v1.gz

十六、手动 virt-sparsify 制作方式

如果要求不创建备份、不创建快照，并且直接从现有虚拟机磁盘生成模板，可以使用手动方式。

假设源磁盘为：

/dev/media/kvm9568_img

先确认虚拟机已经关机：

pgrep -af '[k]vm9568'

没有 QEMU 进程输出后再继续。

检查源磁盘：

file -sL /dev/media/kvm9568_img
fdisk -l /dev/media/kvm9568_img
qemu-img info /dev/media/kvm9568_img

制作压缩 QCOW2 模板：

mkdir -p /home/solusvm/kvm/template
mkdir -p /home/solusvm/template-tmp

TMPDIR=/home/solusvm/template-tmp \
virt-sparsify \
  -v \
  --format raw \
  --convert qcow2 \
  --compress \
  -o compat=0.10 \
  /dev/media/kvm9568_img \
  /home/solusvm/kvm/template/.linux-debian-13-x86_64-minimal-gen2-v1.gz.tmp

检查模板：

qemu-img check --force-share \
  /home/solusvm/kvm/template/.linux-debian-13-x86_64-minimal-gen2-v1.gz.tmp

设置权限：

chown qemu:qemu \
  /home/solusvm/kvm/template/.linux-debian-13-x86_64-minimal-gen2-v1.gz.tmp

chmod 0644 \
  /home/solusvm/kvm/template/.linux-debian-13-x86_64-minimal-gen2-v1.gz.tmp

正式替换：

mv -f \
  /home/solusvm/kvm/template/.linux-debian-13-x86_64-minimal-gen2-v1.gz.tmp \
  /home/solusvm/kvm/template/linux-debian-13-x86_64-minimal-gen2-v1.gz

十七、模板格式验证

file /home/solusvm/kvm/template/linux-debian-13-x86_64-minimal-gen2-v1.gz

qemu-img info \
  /home/solusvm/kvm/template/linux-debian-13-x86_64-minimal-gen2-v1.gz

qemu-img check --force-share \
  /home/solusvm/kvm/template/linux-debian-13-x86_64-minimal-gen2-v1.gz

正确结果应类似：

QEMU QCOW Image
file format: qcow2
virtual size: 6.0G
disk size: 小于虚拟容量
No errors were found on the image.

注意：不要用以下命令判断 SolusVM 模板是否正确：

gzip -t linux-debian-13-x86_64-minimal-gen2-v1.gz

SolusVM v1 的模板文件虽然使用 .gz 后缀，但实际内容通常是启用了压缩簇的 QCOW2 镜像。

十八、SolusVM 面板参数

字段 推荐值
Template Name Debian 13 64bit Minimal
Description Debian 13 amd64 Minimal KVM Template
Generation 2
Template linux-debian-13-x86_64-minimal-gen2-v1.gz
Status Active
Arch x86_64
Disk Driver virtio
Change Root/Admin Password 勾选
Configure Networking 勾选
No sparse copying 不勾选
Partition # to Resize 1
Swap Partition # 2
CPU Model default
CPU Match default
CPU Topology 不启用

十九、模板文件上传验证

上传前先计算源文件 SHA-256：

sha256sum \
  /home/solusvm/kvm/template/linux-debian-13-x86_64-minimal-gen2-v1.gz

上传到目标服务器时，建议先使用临时文件名：

linux-debian-13-x86_64-minimal-gen2-v1.gz.part

上传完成后，在目标服务器执行：

stat -c '%s' linux-debian-13-x86_64-minimal-gen2-v1.gz.part
sha256sum linux-debian-13-x86_64-minimal-gen2-v1.gz.part
qemu-img check --force-share linux-debian-13-x86_64-minimal-gen2-v1.gz.part

确认文件大小、SHA-256 和镜像检查全部正确后，再改名：

mv -f \
  linux-debian-13-x86_64-minimal-gen2-v1.gz.part \
  linux-debian-13-x86_64-minimal-gen2-v1.gz

二十、第一次安装测试

模板制作完成后，不要立即批量使用。建议先创建一台测试虚拟机。

测试项目 要求
Generation 2
Disk Driver virtio
磁盘容量 不小于模板虚拟容量
Resize Partition 1
Swap Partition 2
Change Password 勾选
Configure Networking 勾选

测试虚拟机启动后执行：

cat /etc/os-release
hostnamectl
lsblk -f
df -h
swapon --show
ip addr
ip route
systemctl status ssh --no-pager
apt-get update

然后测试：

  • VNC 控制台。
  • root SSH 密码登录。
  • IPv4 地址。
  • IPv6 地址。
  • DNS 解析。
  • 默认路由。
  • APT 更新。
  • 关机和重启。
  • 重启后网络是否自动恢复。
  • 磁盘和 Swap 是否正常。

二十一、常见故障

1. Boot failed: not a bootable disk

  • 新虚拟机磁盘小于模板虚拟容量。
  • 模板使用了 UEFI，但虚拟机使用 SeaBIOS。
  • 模板使用 GPT/EFI-only，但没有正确配置 EFI。
  • GRUB 安装到了分区而不是整个磁盘。
  • Partition # to Resize 填错。
  • 模板文件传输不完整。
  • 模板不是有效 QCOW2。

检查：

qemu-img info linux-debian-13-x86_64-minimal-gen2-v1.gz
qemu-img check --force-share linux-debian-13-x86_64-minimal-gen2-v1.gz

2. VNC 连接失败

Debian Minimal 默认没有桌面环境，VNC 正常时应该显示文本控制台，不是图形桌面。

如果显示 1008、WebSocket 失败或 Failed to connect，检查：

pgrep -af kvm9568
virsh list --all
virsh dumpxml kvm9568 | grep -E 'graphics|video|disk|boot'

VNC 连接失败通常属于 QEMU、SolusVM 节点、WebSocket 代理或虚拟机启动问题，不代表 Debian 必须安装桌面环境。

3. 虚拟机没有网络

ip link
ip addr
ip route
cat /etc/resolv.conf
systemctl status networking --no-pager
systemctl status NetworkManager --no-pager

重点检查：

  • 是否保留了旧 MAC 地址规则。
  • 是否写死了源虚拟机 IP。
  • SolusVM 是否勾选 Configure Networking。
  • 虚拟机网卡名称是否发生变化。
  • 是否同时运行多个网络管理器。
  • 是否有默认路由。

4. APT 出现 404

检查系统是否误用了 Debian 11、Debian 12 或其他版本的软件源：

grep -R . /etc/apt/sources.list /etc/apt/sources.list.d/

Debian 13 应使用 trixie、trixie-updates 和 trixie-security，不要复制旧版本模板的软件源。

5. APT 出现 Splitting up failed

首先检查磁盘空间：

df -h
df -i

如果根分区已经 100% 满：

apt-get clean
rm -rf /var/lib/apt/lists/*
mkdir -p /var/lib/apt/lists/partial
apt-get update

如果磁盘只有 4 GB 或更小，建议扩容，而不是反复清理缓存。

二十二、最终发布前检查清单

  • 系统版本为 Debian 13。
  • 架构为 x86_64。
  • 使用 Generation 2。
  • 磁盘驱动为 virtio。
  • 磁盘使用 MBR/Legacy BIOS。
  • 根分区为第 1 分区。
  • Swap 为第 2 分区。
  • GRUB 安装在整个磁盘。
  • root 可以通过 SSH 密码登录。
  • SSH host key 已清理。
  • machine-id 已清理。
  • 旧网卡规则已清理。
  • 源虚拟机静态 IP 已清理。
  • APT 更新没有报错。
  • 没有遗留密码、密钥和日志。
  • 虚拟机已经关机。
  • 模板文件是 QCOW2 格式。
  • QCOW2 压缩已启用。
  • qemu-img check 无错误。
  • 上传后的 SHA-256 与源文件一致。
  • 新虚拟机磁盘容量不小于模板虚拟容量。
  • 已经完成至少一台测试虚拟机安装。

二十三、推荐的最终配置摘要

系统：
Debian 13 amd64 Minimal

启动：
Legacy BIOS / SeaBIOS

分区：
/dev/vda1  ext4  /
/dev/vda2  swap

SolusVM：
Generation = 2
Disk Driver = virtio
Partition # to Resize = 1
Swap Partition # = 2
Configure Networking = enabled
Change Root/Admin Password = enabled

模板制作：
virt-sparsify
--convert qcow2
--compress
-o compat=0.10

模板文件：
linux-debian-13-x86_64-minimal-gen2-v1.gz

只要按照“MBR + BIOS + ext4 根分区 + Swap 分区 + GRUB 安装到整个磁盘 + Generation 2 + virt-sparsify 压缩”这套组合制作，Debian 13 模板在 SolusVM v1 中的兼容性和稳定性最高。

```