> For AI agents: the complete documentation index is available at https://www.tteam.icu/llms.txt, the full documentation bundle is available at https://www.tteam.icu/llms-full.txt.

# libvirt


AI SummaryAI Generated

**核心内容**：记录 Debian/Ubuntu 与红帽系系统安装 KVM/libvirt、启动默认 NAT 网络、导入 qcow2 镜像并挂载数据盘的常用命令。
**内容要点**：
- 安装与环境准备
- 默认 NAT 网络
- 导入 qcow2 镜像创建虚拟机
- 创建并挂载数据盘
- 常用维护命令
内容偏向可直接复用的运维操作，涵盖命令、配置顺序和部署注意事项。

## 安装


**Debian/Ubuntu**

```shell
apt update
apt install -y \
  virt-manager \
  virtinst \
  libvirt-daemon-system \
  qemu-system-x86 \
  qemu-utils \
  bridge-utils \
  osinfo-db
```
其中 `virtinst` 提供 `virt-install`，`qemu-utils` 提供 `qemu-img`。如果只在服务器上使用命令行，可以不安装 `virt-manager`。
```shell
systemctl enable --now libvirtd

# 非 root 用户管理虚拟机时使用，执行后需要重新登录
usermod -aG libvirt,kvm "$USER"
```


**Red Hat/Rocky/Alma/CentOS**

红帽系发行版可以使用 `dnf` 安装 KVM/libvirt 相关组件：
```shell
dnf install -y \
  qemu-kvm \
  libvirt \
  virt-install \
  virt-viewer \
  qemu-img \
  bridge-utils \
  osinfo-db
```
如果需要图形化管理工具，可以额外安装：
```shell
dnf install -y virt-manager
```
Rocky Linux 10 已经不再提供 `virt-manager`，可以改用 Cockpit 管理虚拟机。
```shell
dnf install -y cockpit cockpit-machines
systemctl enable --now cockpit.socket
```
安装完成后，可以通过 `https://宿主机IP:9090` 访问 Cockpit。
红帽系如果需要在 `/data/images` 之类的自定义目录存放虚拟机磁盘，还要注意 SELinux 上下文：
```shell
dnf install -y policycoreutils-python-utils
semanage fcontext -a -t virt_image_t "/data/images(/.*)?"
restorecon -Rv /data/images
```
```shell
systemctl enable --now libvirtd

# 非 root 用户管理虚拟机时使用，执行后需要重新登录
usermod -aG libvirt,kvm "$USER"
```
RHEL 9/10 也可以按模块化 socket 启动 libvirt 服务：
```shell
for drv in qemu network nodedev nwfilter secret storage interface; do
  systemctl enable --now "virt${drv}d.socket"
done
```


可以先确认宿主机是否支持硬件虚拟化：

```shell
lscpu | grep -i virtualization
```

## 默认 NAT 网络

libvirt 默认会创建一个名为 `default` 的 NAT 网络，虚拟机可以通过它访问外网。

```shell
virsh net-list --all

virsh net-start default

# 设置开机自动激活
virsh net-autostart default
```

如果需要查看默认网络的配置：

```shell
virsh net-dumpxml default
```

## 导入 qcow2 镜像创建虚拟机

这里适合导入已经能启动的系统盘，例如提前做好的 Debian qcow2 模板。`--import` 不会进入安装流程，而是直接把已有磁盘作为启动盘。

```shell
virt-install \
  --name instance \
  --memory 16384 \
  --vcpus 8 \
  --cpu host-passthrough \
  --disk path=/data/images/debian12_template_v2.qcow2,format=qcow2,bus=virtio \
  --import \
  --os-variant generic \
  --network network=default,model=virtio \
  --graphics vnc,listen=0.0.0.0 \
  --video virtio \
  --console pty,target_type=serial
```

:::warning
`--graphics vnc,listen=0.0.0.0` 会让 VNC 监听所有网卡，生产环境需要配合防火墙、安全组或 SSH 隧道限制访问。
:::

如果本机的 `osinfo-db` 能识别具体发行版，可以用更精确的 `--os-variant`：

```shell
osinfo-query os | grep -i debian
```

常用检查命令：

```shell
# 查看虚拟机
virsh list --all

# 查看 VNC 端口
virsh vncdisplay instance

# 关机、启动、重启
virsh shutdown instance
virsh start instance
virsh reboot instance
```

## 创建并挂载数据盘

先创建一个 qcow2 数据盘：

```shell
qemu-img create -f qcow2 /data/images/vm/hw-902c-arm-1-data.qcow2 100G
```

挂载到虚拟机：

```shell
virsh attach-disk hw-902c-arm-1 \
  /data/images/vm/hw-902c-arm-1-data.qcow2 \
  vdb \
  --driver qemu \
  --subdriver qcow2 \
  --targetbus virtio \
  --cache none \
  --persistent
```

如果是批量创建，可以用变量保留原始命名习惯：

```shell
for i in 1 2 3; do
  vm_name="hw-902c-arm-${i}"
  data_disk="/data/images/vm/${vm_name}-data.qcow2"

  qemu-img create -f qcow2 "$data_disk" 100G

  virsh attach-disk "$vm_name" \
    "$data_disk" \
    vdb \
    --driver qemu \
    --subdriver qcow2 \
    --targetbus virtio \
    --cache none \
    --persistent
done
```

## 常用维护命令

```shell
# 查看虚拟机配置
virsh dumpxml instance

# 编辑虚拟机配置
virsh edit instance

# 分离数据盘
virsh detach-disk hw-902c-arm-1 vdb --persistent

# 删除虚拟机定义，不删除磁盘文件
virsh undefine instance
```