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.
virt/README.md

130 lines
34 KiB
Markdown

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# VirtPilot:远端 virsh/libvirt 面板
项目提供面板程序、Python 依赖清单和可选的 [systemd service 文件](deploy/virsh-panel.service),没有安装器或反向代理配置。面板运行在管理服务器 A,默认只监听 `127.0.0.1:8000`;AlmaLinux 10 的 virsh 宿主机 B 通过已有的 root SSH 密钥连接。B 不需要安装面板、创建新账号或导入新公钥。面板使用 [libvirt 官方 SSH 连接方式](https://www.libvirt.org/uri.html)管理 `qemu:///system`,VNC 经 SSH 连接 B 的本机端口。
这一版的持久化面板数据使用 **MariaDB**。首次打开网页会先配置数据库连接、创建初始账户;初始账户可不填写邮箱,由你随后在 MariaDB 手动补齐。之后所有用户**只能使用邮箱和密码登录**,用户名仅用于显示、注册和数据库管理,不能作为登录凭据。初始账户的 `admin` 字段初始为 `0`,需由你手工在数据库升为管理员,之后才能在网页配置宿主机和 SMTP。数据库及有建表权限的专用账号需要你事先准备;面板不会安装 MariaDB 或自动创建数据库。旧版 `data/state.json`、`data/templates.json` 和本地宿主机配置**不会自动迁移**。虚拟机定义和虚拟磁盘仍由远端 libvirt/宿主机持有,数据库保存用户、邮箱验证码、虚拟机归属、登录会话、SMTP 设置、模板目录、宿主机连接资料、更新设置、更新任务及虚拟机性能历史等面板数据。
如果是在旧测试目录上替换代码,旧 `data/generations/` 中的明文 SSH 私钥不会被新版使用,也**不会自动删除**。为避免遗留敏感文件,建议先备份并核对后,在首次运行新版前使用全新的 `data/` 目录;不要未经核对直接删除仍需使用的资料。
## 目录与依赖
面板目录固定为 `/home/virsh-panel`。代码、静态资源、`.venv/` 和启动后自动创建的 `data/` 都在这个目录下;**不会把持久面板业务数据放到 `/var`**。本地 `data/` 的持久敏感文件仅有连接 MariaDB 所必需的加密引导配置、0600 主密钥和初始化阶段的令牌;还会有锁文件及不含密钥的 SSH 运行包装器。主密钥与数据库备份须分别安全保管;只有数据库而丢失主密钥,已加密的宿主机资料及更新令牌将无法恢复。不要把 `/home/virsh-panel` 当作 Web 静态目录对外提供。
管理服务器 A 需要 Python 3、`pip`、Python 的 libvirt 绑定和 OpenSSH 客户端(包含 `ssh`、`ssh-keyscan`、`ssh-keygen`、`ssh-agent`、`ssh-add`),另需 MariaDB 数据库。如果 A 也是 AlmaLinux 10,对应 RPM 是 `python3`、`python3-pip`、`python3-libvirt`、`openssh-clients`;Python 依赖在 `requirements.txt` 中,包括 FastAPI、Uvicorn、Pydantic、pycdlib、Passlib、PyMySQL 和 cryptography。`static/vendor/` 已包含浏览器 VNC 前端,无需 npm。请自行安装这些依赖;面板没有安装器。
宿主机 B 需已有正常工作的 SSH 服务、`/usr/bin/virsh`、libvirt/QEMU 服务,以及 root 账号已授权的公钥。libvirt 的 SSH 传输优先使用宿主机上的原生代理,不可用时可能回退到 `nc`;若网页测试提示 libvirt 连接失败,可检查 B 是否有 `virt-ssh-helper` 或兼容 `nc -U` 的工具。[libvirt 传输参数说明](https://www.libvirt.org/uri.html)。
## 启动
把整个项目放到 `/home/virsh-panel`,保持代码和虚拟环境仅 root 可修改。创建 `.venv` 时务必使用 `--system-site-packages`,让虚拟环境可以读取系统安装的 `python3-libvirt`;不要把 FastAPI 等依赖装到系统 Python。以下命令在 A 上执行,软件安装本身由你完成:
```bash
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”,先确认这三个静态文件均为同一版本,再重新打开页面。网页一键更新另有 Git 仓库和更新服务的要求,见下文。
从仍允许用户名登录的版本升级时,**先检查初始账户的邮箱再替换代码并重启**。旧版可能创建了 `email=NULL` 的初始账户;新版首次创建的账户也可以不填邮箱。这种账户创建后会建立当前浏览器会话,但一旦退出、会话过期或清除 Cookie,在数据库补齐邮箱前就无法再次登录。请先备份数据库,在 MariaDB 中查询并确认准确的账户 ID 与用户名,再将示例邮箱换成你自己的、尚未被其他用户占用的真实邮箱:
```sql
SELECT id, username, email FROM users;
UPDATE users SET email = LOWER('你的邮箱@example.com'), email_verified = 1
WHERE id = 1 AND username = '你的初始用户名' AND email IS NULL;
SELECT id, username, email FROM users WHERE id = 1;
```
请确认 `UPDATE` 实际影响一行,且查询结果是预期邮箱;否则不要继续升级、退出当前会话或重启,应核对 ID、用户名及已有邮箱。初始账户的邮箱由持有初始化令牌的你设置,不通过公开注册验证码流程。已设置邮箱的现有账户无需再改,升级后直接用其邮箱登录;邮箱不区分大小写。
若初始化令牌意外公开、且尚未创建初始账户,请先停止面板,只删除 `/home/virsh-panel/data/setup-token`,再启动面板生成新令牌。不要删除整个 `data/`;新令牌不要再次公开。
按当前需求从 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 官方代理说明](https://www.uvicorn.org/deployment/)。
## 首次网页操作
1. 通过你的 HTTPS 域名打开面板,使用启动终端输出中的一次性令牌填写 MariaDB 的地址、端口、已有数据库名、专用账号和密码。数据库账号至少需要在该数据库中建表及读写权限;连接失败时不会保存配置。当前数据库连接尚未提供 TLS 参数,数据库请放在面板本机或可信内网,不要将其端口暴露公网。
2. 使用同一个令牌填写用户名和密码,创建初始账户;此处不要求填写邮箱。密码只保存为密码哈希。此时 `users.admin=0`,账户已建立当前浏览器会话,但还不能管理宿主机。按照你的要求,面板**不会自动赋予管理员权限**。用有权访问该数据库的账号在 MariaDB 中核对用户名及 ID 后,手工执行下面 SQL;将示例 ID、用户名和邮箱换成实际值。**必须在退出当前会话前补齐邮箱**,否则无法再次登录:
```sql
SELECT id, username, email, admin, approved FROM users;
UPDATE users SET email = LOWER('你的邮箱@example.com'), email_verified = 1
WHERE id = 1 AND username = '你的初始用户名' AND email IS NULL;
UPDATE users SET admin = 1 WHERE id = 1 AND username = '你的初始用户名';
SELECT id, username, email, admin, approved FROM users WHERE id = 1;
```
核对查询结果中的邮箱和管理员标志后,再刷新面板;权限会从数据库即时读取,不必重启。此后用邮箱登录,不能用用户名登录。不要把 `admin=1` 给公开注册用户。
3. 管理员在网页配置 SMTP 地址、端口、SSL/STARTTLS、发件邮箱及需要时的 SMTP 账号密码;设置加密保存在 MariaDB,页面不回显密码。完成后,访客可用邮箱验证码注册(10 分钟有效,重复发送与输错次数受限);邮箱验证成功即可登录,但须由管理员在“用户审核”批准后才能创建虚拟机。普通用户不能添加宿主机、导入云镜像模板、配置 SMTP 或更新面板,也看不到其他人的虚拟机和初始密码。面板外创建或管理员创建的未归属虚拟机仅管理员可见;当前没有从网页将旧 VM 分配给用户的功能。
4. 在网页填写 B 的 IP/DNS、SSH 端口、虚拟机地区、现有的 **root 客户端 SSH 私钥**、磁盘目录、安装 ISO 目录、独立救援 ISO 目录和网络名称。救援目录可暂留空,但配置前不能上传救援模版;它不能与安装 ISO 目录相同。还可配置由服务商分配且已路由到该宿主机的**公网 IPv4 `/24` 地址池**、同网段网关、DNS,以及不能分配给虚拟机的保留地址。地区是这台宿主机上虚拟机共用的展示标签,可留空;它不影响 SSH 连接或已导入的模板。私钥必须与 B 的 root 账号**已经授权的公钥**匹配;仅有 root 密码或 B 的 SSH 主机密钥不能代替它。加密私钥还需填写其口令。保存宿主机设置时,面板会将口令与私钥加密写入 MariaDB,以便面板重启后自动连接和无人登录时继续采样;设置 API 不回显口令,面板代码也不将其写入浏览器存储。**旧版本中只在内存解锁过的口令无法自动恢复**:升级后进入“宿主机设置”,不必重新粘贴原私钥,填写原口令并重新保存一次。只在“解锁宿主机 SSH 私钥”页面输入不会持久保存。
5. 点击“扫描主机指纹”,再通过 B 的可信控制台运行 `ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub` 独立核对;确认后在网页测试、保存。保存前会重扫并测试 SSH 与 libvirt API,失败不会覆盖现有连接。
宿主机私钥、已填写的私钥口令和配置加密保存在 MariaDB。数据库备份与 `data/master.key` 同时泄露时,这些凭据可以被解密,因此须分别严密保护;运行中的 root 面板进程同样能使用它们。OpenSSH 连接时需要读取私钥文件,Linux 上面板会将其临时还原到权限为 `0700` 的 `/dev/shm` 内存文件系统目录;面板关闭时清除。`data/runtime-wrappers/` 只包含不带密钥的启动包装器。若 SSH agent 异常退出,后台采样会限频尝试使用已保存口令恢复连接;若保存的口令错误,仍需管理员检查并重新保存。面板仅支持单个 Uvicorn worker。
虚拟机列表只展示状态、地区、系统或安装镜像、IP、规格和磁盘;点击虚拟机名称进入该机管理页,控制台、电源、重装和删除等操作都在管理页。“创建虚拟机”从列表进入独立页面,“重装系统”从虚拟机详情进入独立页面,表单和任务进度不再使用弹窗。地区取自当前宿主机设置。新建或重装的云镜像 VM 会记录所选模板名称及配置的公网 IP/CIDR;这个 IP 是**配置记录**,不是连通性探测。详情页的公网 IP 不显示 `/24` 等掩码后缀,可点击旁边的按钮复制;磁盘信息只显示总容量,不再显示磁盘块数。ISO 安装 VM 只记录安装镜像文件名,不能据此确认客体最终安装的系统;旧 VM 或面板外创建的 VM 若无可靠记录,会显示“未识别”或“未获取”,不会猜测客体系统与 IP。
云镜像 VM 的详情页显示 SSH 登录名 `root`。面板保存了初始 root 密码时,默认以星号遮盖;管理员或该 VM 的所属用户可按需点击图标查看、复制,不会在虚拟机列表或普通详情数据中直接返回密码。新建云镜像 VM 无论是否选择 SSH 公钥,都会设置并加密保存可查看的初始密码;重装时若只选公钥而不填写密码,则保持仅公钥登录,不保存新密码。ISO 安装和面板外创建的 VM 的客体密码不由面板管理。旧 VM 曾使用但面板未保存的密码无法从密码哈希或虚拟机系统中还原。客体内修改 root 密码后,详情页保存的**初始**密码不会自动更新,可能已无法用于登录;请妥善保护数据库备份和面板主密钥。
虚拟机详情页显示 CPU、客体内存、磁盘 I/O 和网络收发四张历史走势图,可切换最近 1 小时、24 小时、7 天和 30 天。面板后台定时从 [libvirt 域统计](https://libvirt.org/manpages/virsh.html#domstats)采样并写入 MariaDB,即使无人登录也会继续记录,前提是宿主机连接可用且加密私钥能自动解锁。旧配置若只在内存中解锁、没有重新保存口令,重启后后台采样会暂停,直到管理员解锁;按上述步骤保存口令后可避免这种中断。查询**只返回最近 30 天**的数据;运行中的面板会分批清理更早的数据库记录。面板停机或数据库不可用时物理清理会暂停,恢复后继续追赶,因此中断期间数据库中可能暂时留有超期记录。CPU 是按 vCPU 数归一化、最高显示 100% 的使用率,磁盘和网络显示每秒速率而不是累计量或网络带宽上限;网络收发方向以虚拟机为准。磁盘与网卡只汇总 libvirt 实际提供计数的设备,未提供计数的设备无法纳入统计。内存占用依赖客体内存气球统计,客户机不提供或统计过期时会显示无数据,不会把宿主机 QEMU 进程占用误当客体内存。初次采样、虚拟机停机、面板/宿主机不可达或计数器重置期间可能出现空白;面板停机期间不会补录历史。较长时间范围会聚合采样,短暂的停机或采样缺口可能不明显。
磁盘目录、安装 ISO 目录和救援 ISO 目录填写的是 **B 宿主机**上已存在的绝对路径,例如 `/home/kvm`、`/home/iso` 和 `/home/rescue-iso`,不是 A 面板服务器的路径;不需要提前手动创建 libvirt 存储池。救援目录须实际独立,不要通过软链接或绑定挂载指向安装 ISO 目录。点击“保存”时,面板会将这些现有目录定义为 libvirt `dir` 存储池并启动,作为内部管理机制;不会创建目录,也不会移动或删除现有文件。新建虚拟机的磁盘文件使用配置的磁盘目录下的 `<虚拟机名>.qcow2`,安装镜像使用配置的安装 ISO 目录下所选的 `.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 并把硬盘设为首选启动设备。此后新建的 ISO 和云镜像 VM 都会自动开启 libvirt 的**随宿主机开机自启**;现有 VM 的设置不会批量改动。开机自启只在宿主机启动时生效,不会让安装程序首次重启后的停机自动恢复。如果 ISO 安装尚未完成时宿主机重启,VM 可能从尚未安装完成的硬盘启动,建议初次安装期间避免重启宿主机。若网页 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 改成公网监听。
## 公网云镜像模板创建(无需手动安装)
面板随项目预存 AlmaLinux、Debian、CentOS 和 Ubuntu 的官方图标,页面运行时不会从外网加载图标;来源与使用说明见 [ICON-SOURCES.md](ICON-SOURCES.md)。图标仅用于识别真实的系统模板,不表示发行版项目认可本面板。当前后端仍只允许导入 AlmaLinux 9/10 镜像,预存其他图标并未开放相应系统的导入或销售。
面板的“创建虚拟机”有独立的“公网云镜像”方式。先在宿主机设置中选择已工作的 Linux 网桥,例如 `bridge:br0`。只有管理员可进入侧栏的“云镜像模板”页面,填写 [AlmaLinux 官方 Generic Cloud qcow2 镜像](https://wiki.almalinux.org/cloud/Generic-cloud)在 `https://repo.almalinux.org/almalinux/9/cloud/x86_64/images/` 或 `https://repo.almalinux.org/almalinux/10/cloud/x86_64/images/` 下的下载地址、发布方 SHA-256 和模板显示名;已保存的显示名也可在该页修改。地址必须是官方 HTTPS 直链,面板不会跟随重定向。面板服务器 A 需要能访问该地址。导入在后台运行,一次只允许一个任务,面板下载、校验 SHA-256 后通过当前 libvirt SSH 连接把模板镜像上传到 B 的磁盘池;无需登录 B 手工复制。模板目录记录加密保存在 MariaDB,绑定当前宿主机身份和磁盘池。改名不会改动镜像文件、模板 ID 或已经创建的虚拟机的系统名称记录,只影响后续创建和重装时的显示。普通用户只能在创建或重装页面从已导入的镜像卡片中选择具体版本,不能导入或改名。不要在导入期间关闭面板进程;若进程异常退出,运行中的导入任务记录不会恢复,可能需要检查项目 `data/` 中的 `.cloud-image-*` 临时文件和 B 磁盘池中 `panel-template-*` 卷,不要未经核对就删除。
选择镜像卡片并展开版本后,填写 VM 资源和 root 登录方式。宿主机公网地址池支持实际获配的 `/24` 至 `/30` 前缀。例如服务商分配 `123.123.123.112/28`、宿主机网关为 `123.123.123.113` 时,在宿主机设置填写该 `/28` 网段(填写 `123.123.123.113/28` 也会规范化为 `123.123.123.112/28`),网关填 `123.123.123.113`,DNS 按服务商要求填写。自动分配只考虑此 `/28` 的有效主机地址;扣除网关后是 `123.123.123.114` 至 `123.123.123.126`,还会跳过保留、已用及池内 DNS 地址。**不要填写 `123.123.123.114/24` 或 `123.123.123.0/24`,除非服务商确实分配了整个 `/24`。**设置页会预览输入前缀换算出的实际网段和主机地址范围。
“虚拟机网卡前缀”与可分配地址池是独立设置:留空时客体使用地址池前缀;如果现场确认服务商要求 VM 内配置 `/24`,而实际只获配上述 `/28`,这里填 `24`,新建 VM 将获得例如 `123.123.123.114/24`,但面板仍只会从 `123.123.123.112/28` 挑选地址。可填写的客体前缀范围为 `/24` 到地址池前缀,以确保整个地址池中的 IP 与网关处于同一客体子网。修改此项不会自动改写已创建 VM;云镜像重装会保留该 VM 首次创建时的网络前缀。若使用 `/28` 不通,其具体原因仍需结合宿主机路由、网桥及服务商网络确认;仅改变面板掩码无法替代上游放行或路由配置。
配置地址池后,创建时会自动选择一个尚未使用的地址,并沿用宿主机设置的网关和 DNS;用户不能在创建请求中另填 IP、网关或 DNS 来绕过地址池。面板会跳过网络地址、广播地址、网关、保留地址、宿主机自身的字面 IPv4,以及 libvirt 可见虚拟机元数据中的已用 IP,并防止面板并发创建分到相同地址。地址池用尽时创建会报错,不会复用仍占用的地址;面板删除 VM 后会释放其地址占用记录。旧宿主机若未配置地址池,仍可按原方式手填已分配给你的**具体公网 IPv4/CIDR**(如 `/24` 或 `/28`)、同网段网关和 1–4 个 DNS 地址。在创建页面中可选一个已保存的 SSH 公钥,同时设置初始 root 密码,登录时可用对应私钥或密码;不选择公钥也可以只用密码。手动密码须为 12–128 个字符,包含大写字母、小写字母和符号;密码留空时面板自动生成并加密保存初始密码,**即使已经选择公钥**。客体登录密钥与连接宿主机的 root 私钥是两套独立凭据。面板无法探测面板及 libvirt 元数据之外的设备是否占用地址,也无法替服务商分配或路由公网 IP。当前版本只支持网关与 VM IP 同一子网的桥接 IPv4;服务商给出 `/32` 或异网段网关时不要强填,需另做路由网络模式。上游网络还必须允许 VM 使用额外 MAC,`br0` 本身不能保证公网可达。
若 DNS 本身位于该地址池中,它的地址也会自动跳过。面板创建成功后会保留 IP 占用记录,只有通过面板删除 VM 才自动释放;如果直接在宿主机或其他工具中删除 VM,旧占用记录会保守保留,避免误将该 IP 分给新 VM,需核查真实占用情况后再处理。
每个已登录用户都可导入并命名自己的**单行 OpenSSH 公钥**:已审核账号从侧栏“公钥管理”进入,等待审核的账号可用“管理我的公钥”入口。可以粘贴 `.pub` 文件内容,或在浏览器选择本地 `.pub` 文件填入表单;面板只接受公钥,不要选择或粘贴私钥。公钥管理列表只显示当前账户导入的公钥;管理员账户也不能把另一个用户的公钥当作自己的预设公钥使用。创建与重装公网云镜像 VM 时,SSH 公钥以卡片形式选择,卡片只显示公钥名称,不显示公钥内容或指纹;再次点击已选卡片可取消选择,不再有手动粘贴公钥输入框。初始 root 密码输入框始终显示,可与公钥同时使用;创建时密码留空总会自动生成,重装时只有公钥和密码都留空才自动生成。未通过管理员审核的用户可以管理自己的公钥,但仍不能创建虚拟机。删除公钥只删除面板中的预设记录,**不会撤销已经写入现有虚拟机的 SSH 授权密钥**;要撤销现有 VM 的访问权限,需在客体系统中删除对应的 `authorized_keys` 条目或重装并更换登录密钥。
创建时,面板在 B 的磁盘池克隆独立 qcow2 磁盘并扩容,生成一个只读、不可启动的 `CIDATA` cloud-init 配置 ISO,经 libvirt 上传后挂载。客体首次直接从硬盘开机,cloud-init 按固定 MAC 配置静态公网 IP、默认网关和 DNS;**不会进入 VNC 安装程序**。[AlmaLinux 本地云镜像用法](https://wiki.almalinux.org/cloud/Generic-cloud-on-local)、[NoCloud 配置说明](https://docs.cloud-init.io/en/latest/reference/datasources/nocloud.html)。选中公钥时,面板将其写入 root 的授权密钥;无论是否选公钥,创建时都会将初始 root 密码的加盐 SHA-512-crypt 哈希写入配置 ISO,并开启 root 的 SSH 密码登录,因此公钥和密码可以共存。自动生成或手填的初始密码还会在 MariaDB 中加密保存,供详情页按需查看或复制。启用密码登录会暴露公网 root 密码认证,建议在宿主机或上游防火墙限制 SSH 来源;宿主机上的配置 ISO 含密码哈希,必须防止未授权读取。网络或凭据填错后需离线修复或重建。删除 VM 时若勾选“同时删除虚拟磁盘”,面板也会删除其配置 ISO,但**保留共享模板镜像**。这项登录方式变更只对新创建的 VM 生效,不会修改已有 VM。
面板创建的公网云镜像 VM 在详情页有“重装”按钮。点击后选择当前宿主机已导入的云镜像模板,输入 VM 名称确认;可在卡片中选择自己保存的 SSH 公钥,并同时设置初始 root 密码。手动密码须为 12–128 个字符并包含大写字母、小写字母及符号;只选公钥而不填写密码时保持仅公钥登录,两者都留空时自动生成强密码。设置或生成的初始密码会在成功重装后加密保存至 MariaDB,并可在虚拟机详情页按需查看或复制。自动生成的密码仍会在任务成功后显示,管理员点击“已保存密码,完成”只会从**任务记录**中清除密码,不影响详情页保存的初始密码。同一浏览器标签页刷新或面板进程重启后仍可按任务编号查询,直到确认保存密码为止。重装自动读取原配置盘中的公网 IP/CIDR、网关、DNS 和 MAC,不要求再次手填网络。运行中的 VM 会先收到正常关机请求;120 秒内未关机则中止,不会强制断电,也不会切换或删除旧系统盘。面板会将所选模板克隆到新系统盘,生成新的 cloud-init 配置盘并启动 VM;新系统尚未启动时切换失败会恢复原定义,旧盘保留。如果启动调用结果不确定但发现新盘已在运行,则保留新旧两份磁盘并提示人工核查。**libvirt 报告新 VM 已启动后,面板会自动删除旧系统盘与旧配置盘;这并不能证明客体系统、网络或 SSH 已工作,旧数据一旦删除不可恢复。** 若旧盘清理失败,任务仍返回成功但附带警告,需在宿主机核查残留卷。此功能仅支持面板创建且配置未被外部修改的公网云镜像 VM,不支持 ISO 安装 VM、快照或多网卡/多磁盘 VM。
## 紧急救援 ISO
管理员先在“宿主机设置”填写已存在且不同于安装 ISO 目录的救援 ISO 目录,再从侧栏“救援模版”选择本地可启动的 ISO 并命名上传;面板将文件暂存于私有 `data/` 目录、验证 ISO 9660/El Torito 启动记录,再经现有 libvirt SSH 连接导入当前宿主机的**救援 ISO 池**。普通 ISO 安装列表只读取安装 ISO 池,不会显示救援池中的镜像;后端也拒绝把面板命名的救援卷当作安装 ISO。此验证不保证 ISO 包含适用于目标 VM 的 UEFI/BIOS 启动项,也不保证救援系统能正常运行;切换后须用 VNC 核实。当前只支持 1 MiB–8 GiB 的 ISO,不支持 qcow2/raw 救援系统盘。ISO 文件保存在宿主机,模版元数据和恢复所需的虚拟机原始 XML 加密保存在 MariaDB;面板完成上传后会清理临时文件。若上传在面板进程被强制终止时中断,检查 `data/.rescue-upload-*` 临时文件和宿主机救援目录中的 `panel-rescue-*.iso` 卷,再决定是否清理。反向代理也必须允许相应请求体大小与上传时间,面板服务器暂存盘须有足够空间。升级前上传到旧安装 ISO 目录的救援镜像不会自动迁移到新目录;配置救援目录后请重新上传需要的模版,核对无人使用后再清理旧文件。
已审核的虚拟机所有者或管理员可在虚拟机详情页点“紧急救援”,选择已上传的 ISO 并输入虚拟机名称确认。面板**先预挂载救援 ISO,保存为下次完整开机的启动配置**,再请求运行中的 VM 正常关机(最多等待 120 秒)并从救援 ISO 冷启动;停机 VM 会直接从该 ISO 开机。若正常关机请求失败或超时,预挂载仍保留,救援页会明确显示“已预挂载”,并提供需再次确认的“强制重启进入救援”按钮:它会强制断电再冷启动,可能丢失未保存的数据。面板**不会自动强制断电**。也可在详情页手动“强制断电”后“开机”;普通“强制重置”只重置原 QEMU 进程,不能可靠读取新保存的启动配置。救援 ISO 仅在卸载或取消救援后才会从启动配置移除。取消尚未启动的救援时,若原系统仍在运行则不会打断它;退出已启动的救援时,面板会正常关机、恢复原始启动配置并从系统盘开机。面板添加独立救援光驱,保留原系统盘、cloud-init 配置盘及原始启动 XML。救援期间不允许重装、删除或执行一般电源操作;VNC 控制台仍可使用。救援 ISO 内的用户名、密码与网络行为由 ISO 自身决定,面板不会把原 VM 的 root 密码或 SSH 公钥注入救援系统。任务成功仅表示 libvirt 报告虚拟机已启动,不保证救援系统或原系统已正常登录;应通过 VNC 核对。建议在救援前备份重要数据;面板不会修改原系统盘,但救援系统中的人工操作仍可修改或删除它。
## 网页一键更新
网页的“网站更新”页固定从 `https://g.luoli.live/root/virt.git` 的 `main` 分支读取更新。访问令牌请使用有此私有仓库**读取权限**的 Gitea `root` 账号令牌;网页保存后不会回显,令牌加密保存在 MariaDB,也不会写入 Git URL。面板会拒绝压缩包部署、分支不符、origin 不符、未提交/未跟踪改动以及不能快进的版本;Git 的 [`--ff-only`](https://git-scm.com/docs/git-merge#Documentation/git-merge.txt---ff-only) 会在提交历史分叉时拒绝覆盖本地代码。
一键更新必须将项目部署为 `/home/virsh-panel` 的完整 Git 检出目录(含 `.git`),并用 systemd 运行主面板。目录及 `.git` 必须归运行账号 root 所有,且不可允许组或其他用户写入;当前仅支持 `main` 分支、origin 精确为 `https://g.luoli.live/root/virt.git` 的干净检出。`git`、`pip` 和 `systemctl` 须可用。第一次启用时,手工将仓库中的两个 unit 文件安装到 systemd,再重载并启动主服务;更新服务本身无需 `enable`,由网页按需触发:
```bash
install -m 0644 /home/virsh-panel/deploy/virsh-panel.service /etc/systemd/system/virsh-panel.service
install -m 0644 /home/virsh-panel/deploy/virsh-panel-update.service /etc/systemd/system/virsh-panel-update.service
systemctl daemon-reload
systemctl enable --now virsh-panel.service
```
独立的 `virsh-panel-update.service` 会先拉取私有仓库并安装目标版本 Python 依赖,再以快进方式切换代码、重启主面板并检查本机 HTTP 与数据库健康状态。更新任务绑定点击“检查更新”时看到的两个提交编号;若本地或远端版本变化,任务会拒绝切换并要求重新检查。更新任务状态加密存于 MariaDB,页面中断后可继续查询;独立服务异常退出或超时会尝试将未完成任务标为失败。更新前请备份 **MariaDB 数据和 `data/master.key`、`data/database-config.json`**;更新失败时不要重复点按钮,应先看 `journalctl -u virsh-panel-update.service -n 100`。依赖在代码切换前安装到当前 `.venv`,因此若依赖安装成功而代码切换失败,可能需要人工检查依赖版本。更新服务会保留更新前的 Git 回滚引用,但不会自动执行覆盖性的回滚。网页更新不负责安装系统 RPM、替换 `/etc/systemd/system` 中已安装的 unit 或修改反向代理配置;这些变化如后续版本需要,仍需人工处理。由于在线更新会运行私有仓库中的代码与依赖,必须保护 Gitea 仓库写入权限和访问令牌。
功能范围:邮箱验证注册、管理员审核及按虚拟机归属隔离用户,虚拟机列表和详情页四项性能走势图、从 ISO 创建、由管理员导入并重命名 AlmaLinux 9/10 云镜像模板、使用已导入模板配置公网静态 IP 创建、云镜像重装、管理员上传救援 ISO 和虚拟机紧急救援、开机、关机、重启、强制断电/重置、删除和浏览器 VNC。当前仍是单宿主机版本;不提供普通安装 ISO 上传、目录自动创建、虚拟网络创建、内网 IP 模板或异网段网关。真实 AlmaLinux 10 宿主机、SMTP 服务及 MariaDB 仍需现场联调。