跳转到主要内容

这是本节的多页打印视图。 .

返回本页常规视图.

文档

了解如何用 ansible-vms 定义和管理 KVM 虚拟机。

用 Ansible 与 libvirt 定义和管理 KVM 虚拟机的完整指南。

1 - 快速开始

安装依赖并创建第一台 KVM 虚拟机。

环境要求

  • 宿主机系统:Debian 12(Bookworm)
  • 软件包:qemu-kvm、libvirt-daemon-system、libvirt-clients、ovmf、swtpm

安装

# Clone the repository
git clone https://github.com/mars-base/ansible-vms.git
cd ansible-vms

# Install Python dependencies
uv sync  # or: pip install -r requirements.txt

# Setup configuration files
cp ansible.cfg.example ansible.cfg  # edit with your host name
cp hosts.ini.example hosts.ini      # edit with your host name
cp vms.csv.example vms.csv          # edit with your VM definitions

快速上手

# Install required packages on KVM host
uv run ansible-playbook playbooks/install-dependencies.yaml

# Create VMs defined in vms.csv
uv run ansible-playbook playbooks/create-vm.yaml

项目结构

ansible-vms/
├── ansible.cfg.example          # Ansible 配置模板
├── hosts.ini.example            # Inventory 模板
├── vms.csv                      # 虚拟机定义(CSV 驱动)
├── pyproject.toml               # Python 依赖(uv)
├── requirements.txt             # pip 依赖
├── group_vars/
│   ├── all/                     # 全局变量
│   └── kvm_hosts/               # KVM 宿主机变量
├── host_vars/                   # 单主机变量
├── playbooks/
│   ├── create-vm.yaml           # 从 vms.csv 创建虚拟机
│   ├── destroy-vm.yaml          # 销毁虚拟机
│   ├── list-vms.yaml            # 列出虚拟机
│   ├── snapshot-vm.yaml         # 管理虚拟机快照
│   ├── setup-user.yaml          # 在 Linux 虚拟机上创建用户
│   ├── start-vm.yaml            # 启动虚拟机
│   ├── stop-vm.yaml             # 停止虚拟机
│   └── restart-vm.yaml          # 重启虚拟机
├── roles/
│   └── create_vm/               # 创建角色(libvirt XML)
├── scripts/                     # 辅助脚本
├── tools/                       # 工具脚本(vm-console、vm-login)
└── var/                         # 运行时数据(日志、facts 缓存)

下一步

2 - 虚拟机定义(vms.csv)

通过 vms.csv 中的每一行配置虚拟机。

虚拟机在 vms.csv 文件中定义,每一行代表一台虚拟机,字段如下:

字段 说明 示例
name 虚拟机名称 win11-dev
host KVM 宿主机(inventory 名称) local
type 系统类型:windows / linux / macos windows
memory_mb 内存大小(MB) 8192
vcpus CPU 核数 4
os 系统变体 win11
disk_gb 系统盘大小 80
data_disk_gb 数据盘大小(0 表示无) 10
base_image 基础 qcow2 镜像路径 /path/to/base.qcow2
bridge 网络网桥 br0
mac MAC 地址 52:54:00:xx:xx:xx
firmware efi 或留空(BIOS) efi
autostart 开机自启(默认:false) true
storage_dir 虚拟机存储路径(可选,默认:/var/lib/libvirt/images) /data/vms
ip 静态 IP(可选,留空 = DHCP)。Linux:创建时经 cloud-init 生效;macOS:之后由 configure-macos-network.yaml 配置,见 macOS 虚拟机 192.168.1.100
netmask 子网 CIDR(可选,默认:22) 24
gateway 默认网关(设置 ip 时必填) 192.168.1.1
dns DNS 服务器,逗号分隔(设置 ip 时必填) 8.8.8.8,8.8.4.4

vms.csv 示例

name,host,type,memory_mb,vcpus,os,disk_gb,data_disk_gb,base_image,bridge,mac,firmware,autostart,storage_dir,ip,netmask,gateway,dns
win11-dev,local,windows,8192,4,win11,80,10,/home/user/images/win11-base.qcow2,br0,52:54:00:12:34:56,efi,true,/var/lib/libvirt/images,,,,
debian12-dev,local,linux,2048,2,debian12,20,0,/home/user/images/debian-12.qcow2,br0,52:54:00:12:34:57,,true,/var/lib/libvirt/images,192.168.1.100,24,192.168.1.1,"8.8.8.8,8.8.4.4"

要点

  • MAC 地址:每台虚拟机需要唯一的 MAC 地址,以获得稳定的 DHCP 租约
  • Autostart:只有 debian12-01 配置了 autostart=true(随宿主机启动)
  • 存储:虚拟机可使用自定义存储路径,默认 /var/lib/libvirt/images
  • 静态 IP:Linux 虚拟机通过 cloud-init;macOS 虚拟机通过 SSH 执行 configure-macos-network.yaml(macOS 没有 cloud-init)——见 macOS 虚拟机
  • 幂等:create-vm playbook 创建前会检查虚拟机是否已存在,可安全重复执行

3 - 虚拟机生命周期

列出、启动、停止、重启和销毁虚拟机。

所有 playbook 都是幂等的(可安全重复执行)。

列出虚拟机

# List all VMs with status and IP
uv run ansible-playbook playbooks/list-vms.yaml

输出示例:

win11-dev            192.168.1.101   windows  4 vCPU 8192 MB    win11  shut off
win10-dev            192.168.1.102   windows  4 vCPU 8192 MB    win10  running
debian12-dev         192.168.1.103   linux    2 vCPU 2048 MB    debian12 running

启动虚拟机

# Start specific VM
uv run ansible-playbook playbooks/start-vm.yaml -e vm_name=debian12-dev

停止虚拟机

# Graceful shutdown
uv run ansible-playbook playbooks/stop-vm.yaml -e vm_name=win11-dev

使用 virsh shutdown,发送 ACPI 关机信号。对于配置了 QEMU guest agent 的 Windows 虚拟机,这会触发干净关机。

重启虚拟机

# Stop then start VM
uv run ansible-playbook playbooks/restart-vm.yaml -e vm_name=debian12-dev

销毁虚拟机

# Permanently delete VM (requires confirmation)
uv run ansible-playbook playbooks/destroy-vm.yaml -e vm_name=win11-dev -e confirm=true

删除内容:domain 定义、磁盘镜像(qcow2)、OVMF VARS、cloud-init ISO、TPM 状态。

警告:该操作具有破坏性且不可恢复,必须传入 confirm=true。

4 - 基础镜像

为虚拟机下载 Linux、Windows 与 macOS 基础镜像。

Linux 基础镜像

Linux 虚拟机使用官方 cloud 镜像,这些镜像已预置 cloud-init 支持。

Debian

下载最新的 Debian 12(Bookworm)镜像:

wget -O debian-12-genericcloud-amd64.qcow2 \
  https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2

其他版本:在 https://cloud.debian.org/images/cloud/ 浏览 bookworm、bullseye、trixie 等版本。

Ubuntu

下载最新的 Ubuntu 24.04 LTS(Noble)镜像:

wget -O ubuntu-24.04-server-cloudimg-amd64.img \
  https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img

下载最新的 Ubuntu 26.04 LTS(Resolute)镜像:

wget -O ubuntu-26.04-server-cloudimg-amd64.img \
  https://cloud-images.ubuntu.com/resolute/current/resolute-server-cloudimg-amd64.img

重要:Ubuntu cloud 镜像需要 virtio 网络驱动。本项目的虚拟机模板已使用 virtio,无需额外配置。

注意:请务必对照官方 SHA256SUMS 文件校验下载的镜像,避免镜像损坏导致启动失败。

其他版本:在 https://cloud-images.ubuntu.com/ 浏览其他 Ubuntu 发行版。

Fedora

下载最新的 Fedora 44 Cloud Base 镜像:

wget -O Fedora-Cloud-Base-Generic-44-1.7.x86_64.qcow2 \
  https://download.fedoraproject.org/pub/fedora/linux/releases/44/Cloud/x86_64/images/Fedora-Cloud-Base-Generic-44-1.7.x86_64.qcow2

注意:Fedora 使用 wheel 组授予 sudo 权限(而非 sudo 组)。setup-user playbook 会自动检测并使用正确的组。

其他版本:在 https://fedoraproject.org/cloud/download/ 浏览其他 Fedora 发行版。

Rocky Linux

下载最新的 Rocky Linux 10 Cloud Base 镜像:

wget -O Rocky-10-GenericCloud-Base.latest.x86_64.qcow2 \
  https://dl.rockylinux.org/pub/rocky/10/images/x86_64/Rocky-10-GenericCloud-Base.latest.x86_64.qcow2

注意:Rocky Linux 使用 wheel 组授予 sudo 权限(与 RHEL/CentOS 相同)。setup-user playbook 会自动检测并使用正确的组。

其他版本:在 https://rockylinux.org/download 浏览其他 Rocky Linux 发行版。

配置

在 vms.csv 的 base_image 字段中设置镜像路径:

# Debian
my-debian-vm,local,linux,...,/path/to/debian-12-genericcloud-amd64.qcow2,...

# Ubuntu
my-ubuntu-vm,local,linux,...,/path/to/ubuntu-24.04-server-cloudimg-amd64.img,...

# Fedora
my-fedora-vm,local,linux,...,/path/to/Fedora-Cloud-Base-Generic-44-1.7.x86_64.qcow2,...

# Rocky Linux
my-rocky-vm,local,linux,...,/path/to/Rocky-10-GenericCloud-Base.latest.x86_64.qcow2,...

镜像会在首次启动时通过 cloud-init 自动配置(SSH 密钥、用户、软件包等,来自 group_vars/kvm_hosts/vms_all.yaml)。

Windows 基础镜像

Windows qcow2 基础镜像由 packer-windows-kubevirt 构建。它使用 Packer + QEMU 生成 sysprep 泛化的 Windows 镜像,包含:

  • 预装 virtio 驱动(vioscsi、viostor、netkvm、vioserial、viorng、balloon、viofs)
  • QEMU Guest Agent + Cloudbase-Init
  • 启用 WinRM HTTPS(端口 5986)和 RDP(端口 3389)
  • EFI 启动,带 secure boot 密钥

构建你自己的镜像:

git clone https://github.com/mars-base/packer-windows-kubevirt
cd packer-windows-kubevirt
packer build <template>

然后在 vms.csv 的 base_image 字段中设置输出路径。

Windows 虚拟机特性

当 type=windows 时,domain XML 模板包含:

  • Hyper-V 优化项(relaxed、vapic、spinlocks、synic、stimer 等),支持嵌套 WSL2
  • VMX 透传,支持虚拟机内嵌套虚拟化(WSL2/Hyper-V)
  • EFI + vTPM 2.0(OVMF secure boot + 模拟 TPM)
  • virtio-scsi 磁盘总线 + virtio 网卡
  • Localtime 时钟,带 hypervclock

macOS 基础镜像

macOS 虚拟机使用在 KVM 宿主机上通过 OSX-KVM 手工制作的自包含 qcow2 基础镜像。与 Linux、Windows 镜像不同,它既不是下载的,也不是用 Packer 构建的:

  • macOS Sonoma 14.8.9(x86_64),4 vCPU / 8 GB,账户 admin / admin,Remote Login 已开启
  • OpenCore 引导盘 + 已 bless 的 OVMF NVRAM 模板,冷启动无需键盘操作
  • 虚拟容量 64 GiB,实际占用约 29 GiB,无 backing file——可直接作为 backing 镜像使用

每台 macOS 虚拟机都会以其为基础派生独立的系统盘 overlay、OpenCore overlay,以及一份 per-VM 的 blessed OVMF VARS 文件。在 vms.csv 的 base_image 字段中设置镜像路径。

完整制作流程(安装介质下载、bless、NVRAM 校验、镜像转换)见 macOS 基础镜像。

5 - 网络

虚拟机的网桥网络、DHCP 与静态 IP 配置。

虚拟机通过网桥(默认 br0)接入本地网络,支持两种 IP 分配方式:

DHCP 模式(默认)

当 ip 字段留空时,虚拟机从局域网的 DHCP 服务器获取 IP 地址——与宿主机处于同一子网。

LAN (192.168.1.0/24, DHCP, gateway 192.168.1.1)
├── KVM Host (192.168.1.100, br0)
└── VM (192.168.1.x, DHCP via br0, virtio NIC)

每台虚拟机在 vms.csv 中都分配了固定的 MAC 地址,因此 DHCP 租约是稳定的。查询虚拟机 IP:

ip neigh show dev br0 | grep -i <MAC>

也可以使用 list-vms playbook,它会自动完成这一步。

静态 IP 模式(Linux 虚拟机)

对于 Linux 虚拟机,可在 vms.csv 中填写 ip、netmask、gateway、dns 字段来配置静态 IP。

LAN (192.168.1.0/24, DHCP, gateway 192.168.1.1)
├── KVM Host (192.168.1.100, br0)
└── VM (192.168.1.150, static IP, virtio NIC)

vms.csv 配置示例

name,host,type,memory_mb,vcpus,os,disk_gb,data_disk_gb,base_image,bridge,mac,firmware,autostart,storage_dir,ip,netmask,gateway,dns
web-server,local,linux,4096,2,debian12,40,100,/path/to/debian-12.qcow2,br0,52:54:00:aa:bb:cc,,true,/var/lib/libvirt/images,192.168.1.150,24,192.168.1.1,"8.8.8.8,1.1.1.1"

说明

  • 静态 IP 配置仅适用于 Linux 虚拟机(cloud-init network-config)
  • Windows 虚拟机不支持通过该方式配置静态 IP
  • 当 ip 留空或省略时,虚拟机使用 DHCP(默认行为)
  • IP 地址是持久的,重启后保持不变
  • 确保静态 IP 位于 DHCP 池之外,避免地址冲突

生成的网络配置

cloud-init 会在 /etc/netplan/50-cloud-init.yaml 生成 netplan 配置:

network:
  version: 2
  ethernets:
    ens3:
      addresses:
      - 192.168.1.150/24
      routes:
      - to: default
        via: 192.168.1.1
      nameservers:
        addresses:
        - 8.8.8.8
        - 1.1.1.1

验证

虚拟机创建完成后,验证静态 IP 是否生效:

# Check IP address
ssh root@192.168.1.150 "ip addr show ens3 | grep inet"

# Check gateway
ssh root@192.168.1.150 "ip route | grep default"

# Check DNS
ssh root@192.168.1.150 "grep nameserver /etc/resolv.conf"

网桥配置

KVM 宿主机需要网络网桥(br0),虚拟机才能直接访问局域网。根据宿主机的网络管理方式选择方法:NetworkManager 处于活动状态(大多数桌面环境)用 nmcli,传统服务器配置用 ifupdown。用 systemctl is-active NetworkManager 检查。

方法 1:nmcli(NetworkManager)

先找到当前的连接配置、其 IP 配置,以及要桥接的网卡:

nmcli -f NAME,DEVICE,TYPE,STATE connection show
nmcli -f ipv4.method,ipv4.addresses,ipv4.gateway,ipv4.dns connection show "<existing profile name>"

创建承载相同静态 IP 的网桥(或在 br0 上用 ipv4.method auto 走 DHCP),然后挂接网卡作为网桥端口,再禁用旧配置以免它抢回网卡:

# 1. Create bridge br0 with the host's IP config
sudo nmcli connection add type bridge ifname br0 con-name br0 \
    ipv4.method manual ipv4.addresses 192.168.1.100/24 \
    ipv4.gateway 192.168.1.1 ipv4.dns 192.168.1.1 \
    bridge.stp no

# 2. Attach the physical NIC as a bridge port
sudo nmcli connection add type bridge-slave ifname eth0 con-name br0-port-eth0 master br0

# 3. Stop the old profile from auto-activating
sudo nmcli connection modify "<existing profile name>" connection.autoconnect no

# 4. Switch over (brief link interruption; do this from the local console
#    or accept the drop if connected remotely)
sudo nmcli connection up br0
sudo nmcli connection down "<existing profile name>"

两个连接都会持久化,重启后依然有效。回滚方法:nmcli connection up "<existing profile name>" 并恢复 connection.autoconnect yes。

方法 2:ifupdown(/etc/network/interfaces)

/etc/network/interfaces 示例:

# Physical NIC — manual mode, no IP (managed by bridge)
auto eth0
iface eth0 inet manual
    pre-up ip link set $IFACE up
    post-down ip link set $IFACE down

# Bridge br0 — static IP, bridges eth0
auto br0
iface br0 inet static
    address 192.168.1.100
    netmask 255.255.255.0
    gateway 192.168.1.1
    dns-nameservers 8.8.8.8 8.8.4.4
    bridge_ports eth0
    bridge_stp off
    bridge_fd 0
    bridge_maxwait 0

将 eth0 替换为实际的网卡名(用 ip link 查看)。修改后:

sudo systemctl restart networking

验证网桥已启用:

ip addr show br0
bridge link show

6 - 数据盘

挂载、扩容、格式化数据盘,以及管理额外磁盘。

macOS 虚拟机:本文档中的 playbook 不适用于 macOS 客户机。 macOS 磁盘位于 q35 内置的 SATA 控制器上(不支持热插拔,也没有 virtio-blk 驱动),且 macOS 客户机内没有可供 Ansible 使用的 Python。 数据盘改为在创建虚拟机时根据 data_disk_gb 列自动创建 (见 macOS 虚拟机);各 playbook 会检测 type=macos 并以 diskutil 提示中止。

挂载数据盘

# Attach data disk to a running VM (hot-plug, no reboot needed)
uv run ansible-playbook playbooks/attach-data-disk.yaml -e vm_name=debian12-dev

从 vms.csv 读取 data_disk_gb,虚拟机必须在 CSV 中定义了 data_disk_gb > 0。通过 virsh attach-disk --config --live 将磁盘热插到运行中的虚拟机(持久化 + 立即生效)。

在虚拟机内部格式化并挂载新磁盘:

mkfs.ext4 /dev/vdb
mkdir -p /data
mount /dev/vdb /data

扩容数据盘

# Resize data disk (reads target size from vms.csv)
uv run ansible-playbook playbooks/resize-data-disk.yaml -e vm_name=debian12-dev

从 vms.csv 读取目标 data_disk_gb。playbook 会:

  1. 检查目标大小是否大于当前大小(不支持缩小)
  2. 若虚拟机正在运行 → 优雅关机并等待停止
  3. 使用 qemu-img resize 扩容 qcow2 文件
  4. 若虚拟机之前在运行 → 自动重新启动

扩容完成后,在虚拟机内扩展文件系统:

# Linux VM
resize2fs /dev/vdb

# Windows VM (PowerShell)
$maxSize = (Get-PartitionSupportedSize -DriveLetter E).SizeMax
Resize-Partition -DriveLetter E -Size $maxSize

注意:如果虚拟机已处于关机状态,playbook 直接扩容磁盘,不会自动开机。

挂载磁盘

# Format and mount data disk inside VM (requires VM in hosts.ini)
uv run ansible-playbook playbooks/mount-disk.yaml -e "HOSTS=debian13-01" -e "mount_point=/data"

在 Linux 虚拟机内部格式化并挂载数据盘。要求虚拟机已在 hosts.ini 中定义。

参数

  • disk_device:磁盘设备路径(默认:/dev/vdb)
  • mount_point:挂载点(必填,如 /data)
  • disk_format:文件系统类型(默认:ext4)
  • need_partition:创建 GPT 分区(默认:false,裸盘挂载)
  • format_force:强制重新格式化(默认:false)
  • auto_mount:写入 fstab(默认:true)

示例

# With GPT partition (default)
uv run ansible-playbook playbooks/mount-disk.yaml -e "HOSTS=debian13-01" -e "mount_point=/data"

# Raw disk without partition
uv run ansible-playbook playbooks/mount-disk.yaml -e "HOSTS=debian13-01" -e "mount_point=/data" -e "need_partition=false"

# Force reformat (WARNING: destroys data)
uv run ansible-playbook playbooks/mount-disk.yaml -e "HOSTS=debian13-01" -e "mount_point=/data" -e "format_force=true"

playbook 会:

  1. 按需安装 parted
  2. 创建 GPT 分区表(当 need_partition=true)
  3. 使用指定文件系统格式化磁盘
  4. 以 UUID 写入 fstab
  5. 挂载并验证

Tags: -t partition、-t format、-t mount(只执行特定步骤)

额外磁盘(添加 / 列出 / 删除)

可在运行时按需添加任意数量的额外 virtio-blk 磁盘,独立于 data_disk_gb 列(该列专供 create-vm.yaml 创建的单块数据盘)。 磁盘命名为 <vm>-extra<N>.qcow2,存放在虚拟机的存储目录中;下一个可用 索引和下一个可用宿主机目标(vdX)都会从运行态和持久化配置中自动 检测,重复执行不会冲突。

仅限 Linux 客户机:virtio-blk 热插拔对运行中的虚拟机有效 (--config --live,立即生效,无需重启);已关机的虚拟机只会通过 --config 添加磁盘,下次启动时可见。

添加

# one 10G disk (index/letter picked automatically)
uv run ansible-playbook playbooks/add-extra-disk-linux.yaml -e vm_name=debian12-01 -e extra_size=10G

# four 2G disks in one run
uv run ansible-playbook playbooks/add-extra-disk-linux.yaml -e vm_name=debian12-01 -e count=4 -e extra_size=2G

# override the target directory (default: VM's storage dir from vms.csv)
uv run ansible-playbook playbooks/add-extra-disk-linux.yaml -e vm_name=debian12-01 -e extra_dir=/data/disks

列出

uv run ansible-playbook playbooks/list-extra-disks.yaml -e vm_name=debian12-01

显示每块磁盘的索引、虚拟大小,以及在运行态 domain 和/或持久化配置中的目标设备:

extra1.qcow2: 2G, live=vdc, config=vdc
extra2.qcow2: 2G, live=vdd, config=vdd

删除

先卸载磁盘(运行中虚拟机的运行态 + 配置——virtio-blk 热拔除),再删除 qcow2 文件。该操作会销毁数据,必须传入 confirm=true:

uv run ansible-playbook playbooks/delete-extra-disk.yaml -e vm_name=debian12-01 -e extra_index=2 -e confirm=true

在客户机内识别磁盘

客户机内核会分配自己的 vdX 名称,通常与宿主机的目标设备不同。每块额外磁盘带有序列号 <vm>-extra<N>——按序列号匹配:

lsblk -o NAME,SERIAL,SIZE
# vdc  debian12-01-extra1  2G

之后用 mount-disk.yaml 格式化/挂载(传入客户机内的设备名,如 -e disk_device=/dev/vdc)。

7 - 快照

创建、列出、恢复和删除虚拟机快照。

使用 libvirt 内置的快照支持创建、列出、恢复和删除虚拟机快照。

用法

# Create snapshot (default: shutdown VM first for disk consistency, then restore previous state)
uv run ansible-playbook playbooks/snapshot-vm.yaml -e vm_name=debian12-01 -e snap_action=create

# Create snapshot without shutdown (live snapshot, VM continues running)
uv run ansible-playbook playbooks/snapshot-vm.yaml -e vm_name=debian12-01 -e snap_action=create -e halt=false

# Create snapshot with custom name and description
uv run ansible-playbook playbooks/snapshot-vm.yaml -e vm_name=debian12-01 -e snap_action=create -e snapshot_name=before-upgrade -e snapshot_desc="升级前快照"

# List all snapshots
uv run ansible-playbook playbooks/snapshot-vm.yaml -e vm_name=debian12-01 -e snap_action=list

# Restore to snapshot (requires confirmation, restores VM state at snapshot time)
uv run ansible-playbook playbooks/snapshot-vm.yaml -e vm_name=debian12-01 -e snap_action=restore -e snapshot_name=before-upgrade -e confirm=true

# Delete snapshot
uv run ansible-playbook playbooks/snapshot-vm.yaml -e vm_name=debian12-01 -e snap_action=delete -e snapshot_name=before-upgrade

参数

  • vm_name:虚拟机名称(必填)
  • snap_action:create / list / restore / delete(必填)
  • snapshot_name:快照名称(create 时自动生成;restore/delete 时必填)
  • snapshot_desc:描述(可选,仅 create)
  • halt:快照前先关机以保证磁盘一致性,完成后恢复之前的状态(可选,仅 create,默认:true)
  • confirm:安全标志(restore 和 delete 必填)

行为

  • halt=true(默认):若虚拟机在运行 → 关机 → 快照 → 启动(恢复运行状态)。若虚拟机已关机 → 快照 → 保持关机(保留关机状态)。
  • halt=false:虚拟机运行中创建快照(live snapshot)。速度更快,但磁盘写入可能不完整。
  • Restore 将虚拟机恢复到快照时刻的精确状态(运行或关机,取决于快照时的状态)。

8 - 用户账户

在 Linux 虚拟机上创建带 SSH 密钥和免密 sudo 的用户。

在 Linux 虚拟机上创建带 SSH 密钥和免密 sudo 的用户账户,自动跳过非 Linux 主机。

用法

# Create user on single VM
uv run ansible-playbook playbooks/setup-user.yaml -e "HOSTS=debian12-01" -e "username=admin"

# Create user on multiple VMs (host group)
uv run ansible-playbook playbooks/setup-user.yaml -e "HOSTS=vms" -e "username=admin"

# Specify SSH public key
uv run ansible-playbook playbooks/setup-user.yaml -e "HOSTS=debian12-01" -e "username=admin" -e "ssh_pubkey=/path/to/id_rsa.pub"

参数

  • HOSTS:目标主机或主机组(默认:vms)
  • username:要创建的用户名(默认:admin)
  • ssh_pubkey:SSH 公钥文件路径(默认:~/.ssh/id_rsa.pub)
  • user_shell:登录 shell(默认:/bin/bash)
  • user_groups:用户组,逗号分隔(自动检测:Fedora/RHEL 用 wheel,Debian/Ubuntu 用 sudo)
  • passwordless_sudo:启用免密 sudo(默认:true)

行为

  • 通过 gather_facts: true 自动检测操作系统
  • Linux 主机:创建用户、配置 SSH 密钥、启用免密 sudo
  • 非 Linux 主机(Windows 等):跳过,并显示检测到的操作系统
  • 幂等:可在同一主机上安全重复执行

9 - 虚拟机控制台

通过 SPICE 或 VNC 访问虚拟机显示控制台。

虚拟机根据系统类型使用不同的图形后端:

  • Windows 虚拟机:SPICE 图形(端口 5900+)
  • Linux 虚拟机:VNC 图形(端口 5900+)

连接虚拟机控制台

# Method 1: virt-viewer (recommended, auto-detects SPICE/VNC)
virt-viewer <vm-name>

# Method 2: Get display port manually
virsh vncdisplay <linux-vm-name>    # Returns :0, :1, etc.
virsh domdisplay <windows-vm-name>  # Returns spice://127.0.0.1:5900

通过 SSH 隧道远程访问

# On your local machine
ssh -L 5900:127.0.0.1:5900 user@kvm-host-ip
# Then connect to spice://127.0.0.1:5900 or vnc://127.0.0.1:5900 locally

示例

查看 Windows 虚拟机的启动过程:

virt-viewer win10-dev1  # Opens SPICE console to watch Windows boot

10 - 远程桌面

Windows 虚拟机的 RDP 访问。

Windows 虚拟机支持 3389 端口的 RDP(Remote Desktop Protocol)。

查找虚拟机 IP 地址

virsh domifaddr <vm-name>

通过 RDP 连接

Linux 桌面(推荐):Remmina

安装:sudo apt install remmina remmina-plugin-rdp

GUI:支持 RDP、VNC、SPICE、SSH 特性:剪贴板共享、文件夹重定向、多显示器

其他选择

  • xfreerdp:xfreerdp /v:<vm-ip> /u:Administrator
  • Windows:内置"远程桌面连接"(mstsc.exe)
  • macOS:App Store 中的 “Microsoft Remote Desktop”

示例

# Linux: open Remmina and connect to 10.241.20.45
remmina -c rdp://10.241.20.45

# Or use xfreerdp
xfreerdp /v:10.241.20.45 /u:Administrator /p:<password>

11 - 防火墙

在 Debian 与 RedHat 系主机上用 nftables 管理宿主机防火墙。

nftables role 管理 KVM 宿主机的防火墙,支持 Debian 系(Debian、Ubuntu)与 RedHat 系(Fedora、Rocky Linux)主机。

在 Ubuntu 上,部分镜像自带并启用了 ufw;默认会将其禁用(nftables_disable_ufw),避免两个管理器争抢规则集。在 Fedora 和 Rocky 上,firewalld 默认被停止并 mask(nftables_disable_firewalld),原因相同。

用法

# Copy the variable template and fill in live values
cp group_vars/nftables/main.yml.example group_vars/nftables/main.yml

# Add hosts to the [nftables] group in hosts.ini, then apply:
uv run ansible-playbook playbooks/nftables.yaml

# Or target hosts directly via HOSTS pattern
uv run ansible-playbook playbooks/nftables.yaml -e HOSTS=<pattern>

除非 nftables_ssh_allow_all 为 true,nftables_ssh_sources 必须至少包含一条记录,且应包含 Ansible 控制节点,否则 role 拒绝应用空列表。已建立的 SSH 会话在重载后不会中断(established/related 被放行),但来源不在列表中的新连接会被丢弃。

role 做了什么

  1. 在改动主机前校验输入(OS family、nftables_ssh_sources 的 IPv4/CIDR 格式、SSH 端口非空、set 名称)。
  2. 安装 nftables(Debian 系用 apt,RedHat 系用 dnf);Debian 系默认移除 netfilter-persistent / iptables-persistent。
  3. 禁用冲突的管理器:Ubuntu 上执行 ufw --force disable(当处于活动状态);Fedora/Rocky 上停止并 mask firewalld。
  4. 将规则集渲染到 /etc/nftables.conf(Debian 系)或 /etc/sysconfig/nftables.conf(RedHat 系),写入前先用 nft -c -f 校验;内容变化时通过 nft -f 重载。
  5. 设置 nftables 服务开机自启。

渲染出的配置定义了两张独立的表 inet _filter 和 inet _nat,重载时只删除并重建这两张表——无关的表(例如 Docker 的)不受影响。

变量

变量 说明 默认值
nftables_ssh_sources 允许建立 SSH 连接的来源 IPv4 地址/CIDR —(除非 allow-all,否则必填)
nftables_ssh_allow_all 接受任意来源的 SSH false
nftables_ssh_ports 宿主机 SSH 端口列表;列出 sshd 监听的每个端口 [22]
nftables_sets 命名地址集合(name + subnet 列表) []
nftables_rules 原样插入 filter_default、filter_forward、nat_prerouting、nat_postrouting 的规则 []
filter_forward_default_policy FORWARD 链默认策略 drop
net_postrouting_default_policy POSTROUTING 链默认策略 accept
nftables_remove_iptables_persistent 移除 netfilter-persistent / iptables-persistent true
nftables_disable_ufw 已安装且启用时禁用 ufw true
nftables_disable_firewalld RedHat 系已安装 firewalld 时停止并 mask true

示例

nftables_ssh_sources:
  - 10.0.0.0/8
  - 192.168.10.0/24
nftables_ssh_ports:
  - 22

nftables_sets:
  - name: cloud_inner
    subnet:
      - "10.5.0.0/16"

nftables_rules:
  - chain: filter_default
    rules:
      - ip saddr $cloud_inner counter jump nolimit
      - tcp dport 50001-50999 counter jump nolimit
  # dnat port 52001 to 192.168.1.2:8080
  - chain: nat_prerouting
    rules:
      - tcp dport 52001 counter dnat ip to 192.168.1.2:8080
  - chain: nat_postrouting
    rules:
      - ip daddr 192.168.1.2 tcp dport 8080 counter masquerade

内置链

  • deny — drop
  • nolimit — accept
  • switch — 总开关,把规则指向它即可切换:
sudo nft flush chain inet _filter switch
sudo nft add rule inet _filter switch counter jump deny

说明

  • 当 nftables_sets 和 nftables_rules 都为空时,只放行 loopback、established/related 流量、DHCP 应答、ICMP,以及来自 nftables_ssh_sources 的 SSH。
  • role 用自己的模板替换发行版自带的 /etc/nftables.conf。对于之前已在运行发行版配置的主机,残留的空 inet filter 表只有在可证明不会过滤流量时(无规则、无 drop/reject 策略)才会被删除。
  • 在 Fedora 和 Rocky 上,nftables.service 的 ExecReload 以 flush ruleset 开头,会清空无关的表。因此 role 直接执行 nft -f <config> 重载,而不使用 systemctl reload nftables。
  • mask firewalld 同时会阻止 D-Bus 激活,firewall-cmd 无法将其拉起。用 systemctl unmask firewalld 恢复。

12 - macOS 虚拟机

与 Linux、Windows 虚拟机并行的免键盘黑苹果 macOS 客户机。

macOS 客户机与 Linux/Windows 虚拟机并行运行。基础镜像如何用 kholia/OSX-KVM 从零构建,见 macOS 基础镜像(中文)。

macOS 与 Linux/Windows 的区别

方面 Linux/Windows macOS
显示 qxl/virtio/spice 通过 qemu:commandline 使用 vmware-svga
SMC — 通过 qemu:commandline 使用 isa-applesmc,osk=...
启动 直接引导系统盘 OpenCore overlay(顺序 1)→ macOS 磁盘(顺序 2)
固件 发行版 OVMF 或 SeaBIOS 持久化 OVMF + 预先 bless 的 NVRAM 模板
网络 libvirt <interface> 网桥,virtio 网卡固定在 root-bus slot=0x05
IP 配置 cloud-init 无 cloud-init — 默认 DHCP
关机 virsh shutdown(ACPI) macOS 忽略 ACPI — 从桌面或通过 SSH 关机

资产

共享的只读模板位于 macos_asset_dir(默认 /home/fish/bucket/kvm/macos/):

文件 用途
macos-sonoma-base.img Sonoma 14.8.9 基础镜像,admin/admin,已开启 Remote Login
OpenCore.qcow2 OpenCore 引导盘(SIP 已关闭、自动引导)
OVMF_VARS-blessed.fd 预 bless 的 NVRAM 模板——冷启动免键盘的关键

把资产复制到另一台宿主机

三个文件是自包含的——复制到新宿主机的 macos_asset_dir 即可在该主机上 创建 macOS 虚拟机。bless 后的 Preboot 卷 UUID、APFS 布局和 boot.efi 路径 都随文件一起迁移。

新宿主机还需要:

  1. apt install ovmf —— 模板还引用了宿主机的 /usr/share/OVMF/OVMF_CODE_4M.fd(发行版持久化构建)。不要 使用 OSX-KVM 自带的非持久化副本,否则 bless 不可见,冷启动会停在 Apple 的磁盘选择界面(见下方约束 1)
  2. 匹配的拓扑 —— q35 + 1f:2 处内置 SATA + 系统盘在 2 号端口是 domain-macos.xml.j2 中硬编码的,使用同一个 ansible-vms role 即自动满足
  3. QEMU >= 8.2.2 及相近版本的 libvirt(用于 qemu:commandline)

无需复制:BaseSystem.img、fetch-macOS-v2.py、 boot-macos-install.sh——仅在重建基础镜像时使用。

配置(vms.csv)

添加一行,type=macos。disk_gb 必须等于基础镜像的虚拟大小(64)。 macOS 使用 DHCP,因此 ip/netmask/gateway/dns 留空(只有需要静态 IP 时才填写——见 静态 IP)。VNC 端口由 libvirt 自动分配 (list-vms 显示实际端口)。

数据盘:把 data_disk_gb 列(第 8 列)设为大于 0 的大小,即可在同一个 内置 AHCI 控制器上挂载一块额外的 SATA 磁盘(sdc)——macOS 原生识别, 无需 kext。与 Linux/Windows 客户机一样,SATA 总线不能热插拔,所以要在 创建时设置(或冷 attach 后重启);对已创建的虚拟机该列会被忽略。

macos-sonoma-01,local,macos,8192,4,macos-sonoma,64,0,/home/fish/bucket/kvm/macos/macos-sonoma-base.img,br0,52:54:00:ff:00:01,efi,false,/home/fish/bucket/kvm/macos,,,,,

创建

uv run ansible-playbook playbooks/create-vm.yaml -e vm_name=macos-sonoma-01

构建两个 overlay(系统盘 + OpenCore),从 bless 模板播种每台虚拟机的 NVRAM,并定义/启动 domain。冷启动无需任何键盘输入;登录窗口约 40 秒内 出现。

网络:默认 DHCP(br0 上游路由器)。查询 IP:

uv run ansible-playbook playbooks/list-vms.yaml

IP 列会列出每台虚拟机的地址(如 macOS 的 192.168.100.45),VNC 列显示 127.0.0.1:<port>。

对 macOS 客户机执行 Ansible 必须用 -m raw——客户机内没有 Python 解释器。

静态 IP(可选)

要把 macOS 虚拟机从 DHCP 切换为自定义静态 IP,分两步:

  1. 先在 vms.csv 中定义网络——填写 ip、netmask (CIDR 前缀,如 22)、gateway 和 dns 列(四项都必填; configure-macos-network.yaml 会在操作客户机前断言这一点):

    ...,efi,false,/home/fish/bucket/kvm/macos,192.168.100.45,24,192.168.100.1,192.168.100.53,
  2. 针对当前(DHCP)地址运行 playbook:

    uv run ansible-playbook playbooks/configure-macos-network.yaml -e vm_name=macos-sonoma-01 -e boot_ip=192.168.100.45

    boot_ip 是虚拟机此刻响应的 DHCP 地址(用 list-vms 查询)。playbook 通过 SSH 登录,按虚拟机的 MAC 定位 BSD 接口,执行 networksetup -setmanual/-setdnsservers,并验证新的静态 IP 在 22 端口可响应。之后把该虚拟机的条目在 hosts.ini 中更新(或新增)为 静态 IP。

启动

uv run ansible-playbook playbooks/start-vm.yaml -e vm_name=macos-sonoma-01

停止

uv run ansible-playbook playbooks/stop-vm.yaml -e vm_name=macos-sonoma-01

macOS 忽略 ACPI 关机,因此 playbook 只打印提示:

  • 从桌面:Apple 菜单 → 关机
  • 或通过 SSH:ssh admin@<ip> 'sudo shutdown -h now'

virsh shutdown 对 macOS 客户机无效——不要使用。

销毁

uv run ansible-playbook playbooks/destroy-vm.yaml -e vm_name=macos-sonoma-01 -e confirm=true

先停止虚拟机(见上)。共享的基础镜像和资产不会被触碰。

快照

macOS domain 通过 pflash OVMF 和 RAW NVRAM 文件启动,libvirt 因此拒绝 完整(含内存)快照。快照 playbook 会对 macOS 自动回退为仅磁盘快照:

# snapshot a running VM (disk-only)
uv run ansible-playbook playbooks/snapshot-vm.yaml -e vm_name=macos-sonoma-01 -e snap_action=create -e snapshot_name=my-snap -e halt=false

# revert (VM must be shut off first; playbook tells you)
uv run ansible-playbook playbooks/snapshot-vm.yaml -e vm_name=macos-sonoma-01 -e snap_action=restore -e snapshot_name=<snap> -e confirm=true

需要了解的局限:

  • NVRAM 不包含在快照中——启动状态永远不会回滚
  • halt=true 时 playbook 会中止并提示:macOS 忽略 ACPI,如需一致的快照 请先自行关机(桌面或 SSH)
  • AHCI 上的 APFS 没有 TRIM,删除快照回收的空间有限

模板约束(domain-macos.xml.j2)

有四处细节必须与验证过的手工配置一致;违反任何一处都会表现为看似无关的 另一种故障:

  1. 持久化 OVMF:使用宿主机的 /usr/share/OVMF/OVMF_CODE_4M.fd,而非 OSX-KVM 自带的非持久化构建
  2. bless 拓扑匹配:磁盘位于 q35 内置 AHCI(PCI 1f:2); 绝不能添加第二块 ich9-ahci 设备
  3. 网卡固定在 root-bus slot=0x05:macOS 的 virtio-net 驱动只会在 固定的 root-bus 位置绑定——如果 libvirt 把网卡自动放到 pcie-root-port 子设备上,客户机将永远看不到它
  4. <seclabel type='none'/>:外部(仅磁盘)快照会把共享的 OpenCore.qcow2 / 基础镜像在 backing 链中多嵌套一层 (… → .inited → overlay → base)。libvirt 的 virt-aa-helper 只允许 XML 中列出的文件(源 + 一层 backingStore),更深层的共享资产会被 AppArmor 拒绝,虚拟机无法启动。在此禁用按域的 AppArmor 是安全的—— qemu:commandline 自定义设备已使该 domain 超出标准 confined-qemu 模型。

完整原理与 bless 流程: macOS 基础镜像。

13 - macOS 基础镜像

在 Debian 12 上用 OSX-KVM 从零制作 macos-sonoma-base.img。

在 Debian 12 KVM 宿主机上,用 kholia/OSX-KVM 方案手工安装 macOS Sonoma,再把成品盘固化成一张自包含的 qcow2 模板镜像,供后续派生 macOS VM 使用。

  • 产出物:/home/fish/bucket/kvm/macos/macos-sonoma-base.img
  • Guest:macOS Sonoma 14.8.9(x86_64),4 vCPU / 8 GB,账户 admin / admin,Remote Login 已开
  • OSX-KVM 仓库(下文简称 repo):/home/fish/bucket/OSX-KVM
  • 记录时间:2026-09-10(更新于 2026-09-20)

前置条件

  • 宿主机 QEMU >= 8.2.2(本机 10.0.2)、libvirt >= 9(本机 11.3.0,来自 bookworm-backports)
  • /dev/kvm 可用
  • 已 clone OSX-KVM 仓库到 repo
  • VNC 客户端:宿主机 DISPLAY=:0 上的 VNC viewer,或 ssh -L 转发后本地连接
  • 磁盘空间:base image 实际约 29G,安装过程需额外空间

OVMF 选择(重要)

安装阶段可以使用 OSX-KVM 自带的 OVMF(非持久化,不影响安装):

  • OVMF_CODE_4M.fd(3.5M)
  • OVMF_VARS-1920x1080.fd(128K)——必须用不带 -exp 后缀的版本

Bless + 集成到 libvirt 时必须换成宿主机发行版的持久化 OVMF:

  • code: /usr/share/OVMF/OVMF_CODE_4M.fd
  • vars: 540672 字节的持久化 VARS 文件(从真实 bless 后落盘的 VARS 复制而来)

OSX-KVM 自带的 OVMF 是 RAM-backed / EmuVariable 版本,完全不读写磁盘上的 VARS 文件。 bless 写入的 efi-boot-device 变量无法持久化,冷启动必然停在 Apple Startup Manager。

1. 下载并转换安装介质

cd /home/fish/bucket/OSX-KVM

# 从 Apple CDN 下载恢复镜像(交互式选版本,选 Sonoma)
./fetch-macOS-v2.py
# 产物:BaseSystem.dmg(753M)+ BaseSystem.chunklist

# 转 raw 格式(QEMU 需要 raw,不能直接挂 dmg)
sudo -n apt install -y dmg2img    # 如未安装
dmg2img -i BaseSystem.dmg BaseSystem.img
# 产物:BaseSystem.img(约 3G),安装器 + Recovery 环境

2. 创建安装目录和磁盘

WORK=/home/fish/bucket/kvm/macos-new
mkdir -p $WORK

# 创建目标安装盘(qcow2,按需选大小)
qemu-img create -f qcow2 $WORK/macos-sonoma-new.qcow2 64G

# 复制 OVMF VARS 模板(安装阶段用 OSX-KVM 自带的非持久化版本即可)
cp /home/fish/bucket/OSX-KVM/OVMF_VARS-1920x1080.fd $WORK/install-OVMF_VARS.fd

qcow2 支持后期扩容:qemu-img resize xxx.qcow2 128G + guest 内 diskutil apfs resizeContainer diskN 0,初始选小不影响后续。

3. 启动安装 VM

使用 boot-macos-install.sh 脚本(位于 /home/fish/bucket/OSX-KVM/):

#!/bin/bash
# Install macOS Sonoma onto a fresh disk
set -euo pipefail
D=/home/fish/bucket/kvm
M=$D/macos-new
OSX=/home/fish/bucket/OSX-KVM
sudo -n qemu-system-x86_64 \
  -enable-kvm -m 8192 -smp 4,cores=2,sockets=1 \
  -cpu Skylake-Client,-hle,-rtm,kvm=on,vendor=GenuineIntel,+invtsc,vmware-cpuid-freq=on,+ssse3,+sse4.2,+popcnt,+avx,+aes,+xsave,+xsaveopt,check \
  -machine q35 \
  -device qemu-xhci,id=xhci \
  -device usb-kbd,bus=xhci.0 -device usb-tablet,bus=xhci.0 \
  -device isa-applesmc,osk="ourhardworkbythesewordsguardedpleasedontsteal(c)AppleComputerInc" \
  -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE_4M.fd \
  -drive if=pflash,format=raw,file=$M/install-OVMF_VARS.fd \
  -smbios type=2 \
  -drive id=OpenCoreBoot,if=none,snapshot=on,format=qcow2,file=$OSX/OpenCore/OpenCore.qcow2 \
  -device ide-hd,bus=ide.0,drive=OpenCoreBoot \
  -drive id=Installer,if=none,format=raw,file=$OSX/BaseSystem.img \
  -device ide-hd,bus=ide.1,drive=Installer \
  -drive id=MacHDD,if=none,format=qcow2,file=$M/macos-sonoma-new.qcow2 \
  -device ide-hd,bus=ide.2,drive=MacHDD \
  -netdev user,id=net0,hostfwd=tcp::2222-:22 \
  -device virtio-net-pci,netdev=net0 \
  -device vmware-svga -vnc 127.0.0.1:83

启动:

cd /home/fish/bucket/OSX-KVM
sudo -n bash boot-macos-install.sh

要点:

  • 三块盘全部挂 q35 内置 AHCI(ide.0 / ide.1 / ide.2),不额外加 ich9-ahci 设备——保证磁盘控制器在 PCI 1f:2,这是后续 bless 正确落盘的前提(详见"技术背景:PCI 拓扑与 bless")
  • snapshot=on 保护 OpenCore 盘不被安装过程修改
  • usb-tablet 让 VNC 客户端指针绝对定位(点击才准)
  • VNC display :83(端口 5983)
  • 使用宿主机持久化 OVMF CODE(/usr/share/OVMF/OVMF_CODE_4M.fd),确保 bless 后变量能落盘

4. VNC 完成安装

连接 VNC:

DISPLAY=:0 setsid nohup vncviewer 127.0.0.1:5983 Shared=false &

安装流程(全程人工点击,键盘不稳时以鼠标为主):

  1. OpenCore 选择界面:方向键选 macOS Base System,回车进 Recovery
  2. Recovery 主窗口 -> 双击 Reinstall macOS Sonoma 行 -> 右下 Continue
  3. 许可页 Agree
  4. 目标磁盘选择页:如果只显示 macOS Base System(2.87G,Recovery 自身),说明目标盘还没分区。点 Back 退回 Recovery
  5. 打开 Disk Utility -> 菜单 View -> Show All Devices -> 选中 QEMU HARDDISK Media(整块虚拟盘)
  6. Erase:Name Macintosh HD / Format APFS / Scheme GUID Partition Map,抹完关掉 Disk Utility
  7. 重新进 Reinstall macOS Sonoma,此时列表出现 Macintosh HD -> Continue
  8. 等待安装完成(几十分钟到一小时+),弹出 Restart -> 点击
  9. 重启回 OpenCore 选择界面 -> 选 Macintosh HD -> 进首次启动引导
  10. Setup Assistant:
    • 语言只选 English(减少语言包占用)
    • Region 随意(选美国/澳洲比较中性,别选 American Samoa 之类奇葩时区)
    • 键盘默认
    • 迁移选 Not Now
    • 不安装 Xcode CLI tools(省 ~1.5G)
    • Account:Full Name / Account Name 用 admin,密码 admin

坑:

  • 首次启动时 vmware-svga 驱动加载有一小段灰屏(几分钟),别当成卡死
  • Recovery 主窗口的键盘导航不稳(Tab 移焦点可以、Space/Return 无法激活列表项),列表行必须鼠标双击
  • 从 VNC 脚本化点击(手写 RFB PointerEvent)在 QEMU 上不稳(BrokenPipe),直接用真 VNC 客户端最省事

5. 体积优化(安装完成后、bless 之前)

SSH 或在 Terminal 里执行:

# 关休眠(省 ~4G sleepimage)
sudo pmset -a hibernatemode 0
sudo rm -f /var/vm/sleepimage

# 清缓存
sudo rm -rf /Library/Caches/* ~/Library/Caches/*

# 清日志
sudo rm -rf /var/log/*.gz /var/log/*.old /private/var/log/asl/*.asl

6. 开 Remote Login(SSH)

System Settings -> General -> Sharing -> Remote Login 打开,右侧 i -> 允许 All users。

macOS 默认关闭 Remote Login;关掉 Network Firewall 或允许 ssh,避免 kex_exchange_identification: Connection closed。

7. Bless + 干净关机

这是让冷启动免键盘的关键步骤(详见"技术背景:PCI 拓扑与 bless")。

在 macOS guest 内执行:

# 确认 SIP 已关(OpenCore csr-active-config 已设 NVRAM Protections=disabled)
csrutil status

# 写入 efi-boot-device 到 OVMF NVRAM
sudo bless --mount / --setBoot --verbose

# 干净关机,让 OVMF 把变量落盘
sudo shutdown -h now

别硬 kill QEMU——qcow2 会脏,还可能被 journal 卡住恢复。

看到 SSH 断、QEMU 进程自己退出(pgrep -f qemu-system 无输出)即可。

8. 校验并晋升 NVRAM 模板

# 校验 bless 写入的设备路径
virt-fw-vars -i $WORK/install-OVMF_VARS.fd -p | grep -E 'efi-boot-device|Boot0080'
# Boot0080 devpath 必须读作 ... PCI(dev=1f:2)/SATA(port=1)/Partition(nr=2)/.../boot.efi

# 晋升为共享模板
cp $WORK/install-OVMF_VARS.fd /home/fish/bucket/kvm/macos/OVMF_VARS-blessed.fd

9. 生成 base image

sudo qemu-img convert -f qcow2 -O qcow2 \
  $WORK/macos-sonoma-new.qcow2 \
  /home/fish/bucket/kvm/macos/macos-sonoma-base.img
sudo chown libvirt-qemu:libvirt-qemu /home/fish/bucket/kvm/macos/macos-sonoma-base.img

校验:

qemu-img info /home/fish/bucket/kvm/macos/macos-sonoma-base.img
# 期望:file format: qcow2、virtual size: 64 GiB、**没有 backing file 行**

产物就是只读模板。派生新 VM 时以它为 backing:

qemu-img create -f qcow2 -b /home/fish/bucket/kvm/macos/macos-sonoma-base.img \
  -F qcow2 <vm-name>.qcow2

注意:macOS APFS 在 AHCI SATA 上不支持 TRIM(QEMU 只有 virtio-blk/scsi/nvme 支持), 所以 fstrim 和 qemu-img convert 的稀疏回收效果有限。实测 Sonoma 精简安装的 地板约 29G,无法通过在线方式显著缩小。


技术背景:PCI 拓扑与 bless

这是 macOS-on-KVM 最容易踩坑的地方,理解它可以避免大量排查弯路。

问题

Apple boot.efi 自己画的 Startup Manager(磁盘选择界面):只要 OVMF 里持久化的 efi-boot-device / efi-boot-device-data 变量缺失、或其中编码的设备路径跟当前 PCI 拓扑对不上,就会停在这里等键盘输入。

而 libvirt 对 macOS guest 的键盘注入(send-key / QMP input-send-event)实测 三种 USB 控制器(默认 xhci、pin 到 bus0 的 xhci、ich9-ehci1 + ich9-uhci1) 全部无响应(截图像素级 AE=0),完全相同的设备配置在裸 qemu 里却是好的。

所以正确做法是让冷启动本身不需要任何键盘输入。

PCI 拓扑匹配

q35 机器类型自带一块 ICH9 AHCI 控制器固定在 PCI 1f:2,libvirt 的 <controller type='sata'> 用的就是这个内置控制器。

OSX-KVM 教程脚本里的 -device ich9-ahci,id=sata 是额外加的第二块控制器, 落在 02:0。在 02:0 拓扑下 bless 出来的 efi-boot-device device-path 放进 1f:2 拓扑的 libvirt 域里不匹配,照样弹 picker。

这个拓扑不匹配一度被误判为"libvirt 键盘坏了导致的集成障碍",实际根因从头到尾只是 设备路径对不上。

正确做法

安装脚本(boot-macos-install.sh)不加额外 ich9-ahci,磁盘直接挂 q35 内置 AHCI 总线(ide.0 / ide.1 / ide.2),天然 1f:2。在这个拓扑下 bless,设备 路径就是 PCI(dev=1f:2)/SATA(port=N)/...,与任何同样使用 1f:2 的 libvirt 域 完全匹配。

OpenCore config.plist 注意事项

NVRAM > Delete 列表里不能有 efi-boot-device / efi-boot-device-data (只留 boot-args 和 ForceDisplayRotationInEFI),否则每次启动都会被自己抹掉, 破坏 bless 持久化。

libvirt EFI 域生命周期坑

virsh undefine 对带 nvram 的域必须加 --nvram,而加了之后会删除 VARS 文件。 因为这份 VARS 是预先烘焙好内容的模板(不是 libvirt 自动生成的空模板),手工重新 define 前必须先重新 cp 一次 OVMF_VARS-blessed.fd 到目标路径:

destroy -> undefine --nvram -> cp blessed 模板 -> define -> start

create-vm role 每次创建时都会重新播种 VARS,所以走 role 正常不受影响;只有手工 改 XML 重定义才需要记这个顺序。

技术背景:关键决策

  • 选 Sonoma 而非最新 macOS:OSX-KVM 对 Intel 模拟(Skylake-Client + OpenCore)+ Sonoma 组合最成熟;Tahoe 起 Intel 支持收窄
  • 保留 OpenCore.qcow2 的 snapshot=on:EFI 盘改动不落地,避免多次启动互相污染
  • 不共用 OVMF_VARS .fd:每台 VM 必须独立拷贝一份,否则 NVRAM 冲突

附录 A:OpenCore 引导盘

OpenCore/OpenCore.qcow2 是预构建的 OpenCore 引导盘,关键配置:

  • SIP 已关闭:csr-active-config 设为 NVRAM Protections disabled
  • 自动引导:Misc > Boot 已配置跳过 picker(bless 后自动选 macOS 盘)
  • NVRAM > Delete 列表:只删 boot-args 和 ForceDisplayRotationInEFI,不能删 efi-boot-device / efi-boot-device-data

安装时挂法:

-drive id=OpenCoreBoot,if=none,snapshot=on,format=qcow2,file=$OSX/OpenCore/OpenCore.qcow2
-device ide-hd,bus=ide.0,drive=OpenCoreBoot

snapshot=on 确保安装过程对 OpenCore 盘的改动不落盘,保持引导盘干净。

附录 B:OSX-KVM 仓库资产清单

仓库地址:kholia/OSX-KVM 本机路径:/home/fish/bucket/OSX-KVM

文件 大小 用途
fetch-macOS-v2.py – 从 Apple CDN 下载 macOS 恢复镜像(交互式选版本)
BaseSystem.dmg 753M Apple 官方恢复镜像原始下载
BaseSystem.img 3.0G dmg2img 转换后的 raw 安装器,直接挂给 VM
OpenCore/OpenCore.qcow2 – 已打补丁的 OpenCore 引导盘(SIP 已关、自动引导)
OVMF_CODE_4M.fd 3.5M OSX-KVM 自带的 OVMF CODE(非持久化)
OVMF_VARS-1920x1080.fd 128K OSX-KVM 自带的 OVMF VARS 模板(非持久化)

仓库内脚本说明

脚本 说明
boot-macos-install.sh base image 安装启动脚本(本文第 3 步)
boot-macos-ctrl4.sh bless 实验脚本,用 q35 内置 AHCI(1f:2),不加额外 ich9-ahci
boot-macos-experiment.sh 早期实验安装脚本(128G + 额外 ich9-ahci 02:0),仅供参考
boot-macos-ctrl.sh / ctrl2 / ctrl3 迭代版本,已不需要
boot-macOS-headless.sh OSX-KVM 原版 GUI 启动脚本

附录 C:磁盘布局

/home/fish/bucket/OSX-KVM/          # 开源项目目录(git clone)
+-- fetch-macOS-v2.py               # 安装介质下载工具
+-- BaseSystem.dmg / BaseSystem.img # macOS Sonoma 安装介质
+-- OpenCore/OpenCore.qcow2         # OpenCore 引导盘(共享,只读)
+-- OVMF_CODE_4M.fd                 # 非持久化 OVMF(仅安装阶段可用)
+-- OVMF_VARS-1920x1080.fd          # 非持久化 OVMF VARS(仅安装阶段可用)
+-- boot-macos-install.sh           # base 安装启动脚本
+-- boot-macos-ctrl4.sh             # bless 实验脚本

/home/fish/bucket/kvm/macos/        # ansible-vms 托管资产目录
+-- macos-sonoma-base.img           # 正式 base image(每台 VM 的 backing)
+-- OpenCore.qcow2                  # OpenCore 引导盘(从 OSX-KVM 复制)
+-- OVMF_CODE_4M.fd                 # 宿主机持久化 OVMF CODE(从 /usr/share/OVMF 复制)
+-- OVMF_VARS-blessed.fd            # 已 bless 的 NVRAM 模板(冷启动免键盘的关键)
+-- <vm-name>/                      # 每台 VM 的工作目录
    +-- <vm-name>.qcow2             # 系统盘 overlay(backing -> base)
    +-- <vm-name>-OpenCore.qcow2    # OpenCore overlay(backing -> 共享 OpenCore)
    +-- <vm-name>-OVMF_VARS.fd      # 从 blessed 模板复制的 per-VM NVRAM

/home/fish/bucket/kvm/macos-new/    # base image 安装临时目录
+-- macos-sonoma-new.qcow2          # 安装盘(安装完成后 convert 为 base)
+-- install-OVMF_VARS.fd            # 安装用 VARS 副本(bless 后晋升为 blessed)

附录 D:资产流转

fetch-macOS-v2.py -> BaseSystem.dmg -> dmg2img -> BaseSystem.img
                                                    |
boot-macos-install.sh(挂三块盘启动安装 VM)
    +-- OpenCore.qcow2          (ide.0, snapshot=on)
    +-- BaseSystem.img          (ide.1, 安装器)
    +-- macos-sonoma-new.qcow2  (ide.2, 目标盘)
                                                    |
安装完成 + bless + shutdown
    -> install-OVMF_VARS.fd 晋升为 OVMF_VARS-blessed.fd
                                                    |
qemu-img convert -> macos-sonoma-base.img
                                                    |
create-vm.yaml 自动化:每台新 VM 以 base 做 backing 派生 overlay

实测执行记录(2026-09-20,本次制作)

按上述步骤实际执行一遍,记录关键命令与验证结果,供下次复现对照。

安装阶段网络坑与修复

安装 VM 用 QEMU user-net(slirp NAT),guest 里 ipconfig getifaddr en0 拿到 10.0.2.15——这是 NAT 内部地址,宿主机无法直接 ping/SSH 到。修复:给 boot-macos-install.sh 的 -netdev user,id=net0 加上 hostfwd=tcp::2222-:22,宿主机通过 ssh -p 2222 admin@127.0.0.1 直接访问 guest, 不需要改网络拓扑、不需要 VNC 里手动敲命令。

# 宿主机验证(安装完成、Remote Login 已开之后)
sshpass -p admin ssh -p 2222 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
  admin@127.0.0.1 'sw_vers; ipconfig getifaddr en0'
# ProductVersion: 14.8.9   10.0.2.15

体积优化(步骤 5)

sshpass -p admin ssh -p 2222 ... admin@127.0.0.1 '
  echo admin | sudo -S -p "" pmset -a hibernatemode 0
  echo admin | sudo -S -p "" rm -f /var/vm/sleepimage
  echo admin | sudo -S -p "" rm -rf /Library/Caches/* ~/Library/Caches/*
  echo admin | sudo -S -p "" sh -c "find /var/log -name *.gz -delete; rm -rf /private/var/log/asl/*.asl"
'

bless 验证(步骤 7)

sshpass -p admin ssh -p 2222 ... admin@127.0.0.1 \
  'echo admin | sudo -S -p "" bless --mount / --setBoot --verbose'

关键输出(确认写入的是 UUID 指向 preboot 卷、拓扑正确):

Setting EFI NVRAM:
    efi-boot-device='<array>...UUID</key><string>98FA02AF-D0A8-4E55-8B63-F9FC985A4251</string>...
    \System\Library\CoreServices\boot.efi</string></dict></array>'

关机(shutdown -h now,rc=255 是 SSH 断开的正常表现,不是错误)后, 宿主机上必须等 QEMU 进程自己退出(用 pgrep/ps 确认,不能用 pgrep 匹配 到自己刚执行的 shell 命令),否则 VARS 文件可能还没落盘完整。

校验 NVRAM(步骤 8)

virt-fw-vars -i /home/fish/bucket/kvm/macos-new/install-OVMF_VARS.fd -p \
  | grep -iE 'Boot00|efi-boot-device'

期望看到 Boot0080,devpath 必须读作 PciRoot()/PCI(dev=1f:2)/SATA(port=2)/... ——本次实测正是这个路径(port=2 对应安装盘挂在 ide.2,与 libvirt 域将来 用的拓扑一致,见"技术背景:PCI 拓扑与 bless"):

Boot0080 : boot entry: title="" devpath=PciRoot()/PCI(dev=1f:2)/SATA(port=2)/Partition(nr=2)/Media(subtype=0x3)/FilePath(\...\boot.efi)
efi-boot-device      : blob: 444 bytes
efi-boot-device-data : blob: 264 bytes

生成 base image(步骤 9)

sudo qemu-img convert -f qcow2 -O qcow2 \
  /home/fish/bucket/kvm/macos-new/macos-sonoma-new.qcow2 \
  /home/fish/bucket/kvm/macos/macos-sonoma-base.img
sudo chown libvirt-qemu:libvirt-qemu /home/fish/bucket/kvm/macos/macos-sonoma-base.img
# 实测耗时:4 分 24 秒

最终产物校验:

qemu-img info /home/fish/bucket/kvm/macos/macos-sonoma-base.img
# file format: qcow2
# virtual size: 64 GiB
# disk size: 29.1 GiB      (无 backing file 行,自包含)

再次验证:虚拟盘从 128G 缩到 64G,实际占用仍是 29.1G(对比之前 128G 虚拟盘实测 28.9G, 基本一致)。印证了本文档开头结论:base image 无法通过调整虚拟盘大小来缩小实际占用, 29G 是 macOS APFS-on-AHCI 无 TRIM 支持下的固有地板(详见"体积优化"与"技术背景"两节)。