# fnOS Libvirt 操作手册

飞牛OS (fnOS) 虚拟机管理命令参考，用于处理 fnOS Web 界面无法正确识别 libvirt NAT 网络的情况。

## 问题背景

fnOS 的虚拟机管理界面无法正确识别 libvirt 的 `default` NAT 网络，即使命令行显示网络正常：

```bash
sudo virsh -c qemu:///system net-list --all
# Name      State    Autostart   Persistent
# --------------------------------------------
# default   active   yes         yes
```

**根本原因**：fnOS 界面层的判断逻辑问题，libvirt 后端是正常的。

---

## 环境变量约定

建议先设置变量，后续命令更简洁：

```bash
export VM=0z7x696a
export URI=qemu:///system
```

---

## 一、查看状态

### 查看所有虚拟机
```bash
sudo virsh -c $URI list --all
```

### 查看指定 VM 详细信息
```bash
sudo virsh -c $URI dominfo $VM
```

### 查看 VM 网卡配置
```bash
sudo virsh -c $URI domiflist $VM
```

### 查看 VM XML 配置
```bash
sudo virsh -c $URI dumpxml $VM
```

### 备份 XML 配置
```bash
sudo virsh -c $URI dumpxml $VM > /tmp/${VM}-$(date +%F-%H%M%S).xml
```

---

## 二、开机 / 关机 / 重启

### 启动虚拟机
```bash
sudo virsh -c $URI start $VM
```

### 优雅关机
```bash
sudo virsh -c $URI shutdown $VM
```

### 强制断电
```bash
sudo virsh -c $URI destroy $VM
```

### 重启
```bash
sudo virsh -c $URI reboot $VM
```

### 设置开机自启
```bash
sudo virsh -c $URI autostart $VM
```

### 取消开机自启
```bash
sudo virsh -c $URI autostart --disable $VM
```

---

## 三、网络管理

### 查看 libvirt 网络列表
```bash
sudo virsh -c $URI net-list --all
```

### 查看 default 网络详情
```bash
sudo virsh -c $URI net-info default
```

### 查看 default 网络 XML
```bash
sudo virsh -c $URI net-dumpxml default
```

### 启动 default 网络
```bash
sudo virsh -c $URI net-start default
```

### 设置 default 开机自启
```bash
sudo virsh -c $URI net-autostart default
```

### 停止 default 网络
```bash
sudo virsh -c $URI net-destroy default
```

---

## 四、查看虚拟机 IP 地址

### 方法 1：查看 dnsmasq 租约文件
```bash
cat /var/lib/libvirt/dnsmasq/virbr0.status
```

或：
```bash
cat /var/lib/misc/dnsmasq.leases
```

### 方法 2：使用 qemu guest agent
```bash
sudo virsh -c $URI domifaddr $VM
```

### 方法 3：查看 virbr0 接口
```bash
ip addr show virbr0
```

---

## 五、修改 VM 配置（CPU/内存/网络）

### 编辑配置
```bash
sudo virsh -c $URI edit $VM
```

### 内存修改示例（64G）
```xml
<memory unit='KiB'>67108864</memory>
<currentMemory unit='KiB'>67108864</currentMemory>
```

### vCPU 修改示例
```xml
<vcpu placement='static'>64</vcpu>
```

查看宿主机可用 CPU：
```bash
nproc
lscpu
```

### 网络修改为 default NAT

确保网卡部分为：
```xml
<interface type='network'>
  <mac address='e4:27:cd:98:26:6a'/>
  <source network='default'/>
  <model type='virtio'/>
</interface>
```

**注意**：删除旧的 bridge 配置，如：
```xml
<!-- 删除以下内容 -->
<interface type='bridge'>
  <source bridge='enp193s0f0-ovs'/>
  ...
</interface>
```

---

## 六、修改配置的标准流程

### 安全修改步骤

```bash
# 1. 关机
sudo virsh -c qemu:///system shutdown 0z7x696a

# 2. 等待确认关闭
sudo virsh -c qemu:///system list --all

# 3. 备份当前配置
sudo virsh -c qemu:///system dumpxml 0z7x696a > /tmp/0z7x696a-backup.xml

# 4. 编辑配置
sudo virsh -c qemu:///system edit 0z7x696a

# 5. 启动
sudo virsh -c qemu:///system start 0z7x696a

# 6. 验证
sudo virsh -c qemu:///system dominfo 0z7x696a
sudo virsh -c qemu:///system domiflist 0z7x696a
```

---

## 七、端口转发（配合 Traefik）

如果需要用 Traefik 反向代理到 VM 内网服务：

### HTTP 转发
```bash
sudo iptables -t nat -I PREROUTING -p tcp --dport 8080 -j DNAT --to-destination 192.168.122.28:80
sudo iptables -I FORWARD -d 192.168.122.28 -p tcp --dport 80 -j ACCEPT
```

### HTTPS 转发
```bash
sudo iptables -t nat -I PREROUTING -p tcp --dport 8443 -j DNAT --to-destination 192.168.122.28:443
sudo iptables -I FORWARD -d 192.168.122.28 -p tcp --dport 443 -j ACCEPT
```

### 查看转发规则
```bash
sudo iptables -t nat -L PREROUTING -n -v
sudo iptables -L FORWARD -n -v
```

---

## 八、诊断脚本

### 快速检查 VM 和网络状态

```bash
cat > /tmp/check-ub24.sh <<'EOF'
#!/usr/bin/env bash
VM=0z7x696a
URI=qemu:///system

echo "=== VM list ==="
sudo virsh -c $URI list --all

echo -e "\n=== VM info ==="
sudo virsh -c $URI dominfo $VM

echo -e "\n=== VM interfaces ==="
sudo virsh -c $URI domiflist $VM

echo -e "\n=== Networks ==="
sudo virsh -c $URI net-list --all

echo -e "\n=== default network info ==="
sudo virsh -c $URI net-info default || true

echo -e "\n=== virbr0 addr ==="
ip addr show virbr0 2>/dev/null || true

echo -e "\n=== DHCP leases ==="
cat /var/lib/libvirt/dnsmasq/virbr0.status 2>/dev/null || \
cat /var/lib/misc/dnsmasq.leases 2>/dev/null || \
echo "No lease file found"
EOF

chmod +x /tmp/check-ub24.sh
/tmp/check-ub24.sh
```

---

## 九、常见问题

### Q: 为什么 fnOS 界面显示 "网络不存在"？

**A**: libvirt 后端正常，fnOS Web 界面层判断逻辑问题。cli 能看到 default 网络，但 fnOS 界面识别不了。

### Q: virbr0 状态 DOWN 怎么办？

**A**: 将 VM 网卡绑定到 default 网络后，virbr0 会自动变为 UP：
```bash
sudo virsh -c qemu:///system start 0z7x696a
```

### Q: 如何确认 VM 已获取 IP？

**A**:
```bash
cat /var/lib/libvirt/dnsmasq/virbr0.status
```

---

## 十、核心命令速查

最常用的三个命令：

```bash
# 编辑配置
sudo virsh -c qemu:///system edit 0z7x696a

# 启动 VM
sudo virsh -c qemu:///system start 0z7x696a

# 查看网卡
sudo virsh -c qemu:///system domiflist 0z7x696a
```

---

## 参考

- [libvirt 官方文档](https://libvirt.org/)
- [virsh 命令手册](https://libvirt.org/manpages/virsh.html)