You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
admin 4166c3002f Allow libvirt SSH capability setup under systemd 2 months ago
deploy Allow libvirt SSH capability setup under systemd 2 months ago
static Initial import of virsh panel 2 months ago
tests Initial import of virsh panel 2 months ago
virsh_panel Initial import of virsh panel 2 months ago
.gitignore Initial import of virsh panel 2 months ago
README.md Initial import of virsh panel 2 months ago
THIRD_PARTY_NOTICES.md Initial import of virsh panel 2 months ago
requirements-dev.txt Initial import of virsh panel 2 months ago
requirements.txt Initial import of virsh panel 2 months ago

README.md

VirtPilot:远端 virsh/libvirt 面板

项目只提供面板程序、Python 依赖清单和可选的 systemd service 文件,没有安装器或反向代理配置。面板运行在管理服务器 A,默认只监听 127.0.0.1:8000;AlmaLinux 10 的 virsh 宿主机 B 通过已有的 root SSH 密钥连接。B 不需要安装面板、创建新账号或导入新公钥。面板使用 libvirt 官方 SSH 连接方式管理 qemu:///system,VNC 经 SSH 连接 B 的本机端口。

目录与依赖

面板目录固定为 /home/virsh-panel。代码、静态资源、.venv/ 和启动后自动创建的 data/ 都在这个目录下;不会把面板数据放到 /var。直接从命令行运行时,无需复制任何文件到其他目录。不要把 /home/virsh-panel 当作 Web 静态目录对外提供,尤其不能暴露 data/ 中的私钥。

管理服务器 A 需要 Python 3、pip、Python 的 libvirt 绑定和 OpenSSH 客户端(包含 ssh、ssh-keyscan、ssh-keygen、ssh-agent、ssh-add)。如果 A 也是 AlmaLinux 10,对应 RPM 是 python3、python3-pip、python3-libvirt、openssh-clients;Python 依赖是 requirements.txt 中的 FastAPI、Uvicorn(含 WebSocket 支持)、Pydantic、用于生成 cloud-init 配置盘的 pycdlib,以及用于生成 Linux root 密码哈希的 Passlib。static/vendor/ 已包含浏览器 VNC 前端,无需 npm。请自行安装这些依赖;面板没有安装器。

宿主机 B 需已有正常工作的 SSH 服务、/usr/bin/virsh、libvirt/QEMU 服务,以及 root 账号已授权的公钥。libvirt 的 SSH 传输优先使用宿主机上的原生代理,不可用时可能回退到 nc;若网页测试提示 libvirt 连接失败,可检查 B 是否有 virt-ssh-helper 或兼容 nc -U 的工具。libvirt 传输参数说明。

启动

把整个项目放到 /home/virsh-panel,保持代码和虚拟环境仅 root 可修改。创建 .venv 时务必使用 --system-site-packages,让虚拟环境可以读取系统安装的 python3-libvirt;不要把 FastAPI 等依赖装到系统 Python。以下命令在 A 上执行,软件安装本身由你完成:

cd /home/virsh-panel
python3 -m venv --system-site-packages .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -c 'import libvirt; print("libvirt Python 绑定可用")'
PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -m uvicorn virsh_panel.app:create_app --factory --host 127.0.0.1 --port 8000 --workers 1 --proxy-headers --forwarded-allow-ips 127.0.0.1

上述命令保持在前台运行。出现 Uvicorn running on http://127.0.0.1:8000 表示已监听;可另开终端运行 curl http://127.0.0.1:8000/api/v1/health 检查。首次启动时,在启动终端输出中查找 VIRSH_PANEL_SETUP_TOKEN=,用它在网页创建管理员;令牌使用后失效,重启不会重新生成。停止面板用 Ctrl+C,再次启动只需执行最后一行启动命令。不需要编辑面板配置文件,也不需要运行初始化命令。

更新版本时请同时替换 static/index.html、static/app.js、static/styles.css 和后端代码,不要只上传页面 HTML;保留原有 data/。浏览器若出现“已选公网云镜像却仍要求 ISO”,先确认这三个静态文件均为同一版本,再重新打开页面。

若初始化令牌意外公开、且尚未创建管理员,请先停止面板,只删除 /home/virsh-panel/data/setup-token,再启动面板生成新令牌。不要删除整个 data/ 或管理员状态文件 state.json;新令牌不要再次公开。

按当前需求从 A 的 root 终端运行面板;程序自动将 data/ 目录和保存的私钥分别限制为 0700、0600。root 面板一旦被攻破,攻击者仍可能取得 B 的 root SSH 私钥;只在可信网络和 HTTPS 反代后使用,妥善限制谁能访问 A。A 若启用 SELinux enforcing,还需在真实系统上验证 /home/virsh-panel 的访问标签。仓库保留可选 service 文件,但以上启动方式不依赖它。

你自行配置的反向代理

反代与面板在 A 上时,上游指向 http://127.0.0.1:8000。对外必须使用你信任的 HTTPS 证书;保留原始 Host,由反代覆盖 X-Forwarded-Proto: https 和真实客户端的 X-Forwarded-For,并透传 /api/v1/vms/{uuid}/console 的 WebSocket。面板需要位于站点根路径 /。面板只信任来自 127.0.0.1 的代理头;直连明文 8000 仅允许 /api/v1/health 健康检查,不能登录或上传私钥。不要向公网暴露 8000。Uvicorn 官方代理说明。

首次网页操作

  1. 通过你的 HTTPS 域名打开面板,使用启动终端输出中的一次性令牌创建管理员。
  2. 在网页填写 B 的 IP/DNS、SSH 端口、现有的 root 客户端 SSH 私钥、磁盘目录、ISO 目录和网络名称。私钥必须与 B 的 root 账号已经授权的公钥匹配;仅有 root 密码或 B 的 SSH 主机密钥不能代替它。加密私钥还需填写其口令。口令只在当前面板进程的内存中用于解锁,不写入配置、磁盘或浏览器存储;面板重启后,登录网页并在“解锁宿主机 SSH 私钥”页面重新输入。
  3. 点击“扫描主机指纹”,再通过 B 的可信控制台运行 ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub 独立核对;确认后在网页测试、保存。保存前会重扫并测试 SSH 与 libvirt API,失败不会覆盖现有连接。

磁盘目录和 ISO 目录填写的是 B 宿主机上已存在的绝对路径,例如 /home/kvm、/home/iso,不是 A 面板服务器的路径;不需要提前手动创建 libvirt 存储池。点击“保存”时,面板会将这些现有目录定义为 libvirt dir 存储池并启动,作为内部管理机制;不会创建目录,也不会移动或删除现有文件。新建虚拟机的磁盘文件使用配置的磁盘目录下的 <虚拟机名>.qcow2,安装镜像使用配置的 ISO 目录下所选的 .iso;虚拟机 XML 通过绝对文件路径引用它们。“测试连接”不会修改宿主机,因此此时若目录尚未注册为池,可能仅显示资源警告。也可继续填写已有的 libvirt 存储池名称。若 B 的目录权限或 SELinux 策略阻止 libvirt 访问,保存会给出错误,需在 B 上修正权限或标签。

“默认虚拟网络或网桥”填写已有 libvirt 虚拟网络名称(如 default);若要使用 B 上已有的 Linux 网桥 br0,请填写 bridge:br0。单独填写 br0 表示名为 br0 的 libvirt 虚拟网络,不表示网桥。面板不会创建网桥;桥接网络的 IP、DHCP 与防火墙由你在 B 上配置。创建 VM 时,面板自动按 vCPU 数设置 virtio 网卡队列,例如 8 vCPU 对应 driver.queues=8;按 RHEL 10 建议最多设 16 队列。

面板设置 API 不回显 root 私钥或口令。B 无需对公网开放 VNC 或明文 libvirt TCP 端口;面板创建的虚拟机 VNC 仅监听 B 的 127.0.0.1。创建新虚拟机需 B 已有可用的目录或存储池、虚拟网络或 Linux 网桥、以及包含 ISO 的目录或池;资源暂时缺失不妨碍保存宿主机连接,但创建虚拟机会提示问题。

若某台现有 VM 是用 --graphics vnc,listen=0.0.0.0 创建的,它会出现在列表,但面板出于安全考虑不会连接其公开监听的 VNC。需在 B 上把该 VM 的 VNC 监听改为 127.0.0.1 后再使用面板控制台。面板新建 VM 的 XML 使用 host-passthrough CPU、Q35 机型与 UEFI(启用 ACPI/APIC)、磁盘 cache=none 和 discard=unmap、按 vCPU 数设置 virtio 网卡队列,并加入 QEMU Guest Agent 通道和 virtio 内存气球空闲页回报。首次安装时临时挂载 ISO 并从光驱启动;保存的配置已弹出 ISO,后续仅从硬盘启动。B 需要有可用的 UEFI/OVMF 固件,客户机内还需安装并运行 qemu-guest-agent 才能使用 Guest Agent 功能。VNC 仍仅监听 B 的 127.0.0.1,现有 VM 配置不会被面板自动改写。

安装程序首次请求重启时,安装阶段的 VM 会先停机;请在面板点击“开机”,它会使用已弹出 ISO 的持久配置从硬盘继续启动。首次重启若发生在多阶段安装的中途,也按此方式继续。这个行为只适用于更新后新创建的 VM;此前已创建的 VM 不会自动改写,可在宿主机手动弹出 ISO 并把硬盘设为首选启动设备。若网页 VNC 显示“连接已中断”,这与虚拟机的 UEFI/磁盘 XML 是不同链路:先在浏览器开发者工具的 Network → WS 检查控制台请求是否得到 101。若 Uvicorn 日志显示对 /console 的普通 GET 返回 404,先检查面板虚拟环境是否安装了 WebSocket 协议依赖(旧版依赖清单可能遗漏),重新运行 .venv/bin/python -m pip install -r requirements.txt;若已安装,则检查反代是否用 HTTP/1.1 透传 Upgrade 和 Connection 头。确认 WebSocket 已连接后,再从 A 测试已保存 SSH 配置能否用 ssh -W 127.0.0.1:<实际 VNC 端口> 连到 B;不要为排障把 VNC 改成公网监听。

公网云镜像模板创建(无需手动安装)

面板的“创建虚拟机”现在有独立的“公网云镜像”方式。先在宿主机设置中选择已工作的 Linux 网桥,例如 bridge:br0;打开创建弹窗的“导入新的云镜像模板”,填写 AlmaLinux 10 官方 Generic Cloud qcow2 镜像在 https://repo.almalinux.org/almalinux/10/cloud/x86_64/images/ 下的下载地址、发布方 SHA-256 和模板显示名。地址必须是官方 HTTPS 直链,面板不会跟随重定向。面板服务器 A 需要能访问该地址。导入在后台运行,一次只允许一个任务,面板下载、校验 SHA-256 后通过当前 libvirt SSH 连接把模板镜像上传到 B 的磁盘池;无需登录 B 手工复制。模板记录保存在项目内的私有 data/templates.json,绑定当前宿主机身份和磁盘池。不要在导入期间关闭面板进程;若进程异常退出,任务记录不会恢复,可能需要检查项目 data/ 中的 .cloud-image-* 临时文件和 B 磁盘池中 panel-template-* 卷,不要未经核对就删除。

选择模板后,填写 VM 资源、已分配给你的具体公网 IPv4/CIDR(如实际公网地址加 /24 或 /28)、同网段网关、1–4 个公网 DNS 地址,再选择一种 root 登录方式:填写 OpenSSH 公钥时,只能用对应私钥登录 root@<公网IP>,密码输入会隐藏;不填公钥时,必须设置 12–128 字符的初始 root 密码,可用它从 VNC 和 SSH 登录。客体登录密钥与连接宿主机的 root 私钥是两套独立凭据。面板会校验公网地址、网络/广播地址、网关和已由面板分配的重复 IP;它无法检测面板外设备的 IP 占用,也无法替服务商分配或路由公网 IP。当前版本只支持网关与 VM IP 同一子网的桥接 IPv4;服务商给出 /32 或异网段网关时不要强填,需另做路由网络模式。上游网络还必须允许 VM 使用额外 MAC,br0 本身不能保证公网可达。

创建时,面板在 B 的磁盘池克隆独立 qcow2 磁盘并扩容,生成一个只读、不可启动的 CIDATA cloud-init 配置 ISO,经 libvirt 上传后挂载。客体首次直接从硬盘开机,cloud-init 按固定 MAC 配置静态公网 IP、默认网关和 DNS;不会进入 VNC 安装程序。AlmaLinux 本地云镜像用法、NoCloud 配置说明。有公钥时,面板将其写入 root 的授权密钥并禁用 SSH 密码登录,root 密码保持锁定(VNC 密码登录也不可用);无公钥时,面板只把加盐的 SHA-512-crypt 密码哈希写入配置 ISO,不在面板数据中保存明文,并开启 root 的 SSH 密码登录。密码模式会暴露公网 root 密码认证,建议优先使用公钥及限制 SSH 来源;宿主机上的配置 ISO 仍含密码哈希,必须防止未授权读取。网络或凭据填错后需离线修复或重建。删除 VM 时若勾选“同时删除虚拟磁盘”,面板也会删除其配置 ISO,但保留共享模板镜像。这项登录方式变更只对新创建的 VM 生效,不会修改已有 VM。

面板创建的公网云镜像 VM 在列表中有“重装”按钮。点击后选择当前宿主机已导入的云镜像模板,输入 VM 名称确认;可填写新的 root SSH 公钥或 12–128 字符的初始 root 密码,二者均不填时会生成强密码。自动生成的密码仅保存在面板进程内存中,在任务成功后显示;管理员点击“已保存密码,完成”后,面板才会清除它,之后无法再次查看。同一浏览器标签页刷新后可凭非机密任务编号恢复查询,但面板进程重启后密码无法找回,请及时保存。重装自动读取原配置盘中的公网 IP/CIDR、网关、DNS 和 MAC,不要求再次手填网络。运行中的 VM 会先收到正常关机请求;120 秒内未关机则中止,不会强制断电,也不会切换或删除旧系统盘。面板会将所选模板克隆到新系统盘,生成新的 cloud-init 配置盘并启动 VM;新系统尚未启动时切换失败会恢复原定义,旧盘保留。如果启动调用结果不确定但发现新盘已在运行,则保留新旧两份磁盘并提示人工核查。libvirt 报告新 VM 已启动后,面板会自动删除旧系统盘与旧配置盘;这并不能证明客体系统、网络或 SSH 已工作,旧数据一旦删除不可恢复。 若旧盘清理失败,任务仍返回成功但附带警告,需在宿主机核查残留卷。此功能仅支持面板创建且配置未被外部修改的公网云镜像 VM,不支持 ISO 安装 VM、快照或多网卡/多磁盘 VM。

功能范围:虚拟机列表、从 ISO 创建、导入 AlmaLinux 10 云镜像模板并配置公网静态 IP 创建、云镜像重装、开机、关机、重启、强制断电/重置、删除和浏览器 VNC。当前为单管理员、单宿主机版本;不提供 ISO 上传、目录自动创建、虚拟网络创建、内网 IP 模板、异网段网关或多用户权限。真实 AlmaLinux 10 宿主机仍需现场联调。