# virt-install 命令详解：KVM 虚拟机命令行部署指南

**作者：吉祥法师**

## 概述

virt-install 是 libvirt 工具集提供的命令行工具，用于在 KVM 虚拟化平台上创建和管理虚拟机。该工具支持多种安装介质——包括本地 ISO 镜像、HTTP 安装源、PXE 网络引导以及导入现有磁盘镜像——并提供对 CPU、内存、存储、网络、控制台和开机自启等参数的细粒度配置。通过脚本化和自动化部署流程，virt-install 成为系统管理员在无图形界面环境中快速创建虚拟机的核心工具。

## 核心概念与快速参考

### 虚拟机命名与资源分配

虚拟机名称在宿主机上必须唯一，通过 `--name` 参数指定。内存以 MiB 为单位进行分配，使用 `--memory` 参数设置。虚拟 CPU 数量通过 `--vcpus` 参数配置。操作系统类型描述符通过 `--osinfo` 参数指定，它通知 virt-install 使用合适的 virtio 默认配置。

### 安装介质选择

virt-install 提供了五种安装方式：

1. **本地 ISO 安装**：使用 `--cdrom` 参数指定 ISO 文件路径，将镜像作为虚拟 CD-ROM 挂载。
2. **HTTP/FTP 安装源**：使用 `--location` 参数指向发行版安装树，virt-install 会拉取内核和 initrd 文件并自动启动安装程序。
3. **PXE 网络引导**：使用 `--pxe` 参数，虚拟机首次启动时通过网络引导，要求网络能够访问 DHCP、TFTP/iPXE 服务。
4. **导入现有磁盘**：使用 `--import` 参数，引导已配置好的可启动磁盘镜像。
5. **简化的 `--install` 参数**：允许使用 libosinfo 配置文件中的默认值进行安装。

### 存储配置选项

`--disk` 参数支持多种格式：

- `--disk size=20`：在默认存储池中创建 20GB 的 qcow2 磁盘
- `--disk pool=vm-disks,size=40,format=qcow2`：在自定义存储池中创建卷
- `--disk path=/disks/vm.qcow2,size=20,format=qcow2`：指定自定义路径
- 重复使用可以附加多个磁盘

### 网络配置选项

`--network` 参数可以重复使用以添加多个网络接口：

- `--network network=default`：连接 libvirt 默认 NAT 网络
- `--network bridge=br0`：桥接到宿主机桥接设备
- 确保需要时网络已启用并设为自启动

### 控制台与图形配置

- `--graphics vnc`：启用 VNC 图形控制台
- `--graphics none --console pty,target_type=serial`：仅串行控制台
- `--noautoconsole`：安装开始后立即返回 shell
- `--wait -1`：保持 virt-install 运行，直到安装后重启

### 安装后行为

- `--autostart`：标记虚拟机在宿主机启动时自动启动
- `--dry-run --print-xml`：预览生成 XML 而不定义虚拟机
- `--unattended`：执行无人值守安装

## 命令语法与使用示例

在 KVM 宿主机上运行 virt-install 时，通常指定系统虚拟化连接 URI：

```
virt-install --connect qemu:///system [OPTIONS]
```

命令行核心参数包括 `--name`（虚拟机名称）、`--memory`（内存大小）、`--vcpus`（虚拟 CPU 数量）、`--disk`（存储配置）、`--network`（网络配置）、`--graphics`（图形配置）以及指定安装源的相关参数。

### 预览配置：验证命令正确性

在任何正式创建操作之前，使用 `--dry-run --print-xml` 组合参数可以验证配置的正确性，并预览将要生成的 libvirt 域 XML：

```bash
sudo virt-install --dry-run --print-xml \
  --name demo-test \
  --memory 2048 --vcpus 2 \
  --osinfo rocky10 \
  --location https://download.rockylinux.org/pub/rocky/10/BaseOS/x86_64/os/ \
  --disk size=5,format=qcow2 \
  --network network=default \
  --graphics vnc --noautoconsole
```

输出 XML 中的 `` 属性应显示为 `kvm`，而非 `qemu`。如果显示 `qemu`，表示宿主机正在回退到软件模拟，需检查固件中的硬件虚拟化支持和内核模块加载状态。

### 本地 ISO 安装

以下命令使用本地 ISO 安装 Rocky Linux 10.2，通过 VNC 进行图形化安装：

```bash
sudo virt-install --connect qemu:///system \
  --name rocky10-guest \
  --memory 4096 --vcpus 2 \
  --osinfo rocky10 \
  --cdrom /var/isos/Rocky-10.2-x86_64-dvd.iso \
  --disk size=20,format=qcow2 \
  --network network=default \
  --graphics vnc \
  --console pty,target_type=serial
```

VNC 服务默认仅监听本地回环地址。使用 `virsh vncdisplay` 查看显示编号，并通过 SSH 隧道或本地 virt-viewer 连接，无需将 VNC 服务公开暴露。

### HTTP 镜像源安装

当需要网络安装时，`--location` 是更优选择。该方式能够自动获取引导文件：

```bash
sudo virt-install --connect qemu:///system \
  --name rocky10-netinst \
  --memory 2048 --vcpus 2 \
  --osinfo rocky10 \
  --location https://download.rockylinux.org/pub/rocky/10/BaseOS/x86_64/os/ \
  --disk size=10 \
  --network network=default \
  --graphics vnc --noautoconsole
```

若需自动化安装，可通过 kickstart 文件实现：

```bash
--extra-args "inst.ks=https://server.example.com/kickstart/rocky10.cfg"
```

或者将本地 kickstart 文件注入 initrd：

```bash
--initrd-inject /path/to/rocky10.cfg \
--extra-args "inst.ks=file:/rocky10.cfg"
```

### 管理存储存储池

在 RHEL 系发行版中，建议将文件类型磁盘作为目录存储池中的卷。自定义路径需要匹配 SELinux/sVirt 上下文，仅更改属主到 qemu 用户通常无法解决权限问题。创建存储池：

```bash
sudo mkdir -p /disks
sudo virsh pool-define-as vm-disks dir --target /disks
sudo virsh pool-start vm-disks
sudo virsh pool-autostart vm-disks
```

然后引用该存储池：

```bash
sudo virt-install --connect qemu:///system \
  --name app-vm \
  --memory 8192 --vcpus 4 \
  --osinfo rocky10 \
  --cdrom /var/isos/Rocky-10.2-x86_64-dvd.iso \
  --disk pool=vm-disks,size=40,format=qcow2 \
  --network bridge=br0 \
  --graphics vnc --autostart
```

### 多网络接口配置

当虚拟机需要同时具备管理和数据平面流量分离时，可以重复使用 `--network` 参数：

```bash
sudo virt-install --connect qemu:///system \
  --name dual-nic-vm \
  --memory 4096 --vcpus 2 \
  --osinfo rocky10 \
  --location https://download.rockylinux.org/pub/rocky/10/BaseOS/x86_64/os/ \
  --disk size=20 \
  --network network=default \
  --network bridge=br0 \
  --graphics vnc --console pty,target_type=serial
```

在选择桥接接口前，使用 `ip link show type bridge` 查看宿主机上的可用网桥。

### 串行控制台无人值守安装

通过 SSH 远程执行安装时，使用 `--noautoconsole` 让命令立即退出：

```bash
sudo virt-install --connect qemu:///system \
  --name headless-install \
  --memory 2048 --vcpus 2 \
  --osinfo rocky10 \
  --location https://download.rockylinux.org/pub/rocky/10/BaseOS/x86_64/os/ \
  --disk size=10 \
  --network network=default \
  --graphics none \
  --console pty,target_type=serial \
  --extra-args "console=ttyS0" \
  --noautoconsole
```

安装完成后，通过 `virsh console headless-install` 重新连接串行会话，按 `Ctrl+]` 退出。对于分阶段的 `--location` 或 `--cdrom` 安装，虚拟机在安装完成后可能处于关机状态，需要手动 `virsh start` 或使用 `--wait -1` 参数使 virt-install 保持运行直到安装后重启。

### 导入现有磁盘镜像

当不需要执行全新安装时，使用 `--import` 参数引导现有虚拟磁盘：

```bash
sudo virt-install --connect qemu:///system \
  --name imported-vm \
  --memory 2048 --vcpus 2 \
  --import \
  --disk path=/var/lib/libvirt/images/existing.qcow2,format=qcow2 \
  --osinfo rocky10 \
  --network network=default \
  --graphics vnc --noautoconsole
```

需要注意的是，磁盘文件必须事先存在。对于不包含本地登录凭据的云镜像，需要额外使用 `--cloud-init` 参数注入初始配置。

### PXE 网络引导安装

PXE 安装要求选定的网络能够访问 DHCP、TFTP/iPXE 以及引导配置服务。`--pxe` 参数仅配置首次引导时的网络启动：

```bash
sudo virt-install --connect qemu:///system \
  --name pxe-guest \
  --memory 4096 --vcpus 2 \
  --osinfo rocky10 \
  --pxe \
  --disk size=20 \
  --network bridge=br0 \
  --graphics vnc \
  --console pty,target_type=serial
```

## 使用场景判断

**应使用 virt-install 的场景**：

- 需要从 SSH 会话进行可脚本化、可重复的虚拟机创建
- 需要自动化集成 kickstart、cloud-init 或 `--unattended` 功能
- 需要对每个磁盘、网卡和控制台标志进行精确控制
- 需要从 ISO、HTTP 安装树或 PXE 一步完成预配置

**应使用其他工具的场景**：

- 更喜欢图形界面时，使用 Cockpit 或 virt-manager
- 只需管理已存在的虚拟机启停，使用 virsh
- 需要大规模虚拟机管理平台，选择 oVirt、OpenStack 等

## 常用问题排查

### 连接失败

当出现 `failed to connect to the hypervisor` 错误时，通常意味着模块化 libvirt socket 未启动或权限不足。在支持模块化守护进程的系统上，需要启用所有 virt 相关 socket：

```bash
for drv in qemu network nodedev nwfilter secret storage interface; do
  sudo systemctl start virt${drv}d{,-ro,-admin}.socket
done
```

之后验证 `virsh -c qemu:///system list --all` 是否正常工作。

### 网络问题

当默认网络缺失或未激活时，可以启动并设置自启动：

```bash
sudo virsh net-autostart default
sudo virsh net-start default
```

### KVM 加速不可用

如果 XML 预览中显示 `type="qemu"` 而非 `type="kvm"`，说明宿主机回退到软件模拟模式。需要检查固件设置中的 VT-x/AMD-V 选项，确认 `/dev/kvm` 设备存在且内核模块已加载。

## 总结

virt-install 是 KVM 虚拟化管理中不可替代的命令行工具。通过灵活组合各类参数，系统管理员可以完成从简单 ISO 安装到复杂多网络、多磁盘配置的各种任务。结合 `--dry-run` 预览验证机制，virt-install 确保了部署配置的准确性和可预测性，适用于从一次性开发环境到生产级基础设施的广泛场景。