先连接数据库,
再开始管理。
+ 面板业务数据保存在 MariaDB 中。只需在首次启用时填写连接信息,无需预先编辑面板配置文件。
+连接 MariaDB
+请先准备可连接的数据库与账号。连接信息只提交给面板服务,不会保存在浏览器中。
+请先完成你自己的 HTTPS 反向代理,并核对证书和域名,再输入数据库密码与初始化令牌。
+ +数据库需由你预先创建并授权;面板不会自动安装 MariaDB。初始化令牌完成管理员创建后失效。
+diff --git a/README.md b/README.md index 77284140..3817afcd 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,16 @@ # 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 的本机端口。 +项目提供面板程序、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 或自动创建数据库。旧版 `data/state.json`、`data/templates.json` 和本地宿主机配置**不会自动迁移**。虚拟机定义和虚拟磁盘仍由远端 libvirt/宿主机持有,数据库保存面板账户、登录会话、模板目录、宿主机连接资料、更新设置和更新任务等面板数据。 + +如果是在旧测试目录上替换代码,旧 `data/generations/` 中的明文 SSH 私钥不会被新版使用,也**不会自动删除**。为避免遗留敏感文件,建议先备份并核对后,在首次运行新版前使用全新的 `data/` 目录;不要未经核对直接删除仍需使用的资料。 ## 目录与依赖 -面板目录固定为 `/home/virsh-panel`。代码、静态资源、`.venv/` 和启动后自动创建的 `data/` 都在这个目录下;**不会把面板数据放到 `/var`**。直接从命令行运行时,无需复制任何文件到其他目录。不要把 `/home/virsh-panel` 当作 Web 静态目录对外提供,尤其不能暴露 `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`)。如果 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。请自行安装这些依赖;面板没有安装器。 +管理服务器 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)。 @@ -22,13 +26,13 @@ python3 -m venv --system-site-packages .venv 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`,再次启动只需执行最后一行启动命令。**不需要编辑面板配置文件,也不需要运行初始化命令。** +上述命令保持在前台运行。出现 `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”,先确认这三个静态文件均为同一版本,再重新打开页面。 +手工更新版本时请同时替换 `static/index.html`、`static/app.js`、`static/styles.css` 和后端代码,不要只上传页面 HTML;保留原有 `data/` 和数据库。浏览器若出现“已选公网云镜像却仍要求 ISO”,先确认这三个静态文件均为同一版本,再重新打开页面。网页一键更新另有 Git 仓库和更新服务的要求,见下文。 -若初始化令牌意外公开、且尚未创建管理员,请先停止面板,只删除 `/home/virsh-panel/data/setup-token`,再启动面板生成新令牌。不要删除整个 `data/` 或管理员状态文件 `state.json`;新令牌不要再次公开。 +若初始化令牌意外公开、且尚未创建管理员,请先停止面板,只删除 `/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 的 root 终端运行面板;程序自动将 `data/` 目录及本地加密主密钥限制为 `0700`、`0600`。数据库中的敏感资料采用应用层认证加密,但运行中的 root 面板仍能解密 B 的 root SSH 私钥;只在可信网络和 HTTPS 反代后使用,妥善限制谁能访问 A。A 若启用 SELinux enforcing,还需在真实系统上验证 `/home/virsh-panel` 的访问标签。仓库保留可选 service 文件,但以上启动方式不依赖它。 ## 你自行配置的反向代理 @@ -36,9 +40,12 @@ PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -m uvicorn virsh_panel.app:create_app ## 首次网页操作 -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,失败不会覆盖现有连接。 +1. 通过你的 HTTPS 域名打开面板,使用启动终端输出中的一次性令牌填写 MariaDB 的地址、端口、已有数据库名、专用账号和密码。数据库账号至少需要在该数据库中建表及读写权限;连接失败时不会保存配置。当前数据库连接尚未提供 TLS 参数,数据库请放在面板本机或可信内网,不要将其端口暴露公网。 +2. 使用同一个令牌创建面板管理员。创建完成后令牌失效,管理员密码只保存为密码哈希。 +3. 在网页填写 B 的 IP/DNS、SSH 端口、现有的 **root 客户端 SSH 私钥**、磁盘目录、ISO 目录和网络名称。私钥必须与 B 的 root 账号**已经授权的公钥**匹配;仅有 root 密码或 B 的 SSH 主机密钥不能代替它。加密私钥还需填写其口令。口令只在当前面板进程的内存中用于解锁,不写入数据库、磁盘或浏览器存储;面板重启后,登录网页并在“解锁宿主机 SSH 私钥”页面重新输入。 +4. 点击“扫描主机指纹”,再通过 B 的可信控制台运行 `ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub` 独立核对;确认后在网页测试、保存。保存前会重扫并测试 SSH 与 libvirt API,失败不会覆盖现有连接。 + +宿主机私钥和配置加密保存在 MariaDB。OpenSSH 连接时需要读取私钥文件,Linux 上面板会将其临时还原到权限为 `0700` 的 `/dev/shm` 内存文件系统目录;面板关闭时清除。`data/runtime-wrappers/` 只包含不带密钥的启动包装器。面板仅支持单个 Uvicorn worker;多 worker 会导致各自 SSH 解锁状态不一致。 磁盘目录和 ISO 目录填写的是 **B 宿主机**上已存在的绝对路径,例如 `/home/kvm`、`/home/iso`,不是 A 面板服务器的路径;不需要提前手动创建 libvirt 存储池。点击“保存”时,面板会将这些现有目录定义为 libvirt `dir` 存储池并启动,作为内部管理机制;不会创建目录,也不会移动或删除现有文件。新建虚拟机的磁盘文件使用配置的磁盘目录下的 `<虚拟机名>.qcow2`,安装镜像使用配置的 ISO 目录下所选的 `.iso`;虚拟机 XML 通过绝对文件路径引用它们。“测试连接”不会修改宿主机,因此此时若目录尚未注册为池,可能仅显示资源警告。也可继续填写已有的 libvirt 存储池名称。若 B 的目录权限或 SELinux 策略阻止 libvirt 访问,保存会给出错误,需在 B 上修正权限或标签。 @@ -52,12 +59,27 @@ PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -m uvicorn virsh_panel.app:create_app ## 公网云镜像模板创建(无需手动安装) -面板的“创建虚拟机”现在有独立的“公网云镜像”方式。先在宿主机设置中选择已工作的 Linux 网桥,例如 `bridge:br0`;打开创建弹窗的“导入新的云镜像模板”,填写 [AlmaLinux 10 官方 Generic Cloud qcow2 镜像](https://wiki.almalinux.org/cloud/Generic-cloud)在 `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-*` 卷,不要未经核对就删除。 +面板的“创建虚拟机”现在有独立的“公网云镜像”方式。先在宿主机设置中选择已工作的 Linux 网桥,例如 `bridge:br0`;打开创建弹窗的“导入新的云镜像模板”,填写 [AlmaLinux 10 官方 Generic Cloud qcow2 镜像](https://wiki.almalinux.org/cloud/Generic-cloud)在 `https://repo.almalinux.org/almalinux/10/cloud/x86_64/images/` 下的下载地址、发布方 SHA-256 和模板显示名。地址必须是官方 HTTPS 直链,面板不会跟随重定向。面板服务器 A 需要能访问该地址。导入在后台运行,一次只允许一个任务,面板下载、校验 SHA-256 后通过当前 libvirt SSH 连接把模板镜像上传到 B 的磁盘池;无需登录 B 手工复制。模板目录记录加密保存在 MariaDB,绑定当前宿主机身份和磁盘池。不要在导入期间关闭面板进程;若进程异常退出,运行中的导入任务记录不会恢复,可能需要检查项目 `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 本地云镜像用法](https://wiki.almalinux.org/cloud/Generic-cloud-on-local)、[NoCloud 配置说明](https://docs.cloud-init.io/en/latest/reference/datasources/nocloud.html)。有公钥时,面板将其写入 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。 +面板创建的公网云镜像 VM 在列表中有“重装”按钮。点击后选择当前宿主机已导入的云镜像模板,输入 VM 名称确认;可填写新的 root SSH 公钥或 12–128 字符的初始 root 密码,二者均不填时会生成强密码。自动生成的密码会在 MariaDB 中加密保存,并在任务成功后显示;管理员点击“已保存密码,完成”后,面板会从任务记录中清除它,之后无法再次查看。同一浏览器标签页刷新或面板进程重启后仍可按任务编号查询,直到确认保存密码为止;关闭标签页前请及时妥善保存。重装自动读取原配置盘中的公网 IP/CIDR、网关、DNS 和 MAC,不要求再次手填网络。运行中的 VM 会先收到正常关机请求;120 秒内未关机则中止,不会强制断电,也不会切换或删除旧系统盘。面板会将所选模板克隆到新系统盘,生成新的 cloud-init 配置盘并启动 VM;新系统尚未启动时切换失败会恢复原定义,旧盘保留。如果启动调用结果不确定但发现新盘已在运行,则保留新旧两份磁盘并提示人工核查。**libvirt 报告新 VM 已启动后,面板会自动删除旧系统盘与旧配置盘;这并不能证明客体系统、网络或 SSH 已工作,旧数据一旦删除不可恢复。** 若旧盘清理失败,任务仍返回成功但附带警告,需在宿主机核查残留卷。此功能仅支持面板创建且配置未被外部修改的公网云镜像 VM,不支持 ISO 安装 VM、快照或多网卡/多磁盘 VM。 + +## 网页一键更新 + +网页的“网站更新”页固定从 `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 10 云镜像模板并配置公网静态 IP 创建、云镜像重装、开机、关机、重启、强制断电/重置、删除和浏览器 VNC。当前为单管理员、单宿主机版本;不提供 ISO 上传、目录自动创建、虚拟网络创建、内网 IP 模板、异网段网关或多用户权限。真实 AlmaLinux 10 宿主机仍需现场联调。 +功能范围:虚拟机列表、从 ISO 创建、导入 AlmaLinux 10 云镜像模板并配置公网静态 IP 创建、云镜像重装、开机、关机、重启、强制断电/重置、删除和浏览器 VNC。当前为单管理员、单宿主机版本;不提供 ISO 上传、目录自动创建、虚拟网络创建、内网 IP 模板、异网段网关或多用户权限。真实 AlmaLinux 10 宿主机及 MariaDB 仍需现场联调。 diff --git a/deploy/virsh-panel-update.service b/deploy/virsh-panel-update.service new file mode 100644 index 00000000..004bdf98 --- /dev/null +++ b/deploy/virsh-panel-update.service @@ -0,0 +1,22 @@ +[Unit] +Description=Virsh Panel one-shot update from the pinned private Gitea repository +After=network-online.target +Wants=network-online.target + +[Service] +Type=oneshot +User=root +Group=root +WorkingDirectory=/home/virsh-panel +Environment=PANEL_DATA_DIR=/home/virsh-panel/data +Environment=PYTHONDONTWRITEBYTECODE=1 +ExecStart=/home/virsh-panel/.venv/bin/python -m virsh_panel.update_worker +ExecStopPost=/home/virsh-panel/.venv/bin/python -m virsh_panel.update_worker --finalize-incomplete +TimeoutStartSec=30min +UMask=0077 +LimitCORE=0 +NoNewPrivileges=true +PrivateTmp=true +ProtectSystem=strict +ProtectHome=false +ReadWritePaths=/home/virsh-panel diff --git a/requirements.txt b/requirements.txt index b3890229..79c1b869 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,3 +3,5 @@ uvicorn[standard]>=0.34,<1 pydantic>=2,<3 pycdlib>=1.14,<2 passlib>=1.7.4,<2 +PyMySQL>=1.1,<2 +cryptography>=44,<49 diff --git a/static/app.js b/static/app.js index 24cb6d0b..e871f053 100644 --- a/static/app.js +++ b/static/app.js @@ -1,5 +1,7 @@ const byId = (id) => document.getElementById(id); const REINSTALL_JOB_STORAGE_PREFIX = "virsh-panel:reinstall-job:"; +const UPDATE_REPOSITORY_URL = "https://g.luoli.live/root/virt.git"; +const UPDATE_BRANCH = "main"; const state = { csrfToken: "", @@ -25,6 +27,12 @@ const state = { hostConfig: null, scannedHost: null, uploadedPrivateKey: "", + updateSettings: null, + updateCheck: null, + updateJobId: null, + updateLastShownJobId: null, + updatePollToken: 0, + updateReturnView: null, }; function text(id, value) { @@ -77,6 +85,7 @@ async function api(path, options = {}) { method, headers, credentials: "same-origin", + cache: "no-store", body: options.body === undefined ? undefined : JSON.stringify(options.body), }); } catch { @@ -87,7 +96,7 @@ async function api(path, options = {}) { if (response.status !== 204) { try { payload = await response.json(); } catch { /* A failed HTTP response may not be JSON. */ } } - if (response.status === 401 && path !== "/api/v1/login" && path !== "/api/v1/session" && !path.startsWith("/api/v1/setup/")) { + if (response.status === 401 && path !== "/api/v1/login" && path !== "/api/v1/session" && !path.startsWith("/api/v1/setup/") && !path.startsWith("/api/v1/database/")) { showLogin(); throw new Error("登录已过期,请重新登录。"); } @@ -111,11 +120,19 @@ function stopPolling() { function showLogin() { stopPolling(); closeModal(); + state.updatePollToken += 1; + state.updateJobId = null; + state.updateLastShownJobId = null; + state.updateCheck = null; + state.updateSettings = null; + state.updateReturnView = null; state.csrfToken = ""; state.vms = []; clearHostPrivateKey(); byId("unlock-passphrase").value = ""; + byId("update-access-token").value = ""; byId("boot-screen").hidden = true; + byId("database-view").hidden = true; byId("setup-view").hidden = true; byId("host-view").hidden = true; byId("unlock-view").hidden = true; @@ -123,11 +140,24 @@ function showLogin() { byId("login-view").hidden = false; } +function showDatabaseView() { + stopPolling(); + closeModal(); + byId("boot-screen").hidden = true; + byId("setup-view").hidden = true; + byId("login-view").hidden = true; + byId("host-view").hidden = true; + byId("unlock-view").hidden = true; + byId("dashboard-view").hidden = true; + byId("database-view").hidden = false; +} + function showSetup() { stopPolling(); closeModal(); byId("unlock-passphrase").value = ""; byId("boot-screen").hidden = true; + byId("database-view").hidden = true; byId("login-view").hidden = true; byId("host-view").hidden = true; byId("unlock-view").hidden = true; @@ -153,6 +183,7 @@ function showUnlockView(hostConfig) { text("unlock-current-user", state.username || "管理员"); text("unlock-host-label", hostConfig?.host ? `${hostConfig.host}:${hostConfig.port || 22}` : "当前宿主机"); byId("boot-screen").hidden = true; + byId("database-view").hidden = true; byId("setup-view").hidden = true; byId("login-view").hidden = true; byId("host-view").hidden = true; @@ -189,7 +220,7 @@ function showHostView(hostConfig = { configured: false }) { showError("host-error", ""); text("host-current-user", state.username || "管理员"); const configured = Boolean(hostConfig.configured); - text("host-step-label", configured ? "HOST SETTINGS" : "步骤 02 / 02"); + text("host-step-label", configured ? "HOST SETTINGS" : "步骤 03 / 03"); text("host-page-title", configured ? "宿主机设置" : "连接 libvirt 宿主机"); text("host-save-button", configured ? "保存修改" : "保存并进入面板"); byId("host-back-button").hidden = !configured; @@ -207,6 +238,7 @@ function showHostView(hostConfig = { configured: false }) { : "尚未测试连接"); byId("host-test-status").classList.remove("success", "warning"); byId("boot-screen").hidden = true; + byId("database-view").hidden = true; byId("setup-view").hidden = true; byId("login-view").hidden = true; byId("unlock-view").hidden = true; @@ -215,15 +247,18 @@ function showHostView(hostConfig = { configured: false }) { } async function showDashboard(session) { + state.updateReturnView = null; state.csrfToken = session.csrf_token || ""; state.username = session.username || "管理员"; text("current-username", state.username); byId("login-view").hidden = true; + byId("database-view").hidden = true; byId("setup-view").hidden = true; byId("host-view").hidden = true; byId("unlock-view").hidden = true; byId("boot-screen").hidden = true; byId("dashboard-view").hidden = false; + showVmWorkspace(); await Promise.allSettled([loadVMs(), loadResources()]); if (byId("dashboard-view").hidden) return; resumeReinstallJob(); @@ -245,6 +280,8 @@ async function continueAfterLogin(session) { async function initialize() { try { + const database = await api("/api/v1/database/status"); + if (database?.setup_required) { showDatabaseView(); return; } const setup = await api("/api/v1/setup/status"); if (setup?.setup_required) { showSetup(); return; } const session = await api("/api/v1/session"); @@ -256,6 +293,152 @@ async function initialize() { } } +function showVmWorkspace() { + byId("vm-workspace").hidden = false; + byId("update-workspace").hidden = true; + byId("vm-navigation-button").classList.add("active"); + byId("vm-navigation-button").setAttribute("aria-current", "page"); + byId("update-settings-button").classList.remove("active"); + byId("update-settings-button").removeAttribute("aria-current"); + text("breadcrumb-current", "虚拟机"); +} + +function openUpdateFromGate(returnView) { + if (returnView === "host") { + const hasKeyInput = Boolean(byId("host-private-key").value || state.uploadedPrivateKey || byId("host-private-key-passphrase").value); + if (hasKeyInput && !window.confirm("切换到网站更新会清空尚未保存的 SSH 私钥与口令输入。确定继续吗?")) return; + clearHostPrivateKey(); + } else if (returnView === "unlock") { + byId("unlock-passphrase").value = ""; + } + state.updateReturnView = returnView; + text("current-username", state.username || "管理员"); + byId("host-view").hidden = true; + byId("unlock-view").hidden = true; + byId("dashboard-view").hidden = false; + void showUpdateWorkspace(); +} + +function leaveUpdateWorkspace() { + byId("update-access-token").value = ""; + const returnView = state.updateReturnView; + if (returnView === "host" || returnView === "unlock") { + state.updateReturnView = null; + byId("dashboard-view").hidden = true; + byId("host-view").hidden = returnView !== "host"; + byId("unlock-view").hidden = returnView !== "unlock"; + return; + } + showVmWorkspace(); +} + +async function showUpdateWorkspace() { + byId("vm-workspace").hidden = true; + byId("update-workspace").hidden = false; + byId("vm-navigation-button").classList.remove("active"); + byId("vm-navigation-button").removeAttribute("aria-current"); + byId("update-settings-button").classList.add("active"); + byId("update-settings-button").setAttribute("aria-current", "page"); + text("breadcrumb-current", "网站更新"); + showError("update-settings-error", ""); + if (!state.updateLastShownJobId && !state.updateJobId) showError("update-action-error", ""); + try { + await loadUpdateSettings(); + } catch (error) { + showError("update-settings-error", `无法读取更新设置:${error.message}`); + } +} + +async function loadUpdateSettings() { + const settings = await api("/api/v1/update/settings"); + state.updateCheck = null; + state.updateSettings = { configured: Boolean(settings?.configured), token_configured: Boolean(settings?.token_configured) }; + byId("update-repository-url").value = UPDATE_REPOSITORY_URL; + byId("update-branch").value = UPDATE_BRANCH; + byId("update-access-token").value = ""; + text("update-token-hint", settings?.token_configured + ? "访问令牌已保存;留空则继续使用现有令牌。令牌不会在页面回显。" + : "填写具有仓库读取权限的令牌。保存后不会回显,也不会写入浏览器存储。"); + if (settings?.current_version) text("update-current-version", settings.current_version); + byId("update-check-button").disabled = !settings?.configured || Boolean(settings?.active_job_id); + byId("update-apply-button").disabled = true; + if (settings?.checkout_error) text("update-status", settings.checkout_error); + else if (!settings?.token_configured) text("update-status", "请先保存私有仓库访问令牌,再检查更新。"); + const activeJobId = settings?.active_job_id; + if (activeJobId && activeJobId !== state.updateJobId) { + state.updateJobId = activeJobId; + void pollUpdateJob(activeJobId, ++state.updatePollToken); + return; + } + if (activeJobId) return; + const lastJobId = settings?.last_job_id; + if (lastJobId && lastJobId !== state.updateLastShownJobId) { + try { + const job = await api(`/api/v1/update/jobs/${encodeURIComponent(lastJobId)}`); + const status = String(job?.status || ""); + if (status === "succeeded" || status === "completed") { + state.updateLastShownJobId = lastJobId; + state.updateJobId = null; + state.updatePollToken += 1; + if (job?.new_commit) text("update-current-version", job.new_commit); + showError("update-action-error", ""); + text("update-status", "上次面板更新已完成。请确认虚拟机与宿主机连接正常。"); + } else if (status === "failed") { + state.updateLastShownJobId = lastJobId; + state.updateJobId = null; + state.updatePollToken += 1; + text("update-status", "上次面板更新未完成。"); + showError("update-action-error", String(job?.error || job?.message || "请检查独立更新服务日志。")); + } else if (status === "queued" || status === "running") { + state.updateJobId = lastJobId; + void pollUpdateJob(lastJobId, ++state.updatePollToken); + } + } catch (error) { + showError("update-action-error", `无法读取上次更新结果:${error.message}`); + } + } +} + +async function pollUpdateJob(jobId, token) { + let errors = 0; + for (let attempt = 0; attempt < 420; attempt += 1) { + if (token !== state.updatePollToken) return; + try { + const job = await api(`/api/v1/update/jobs/${encodeURIComponent(jobId)}`); + if (token !== state.updatePollToken) return; + errors = 0; + const status = String(job?.status || "running"); + const phase = String(job?.phase || job?.message || "正在更新面板文件…"); + text("update-status", `更新任务:${phase}`); + if (status === "succeeded" || status === "completed") { + text("update-status", "面板更新已完成。请刷新页面,并确认虚拟机与宿主机连接正常。"); + state.updateJobId = null; + state.updateLastShownJobId = jobId; + byId("update-check-button").disabled = false; + toast("面板更新已完成。", "success"); + return; + } + if (status === "failed") { + const message = String(job?.error || job?.message || "更新失败,请检查面板日志。"); + text("update-status", "更新未完成。"); + showError("update-action-error", message); + state.updateJobId = null; + state.updateLastShownJobId = jobId; + byId("update-check-button").disabled = false; + return; + } + } catch (error) { + if (token !== state.updatePollToken) return; + errors += 1; + text("update-status", `面板暂时无法响应(第 ${errors} 次),可能正在重启;将继续查询同一更新任务。`); + } + await new Promise((resolve) => window.setTimeout(resolve, 5000)); + } + if (token === state.updatePollToken) { + text("update-status", "暂时无法确认更新结果。请检查服务状态和日志,不要重复点击更新。"); + } +} + function setButtonBusy(button, busy, busyLabel = "处理中…") { if (busy) { button.dataset.originalLabel = button.textContent; @@ -1058,6 +1241,39 @@ async function openConsole(vm) { } } +byId("database-form").addEventListener("submit", async (event) => { + event.preventDefault(); + showError("database-error", ""); + const button = byId("database-submit"); + const token = byId("database-token").value.trim(); + const body = { + host: byId("database-host").value.trim(), + port: Number(byId("database-port").value), + database: byId("database-name").value.trim(), + username: byId("database-username").value.trim(), + password: byId("database-password").value, + setup_token: token, + }; + setButtonBusy(button, true, "正在连接…"); + try { + requireSecureCredentialTransport(); + const result = await api("/api/v1/database/setup", { method: "POST", csrf: false, body }); + if (result?.configured !== true) throw new Error("无法确认数据库配置已保存,请刷新页面后检查状态。"); + byId("setup-token").value = token; + byId("database-password").value = ""; + byId("database-token").value = ""; + showSetup(); + } catch (error) { + showError("database-error", error.message); + } finally { + delete body.password; + delete body.setup_token; + byId("database-password").value = ""; + byId("database-token").value = ""; + setButtonBusy(button, false); + } +}); + byId("setup-form").addEventListener("submit", async (event) => { event.preventDefault(); showError("setup-error", ""); @@ -1128,6 +1344,12 @@ byId("host-logout-button").addEventListener("click", () => void logout(byId("hos byId("unlock-logout-button").addEventListener("click", () => void logout(byId("unlock-logout-button"))); byId("host-settings-button").addEventListener("click", () => showHostView(state.hostConfig || { configured: true })); byId("host-settings-mobile-button").addEventListener("click", () => showHostView(state.hostConfig || { configured: true })); +byId("host-update-button").addEventListener("click", () => openUpdateFromGate("host")); +byId("unlock-update-button").addEventListener("click", () => openUpdateFromGate("unlock")); +byId("vm-navigation-button").addEventListener("click", leaveUpdateWorkspace); +byId("update-settings-button").addEventListener("click", () => void showUpdateWorkspace()); +byId("update-settings-mobile-button").addEventListener("click", () => void showUpdateWorkspace()); +byId("update-back-button").addEventListener("click", leaveUpdateWorkspace); byId("unlock-settings-button").addEventListener("click", () => showHostView(state.hostConfig || { configured: true })); byId("host-back-button").addEventListener("click", () => { clearHostPrivateKey(); @@ -1185,6 +1407,93 @@ byId("host-private-key-file").addEventListener("change", async (event) => { } }); +byId("update-settings-form").addEventListener("submit", async (event) => { + event.preventDefault(); + showError("update-settings-error", ""); + const body = { repository_url: UPDATE_REPOSITORY_URL, branch: UPDATE_BRANCH }; + const accessToken = byId("update-access-token").value; + if (accessToken) body.access_token = accessToken; + if (!accessToken && !state.updateSettings?.token_configured) { + showError("update-settings-error", "请填写具有仓库读取权限的 Gitea 访问令牌。"); + return; + } + const button = byId("update-settings-submit"); + setButtonBusy(button, true, "正在保存…"); + try { + requireSecureCredentialTransport(); + const settings = await api("/api/v1/update/settings", { method: "PUT", body }); + state.updateSettings = { configured: Boolean(settings?.configured), token_configured: Boolean(settings?.token_configured) }; + state.updateCheck = null; + byId("update-check-button").disabled = !settings?.configured; + byId("update-apply-button").disabled = true; + byId("update-access-token").value = ""; + text("update-token-hint", "访问令牌已保存;留空则继续使用现有令牌。令牌不会在页面回显。"); + text("update-latest-version", "—"); + text("update-status", settings?.checkout_error || "访问令牌已保存。请点击“检查更新”。"); + toast("更新来源已保存。", "success"); + } catch (error) { + showError("update-settings-error", error.message); + } finally { + delete body.access_token; + byId("update-access-token").value = ""; + setButtonBusy(button, false); + } +}); + +byId("update-check-button").addEventListener("click", async () => { + showError("update-action-error", ""); + const button = byId("update-check-button"); + setButtonBusy(button, true, "正在检查…"); + byId("update-apply-button").disabled = true; + try { + const result = await api("/api/v1/update/check", { method: "POST" }); + state.updateCheck = result; + text("update-current-version", result?.current_version || "—"); + text("update-latest-version", result?.latest_version || "—"); + const available = result?.update_available === true; + byId("update-apply-button").disabled = !available || Boolean(state.updateJobId); + text("update-status", available ? "发现新版本。请先备份数据库和面板数据,再点击“一键更新”。" : "当前已是最新版本。"); + } catch (error) { + state.updateCheck = null; + showError("update-action-error", `检查更新失败:${error.message}`); + text("update-status", "未能确认仓库版本,请检查更新来源与令牌。"); + } finally { + setButtonBusy(button, false); + } +}); + +byId("update-apply-button").addEventListener("click", async () => { + if (!state.updateCheck?.update_available || state.updateJobId) return; + const expectedCurrent = String(state.updateCheck.current_version || ""); + const expectedRemote = String(state.updateCheck.latest_version || ""); + if (!expectedCurrent || !expectedRemote) { + showError("update-action-error", "缺少已检查的提交编号,请重新检查更新。"); + return; + } + if (!window.confirm(`即将把面板更新到已检查的提交 ${expectedRemote.slice(0, 12)}。如果仓库版本已变化,更新会停止并要求重新检查。过程可能重启服务。确认已备份数据库和面板数据,并且可以使用服务器控制台恢复后,再继续。确定执行吗?`)) return; + showError("update-action-error", ""); + const button = byId("update-apply-button"); + setButtonBusy(button, true, "正在提交…"); + byId("update-check-button").disabled = true; + try { + const started = await api("/api/v1/update/apply", { method: "POST", body: { + expected_current_commit: expectedCurrent, + expected_remote_commit: expectedRemote, + } }); + const jobId = String(started?.job_id || ""); + if (!jobId) throw new Error("未收到更新任务编号;请检查服务端状态,勿重复提交。"); + state.updateJobId = jobId; + text("update-status", "更新任务已提交,正在查询进度。服务可能短暂断开。"); + void pollUpdateJob(jobId, ++state.updatePollToken); + } catch (error) { + showError("update-action-error", `提交更新失败:${error.message}`); + byId("update-check-button").disabled = false; + } finally { + setButtonBusy(button, false); + byId("update-apply-button").disabled = true; + } +}); + byId("refresh-button").addEventListener("click", () => void loadVMs()); byId("search-input").addEventListener("input", () => renderVMs()); byId("state-filter").addEventListener("change", () => renderVMs()); diff --git a/static/index.html b/static/index.html index 725c597f..e68d75ab 100644 --- a/static/index.html +++ b/static/index.html @@ -5,8 +5,8 @@
面板业务数据保存在 MariaDB 中。只需在首次启用时填写连接信息,无需预先编辑面板配置文件。
+请先准备可连接的数据库与账号。连接信息只提交给面板服务,不会保存在浏览器中。
+请先完成你自己的 HTTPS 反向代理,并核对证书和域名,再输入数据库密码与初始化令牌。
+ +数据库需由你预先创建并授权;面板不会自动安装 MariaDB。初始化令牌完成管理员创建后失效。
+只需完成两步,即可从面板管理远端 libvirt 宿主机。启动前无需填写配置文件。
-完成数据库连接后,即可创建管理员并接入远端 libvirt 宿主机。
+使用面板首次启动时在终端输出的一次性初始化令牌。完成后令牌将失效。
安全检查:请先完成你自己的 HTTPS 反向代理,并确认浏览器连接的是你信任的证书和域名,再输入令牌、密码或宿主机私钥。
@@ -86,7 +121,7 @@填入现有的 root SSH 信息,面板将通过 libvirt API 管理远端虚拟机。
填入现有的 root SSH 信息,面板将通过 libvirt API 管理远端虚拟机。
使用宿主机已有的 root 私钥,不创建额外的系统账号。
口令只用于当前运行中的面板进程,不保存到磁盘或浏览器。请通过 HTTPS 连接面板。
+