commit 992ea4142e8769c71090dc5e0503fa02e163b9ad
Author: zly <zly@example.com>
Date:   Sun Mar 15 16:22:10 2026 +0800

    first commit: fnOS libvirt runbooks

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ce6a96d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,331 @@
+# 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)