Add MariaDB-backed panel state and web updates

main
admin 2 months ago
parent 4166c3002f
commit c83e17cd46

@ -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 仍需现场联调。

@ -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

@ -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

@ -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());

@ -5,8 +5,8 @@
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="theme-color" content="#101d2c" />
<title>VirtPilot · 虚拟机管理</title>
<link rel="stylesheet" href="/static/styles.css?v=reinstall-1" />
<script type="module" src="/static/app.js?v=reinstall-1"></script>
<link rel="stylesheet" href="/static/styles.css?v=database-update-1" />
<script type="module" src="/static/app.js?v=database-update-1"></script>
</head>
<body>
<div id="boot-screen" class="boot-screen" role="status" aria-live="polite">
@ -14,17 +14,52 @@
<span>正在连接控制面板…</span>
</div>
<main id="database-view" class="setup-layout" hidden>
<div class="setup-intro">
<div class="setup-brand"><span class="brand-mark"><span></span></span> VirtPilot</div>
<span class="eyebrow light">FIRST RUN SETUP</span>
<h1>先连接数据库,<br />再开始管理。</h1>
<p>面板业务数据保存在 MariaDB 中。只需在首次启用时填写连接信息,无需预先编辑面板配置文件。</p>
<div class="setup-steps"><span class="current">01 · 配置数据库</span><span>02 · 创建管理员</span><span>03 · 连接宿主机</span></div>
</div>
<div class="setup-form-side">
<section class="setup-card" aria-labelledby="database-title">
<span class="eyebrow">步骤 01 / 03</span>
<h2 id="database-title">连接 MariaDB</h2>
<p class="muted">请先准备可连接的数据库与账号。连接信息只提交给面板服务,不会保存在浏览器中。</p>
<p class="setup-security-note">请先完成你自己的 HTTPS 反向代理,并核对证书和域名,再输入数据库密码与初始化令牌。</p>
<form id="database-form" class="form-stack">
<label for="database-host">数据库 IP 或主机名</label>
<input id="database-host" name="host" type="text" autocomplete="off" maxlength="253" required placeholder="例如 127.0.0.1" />
<label for="database-port">端口</label>
<input id="database-port" name="port" type="number" min="1" max="65535" value="3306" required />
<label for="database-name">数据库名</label>
<input id="database-name" name="database" type="text" autocomplete="off" maxlength="64" required placeholder="例如 virsh_panel" />
<label for="database-username">数据库用户名</label>
<input id="database-username" name="username" type="text" autocomplete="off" maxlength="128" required />
<label for="database-password">数据库密码</label>
<input id="database-password" name="password" type="password" autocomplete="off" maxlength="1024" required />
<label for="database-token">初始化令牌</label>
<input id="database-token" name="setup_token" type="password" autocomplete="off" maxlength="256" required placeholder="粘贴面板启动终端输出中的令牌" />
<p id="database-error" class="form-error" role="alert" hidden></p>
<button id="database-submit" class="button button-primary setup-submit" type="submit">连接数据库并继续 <span aria-hidden="true">→</span></button>
</form>
<p class="setup-note">数据库需由你预先创建并授权;面板不会自动安装 MariaDB。初始化令牌完成管理员创建后失效。</p>
</section>
</div>
</main>
<main id="setup-view" class="setup-layout" hidden>
<div class="setup-intro">
<div class="setup-brand"><span class="brand-mark"><span></span></span> VirtPilot</div>
<span class="eyebrow light">FIRST RUN SETUP</span>
<h1>欢迎使用<br />VirtPilot</h1>
<p>只需完成两步,即可从面板管理远端 libvirt 宿主机。启动前无需填写配置文件。</p>
<div class="setup-steps"><span class="current">01 · 创建管理员</span><span>02 · 连接宿主机</span></div>
<p>完成数据库连接后,即可创建管理员并接入远端 libvirt 宿主机。</p>
<div class="setup-steps"><span>01 · 配置数据库</span><span class="current">02 · 创建管理员</span><span>03 · 连接宿主机</span></div>
</div>
<div class="setup-form-side">
<section class="setup-card" aria-labelledby="setup-title">
<span class="eyebrow">步骤 01 / 02</span>
<span class="eyebrow">步骤 02 / 03</span>
<h2 id="setup-title">创建面板管理员</h2>
<p class="muted">使用面板首次启动时在终端输出的一次性初始化令牌。完成后令牌将失效。</p>
<p class="setup-security-note">安全检查:请先完成你自己的 HTTPS 反向代理,并确认浏览器连接的是你信任的证书和域名,再输入令牌、密码或宿主机私钥。</p>
@ -86,7 +121,7 @@
<div class="host-topbar-actions"><span id="host-current-user" class="host-user"></span><button id="host-logout-button" class="button button-ghost small" type="button">退出登录</button></div>
</header>
<div class="host-content">
<div class="host-heading"><div><span id="host-step-label" class="eyebrow">步骤 02 / 02</span><h1 id="host-page-title">连接 libvirt 宿主机</h1><p>填入现有的 root SSH 信息,面板将通过 libvirt API 管理远端虚拟机。</p></div><button id="host-back-button" class="button button-outline" type="button" hidden>返回虚拟机</button></div>
<div class="host-heading"><div><span id="host-step-label" class="eyebrow">步骤 03 / 03</span><h1 id="host-page-title">连接 libvirt 宿主机</h1><p>填入现有的 root SSH 信息,面板将通过 libvirt API 管理远端虚拟机。</p></div><button id="host-update-button" class="button button-outline" type="button">网站更新</button><button id="host-back-button" class="button button-outline" type="button" hidden>返回虚拟机</button></div>
<div class="host-columns">
<section class="host-card" aria-labelledby="host-form-title">
<div class="host-card-heading"><span class="host-card-number">1</span><div><h2 id="host-form-title">SSH 连接信息</h2><p>使用宿主机已有的 root 私钥,不创建额外的系统账号。</p></div></div>
@ -143,6 +178,7 @@
</form>
<p class="host-security-note">口令只用于当前运行中的面板进程,不保存到磁盘或浏览器。请通过 HTTPS 连接面板。</p>
<button id="unlock-settings-button" class="button button-ghost small unlock-settings-button" type="button">修改宿主机设置</button>
<button id="unlock-update-button" class="button button-ghost small unlock-settings-button" type="button">网站更新</button>
</section>
</div>
</main>
@ -151,8 +187,9 @@
<aside class="sidebar">
<div class="sidebar-brand"><span class="brand-mark"><span></span></span><span>VirtPilot<small>CONTROL PANEL</small></span></div>
<div class="sidebar-section-label">工作区</div>
<div class="sidebar-link active"><span class="nav-icon" aria-hidden="true">▦</span> 虚拟机 <span class="nav-arrow" aria-hidden="true">›</span></div>
<button id="vm-navigation-button" class="sidebar-link sidebar-button active" type="button" aria-current="page"><span class="nav-icon" aria-hidden="true">▦</span> 虚拟机 <span class="nav-arrow" aria-hidden="true">›</span></button>
<button id="host-settings-button" class="sidebar-link sidebar-button" type="button"><span class="nav-icon" aria-hidden="true">⌁</span> 宿主机设置 <span class="nav-arrow" aria-hidden="true">›</span></button>
<button id="update-settings-button" class="sidebar-link sidebar-button" type="button"><span class="nav-icon" aria-hidden="true">↻</span> 网站更新 <span class="nav-arrow" aria-hidden="true">›</span></button>
<div class="sidebar-bottom">
<div class="host-panel"><div class="host-panel-icon" aria-hidden="true">⌁</div><div><strong>远端宿主机</strong><span id="host-connection-label">连接中…</span></div><span id="host-connection-dot" class="connection-dot"></span></div>
<div class="sidebar-caption">Powered by libvirt</div>
@ -161,11 +198,12 @@
<div class="main-area">
<header class="topbar">
<div class="breadcrumb">工作区 <span>/</span> <strong>虚拟机</strong></div>
<div class="topbar-right"><button id="host-settings-mobile-button" class="button button-ghost small host-settings-mobile" type="button">宿主机设置</button><span class="topbar-user"><span class="avatar" aria-hidden="true">A</span><span id="current-username">管理员</span></span><button id="logout-button" class="button button-ghost small" type="button">退出登录</button></div>
<div class="breadcrumb">工作区 <span>/</span> <strong id="breadcrumb-current">虚拟机</strong></div>
<div class="topbar-right"><button id="host-settings-mobile-button" class="button button-ghost small host-settings-mobile" type="button">宿主机设置</button><button id="update-settings-mobile-button" class="button button-ghost small host-settings-mobile" type="button">网站更新</button><span class="topbar-user"><span class="avatar" aria-hidden="true">A</span><span id="current-username">管理员</span></span><button id="logout-button" class="button button-ghost small" type="button">退出登录</button></div>
</header>
<main class="content">
<div id="vm-workspace">
<div class="page-heading"><div><span class="eyebrow">VIRTUAL MACHINES</span><h1>虚拟机管理</h1><p>查看状态、管理电源,并通过浏览器接入控制台。</p></div><div class="heading-actions"><button id="refresh-button" class="button button-outline" type="button"><span aria-hidden="true">↻</span> 刷新</button><button id="create-button" class="button button-primary" type="button"><span aria-hidden="true">+</span> 创建虚拟机</button></div></div>
<div id="resource-warning" class="resource-warning" role="alert" hidden></div>
@ -181,6 +219,34 @@
<div id="empty-state" class="empty-state" hidden><div class="empty-icon" aria-hidden="true">▦</div><h3 id="empty-title">还没有虚拟机</h3><p id="empty-description">点击右上角“创建虚拟机”开始。</p></div>
</section>
<div class="footer-note">状态每 15 秒自动更新 · 操作会发送至远端 libvirt 宿主机</div>
</div>
<div id="update-workspace" hidden>
<div class="page-heading"><div><span class="eyebrow">PANEL UPDATE</span><h1>网站更新</h1><p>从当前项目的私有 Gitea 仓库检查并安装新版本。</p></div><button id="update-back-button" class="button button-outline" type="button">返回虚拟机</button></div>
<div class="update-grid">
<section class="host-card" aria-labelledby="update-repository-title">
<div class="host-card-heading"><span class="host-card-number">1</span><div><h2 id="update-repository-title">更新来源</h2><p>这一版固定使用当前项目仓库的 main 分支;只需设置私有仓库访问令牌。</p></div></div>
<form id="update-settings-form" class="form-stack">
<label for="update-repository-url">仓库地址</label>
<input id="update-repository-url" type="url" value="https://g.luoli.live/root/virt.git" readonly aria-readonly="true" />
<label for="update-branch">更新分支</label>
<input id="update-branch" type="text" value="main" readonly aria-readonly="true" />
<label for="update-access-token">Gitea 访问令牌</label>
<input id="update-access-token" type="password" autocomplete="off" maxlength="4096" placeholder="填写具有仓库读取权限的令牌" />
<small id="update-token-hint" class="field-hint">令牌需要仓库读取权限。保存后不会回显,也不会写入浏览器存储。</small>
<p id="update-settings-error" class="form-error" role="alert" hidden></p>
<button id="update-settings-submit" class="button button-primary" type="submit">保存访问令牌</button>
</form>
</section>
<section class="host-card" aria-labelledby="update-run-title">
<div class="host-card-heading"><span class="host-card-number">2</span><div><h2 id="update-run-title">检查并更新</h2><p>先检查可用版本,确认后再执行更新。</p></div></div>
<div class="update-versions"><div><span>当前版本</span><strong id="update-current-version">—</strong></div><div><span>仓库版本</span><strong id="update-latest-version">—</strong></div></div>
<p id="update-status" class="host-test-status" role="status">尚未检查更新。</p>
<p id="update-action-error" class="form-error" role="alert" hidden></p>
<div class="host-submit-actions"><button id="update-check-button" class="button button-outline" type="button">检查更新</button><button id="update-apply-button" class="button button-primary" type="button" disabled>一键更新</button></div>
<p class="host-security-note">更新可能短暂中断面板服务。请先备份数据库及面板数据目录,并确保有服务端控制台可用于恢复。</p>
</section>
</div>
</div>
</main>
</div>
</div>

@ -69,6 +69,8 @@ input:focus,select:focus,button:focus-visible{outline:3px solid rgba(18,166,176,
.host-card textarea{width:100%;min-height:125px;padding:12px 13px;border:1px solid #dce4eb;border-radius:9px;color:#15243a;font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;resize:vertical;background:#fff}.host-card textarea:focus{border-color:#35b9c0;box-shadow:0 0 0 4px rgba(25,179,187,.1);outline:none}.host-card input[type=file]{height:auto;min-height:43px;padding:9px;font-size:11px}.host-card input[type=file]::file-selector-button{border:0;border-radius:6px;padding:5px 10px;margin-right:9px;background:#e9f6f6;color:#137e89;font-weight:700;cursor:pointer}
.fingerprint-result{margin:18px 0 14px;padding:14px;border:1px solid #b9e6e5;background:#effafa;border-radius:9px}.fingerprint-result>span{display:block;color:#417c85;font-size:11px;font-weight:700;margin-bottom:8px}.fingerprint-result code{display:block;color:#1b5260;font-size:12px;font-weight:800;line-height:1.7;overflow-wrap:anywhere}.host-security-note{font-size:11px;color:#8191a1;line-height:1.75;margin:16px 0 0}.host-security-note code{color:#41566e;font-size:10px;overflow-wrap:anywhere}.host-confirm{margin-top:17px;background:#f0fbf8;border-color:#cce9e0}.host-confirm strong{color:#217d6e}.host-confirm small{color:#659a90}
.host-test-status{font-size:12px;color:#708095;background:#f4f7fa;padding:12px 14px;border-radius:8px;line-height:1.55;margin:0 0 15px}.host-test-status.success{background:#e7f8ef;color:#1d9168}.host-test-status.warning{background:#fff4e6;color:#9a641d}.host-submit-actions{display:flex;gap:9px;flex-wrap:wrap}.host-submit-actions .button{flex:1}.host-card .form-error{margin:0 0 13px}
.update-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:19px;align-items:start}.update-grid .host-card{min-width:0}.update-grid .form-stack input{margin-bottom:17px}.update-grid .form-stack .field-hint{display:block;color:#8395a5;font-size:11px;line-height:1.6;margin:-7px 0 17px}.update-grid .form-stack .button{align-self:flex-start}.update-grid .host-test-status{margin-top:17px;overflow-wrap:anywhere}.update-versions{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:11px}.update-versions>div{border:1px solid #e2ebf0;border-radius:9px;padding:13px;background:#fbfdfd;min-width:0}.update-versions span{display:block;color:#8291a1;font-size:11px;margin-bottom:9px}.update-versions strong{display:block;color:#284459;font-size:12px;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;overflow-wrap:anywhere}
.update-grid .form-stack input[readonly]{background:#f4f7f9;color:#6c7d8d}
.unlock-content{min-height:calc(100vh - 75px);display:flex;align-items:center;justify-content:center;padding:40px 24px}.unlock-card{width:min(100%,480px);padding:35px}.unlock-card h1{font-size:28px;letter-spacing:-.5px;margin:12px 0}.unlock-card .muted{margin:0 0 27px}.unlock-card .muted strong{color:#30445a;overflow-wrap:anywhere}.unlock-submit{width:100%;min-height:46px}.unlock-settings-button{margin-top:18px;padding-left:0}
.dashboard{min-height:100vh;display:grid;grid-template-columns:244px minmax(0,1fr)}
.sidebar{position:sticky;top:0;height:100vh;background:#101d2c;color:#d2dce6;padding:32px 15px 22px;display:flex;flex-direction:column}
@ -143,7 +145,9 @@ tbody tr:hover{background:#fcfefe}
@media(max-width:1150px){th,td{padding-left:15px;padding-right:15px}.row-button{padding:6px}.content{padding-left:28px;padding-right:28px}}
@media(max-width:960px){.dashboard{display:block}.sidebar{position:relative;width:100%;height:65px;min-height:65px;padding:12px 24px}.sidebar-brand{padding:0}.sidebar-section-label,.sidebar-link,.sidebar-bottom{display:none}.host-settings-mobile{display:inline-flex}.topbar{height:60px;padding:0 24px}.content{padding:30px 24px}.page-heading{margin-bottom:24px}}
@media(max-width:960px){.host-columns{grid-template-columns:1fr}.host-side-stack{grid-template-columns:repeat(2,minmax(0,1fr));align-items:start}.setup-layout{grid-template-columns:minmax(280px,36%) 1fr}}
@media(max-width:960px){.update-grid{grid-template-columns:1fr}}
@media(max-width:740px){.login-layout{display:block;min-height:100vh}.login-art{display:none}.login-form-side{min-height:100vh;padding:32px 25px}.login-mobile-brand{display:flex;align-items:center;gap:10px;font-size:21px;font-weight:800;margin-bottom:70px}.login-card h2{font-size:29px}.page-heading{align-items:flex-start;flex-direction:column;gap:20px}.heading-actions{width:100%}.heading-actions .button{flex:1}.overview-grid{gap:9px}.stat-card{min-height:121px;padding:16px}.stat-card>strong{font-size:25px}.stat-top{font-size:10px}.stat-icon{width:27px;height:27px;font-size:12px}.stat-card>small{font-size:9px}.panel-heading{align-items:flex-start;flex-direction:column;padding:19px}.panel-tools{width:100%}.search-box{flex:1}.search-box input{width:100%}.footer-note{text-align:left}.console-toolbar{align-items:flex-start}.console-tools{flex-wrap:wrap;justify-content:flex-end}.console-tools .button{font-size:10px}}
@media(max-width:740px){.setup-layout{display:block}.setup-intro{min-height:0;padding:28px 25px}.setup-brand{margin:0 0 38px}.setup-intro h1{font-size:31px;margin:11px 0}.setup-intro p{font-size:12px;margin-bottom:24px}.setup-steps{margin-top:0}.setup-form-side{padding:36px 25px 55px}.setup-card h2{font-size:27px}.host-side-stack{grid-template-columns:1fr}.host-heading{align-items:flex-start;flex-direction:column}.host-topbar{height:65px}.host-content{padding-top:27px}.host-card{padding:20px}}
@media(max-width:510px){.topbar{padding:0 17px}.content{padding:25px 14px}.page-heading{padding:0 3px}.overview-grid{grid-template-columns:repeat(3,minmax(0,1fr))}.stat-card{padding:13px 11px;min-height:112px}.stat-card>strong{font-size:23px}.stat-icon{display:none}.topbar-right{gap:4px}.topbar-user{font-size:11px}.breadcrumb{font-size:11px}.modal-backdrop{padding:10px}.modal-header,.modal-body{padding-left:19px;padding-right:19px}.modal-footer{padding:14px 19px}.form-grid{gap:15px 10px}.console-backdrop{padding:0}.console-modal{height:100vh;max-height:100vh;border-radius:0}.console-stage{flex:1;height:auto}.console-tools .button{display:none}.console-password{flex-wrap:wrap}.console-password input{flex:1;min-width:130px}}
@media(max-width:510px){.topbar-right{flex-wrap:wrap;justify-content:flex-end;gap:2px}.host-settings-mobile{font-size:10px!important;padding:5px!important;min-height:28px!important}.topbar-user .avatar{display:none}.update-versions{grid-template-columns:1fr}}
@media(max-width:510px){.create-source-picker,.cloud-fields>.form-grid{grid-template-columns:1fr}}

@ -845,10 +845,10 @@ def test_static_assets_and_security_headers(web):
assert page.status_code == 200 and "text/html" in page.headers["content-type"]
assert page.headers["cache-control"] == "no-store"
assert "frame-ancestors 'none'" in page.headers["content-security-policy"]
assert "/static/app.js?v=reinstall-1" in page.text
assert "/static/styles.css?v=reinstall-1" in page.text
script = client.get("/static/app.js?v=reinstall-1")
style = client.get("/static/styles.css?v=reinstall-1")
assert "/static/app.js?v=database-update-1" in page.text
assert "/static/styles.css?v=database-update-1" in page.text
script = client.get("/static/app.js?v=database-update-1")
style = client.get("/static/styles.css?v=database-update-1")
assert script.status_code == 200 and script.headers["cache-control"] == "no-store"
assert style.status_code == 200 and style.headers["cache-control"] == "no-store"
assert "function updateCreateSource()" in script.text

@ -0,0 +1,224 @@
"""Database-backed state behavior without requiring a live MariaDB server."""
from __future__ import annotations
import base64
import os
import stat
import struct
import subprocess
from pathlib import Path
from types import SimpleNamespace
import pytest
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
from virsh_panel.auth import verify_password
from virsh_panel.cloud_templates import TemplateError
from virsh_panel.database import (
DatabasePanelState,
DatabaseRemoteHostManager,
DatabaseStore,
DatabaseTemplateStore,
)
from virsh_panel.remote_host import HostProfile, RemoteHostError
PRIVATE_KEY = "-----BEGIN OPENSSH PRIVATE KEY-----\nZmFrZQ==\n-----END OPENSSH PRIVATE KEY-----\n"
class MemoryStore:
def __init__(self) -> None:
self.records: dict[tuple[str, str], str] = {}
def get(self, kind: str, key: str) -> str | None:
return self.records.get((kind, key))
def set(self, kind: str, key: str, value: str) -> None:
self.records[(kind, key)] = value
def insert(self, kind: str, key: str, value: str) -> bool:
if (kind, key) in self.records:
return False
self.records[(kind, key)] = value
return True
def delete(self, kind: str, key: str) -> None:
self.records.pop((kind, key), None)
def list(self, kind: str) -> dict[str, str]:
return {key: value for (record_type, key), value in self.records.items()
if record_type == kind}
def test_database_ciphertext_is_randomized_and_bound_to_record_key():
store = DatabaseStore.__new__(DatabaseStore)
store._cipher = AESGCM(b"a" * 32)
first = store._encrypt("secret", "gitea_token", "private-token")
second = store._encrypt("secret", "gitea_token", "private-token")
assert first != second
assert b"private-token" not in first
assert store._decrypt("secret", "gitea_token", first) == "private-token"
with pytest.raises(Exception, match="密文"):
store._decrypt("secret", "different_name", first)
with pytest.raises(Exception, match="密文"):
store._decrypt("secret", "gitea_token", first[:-1] + b"0")
def test_linux_tmpfs_agent_socket_path_fits_openssh_limit():
# Linux pid_max cannot exceed 4,194,304; the runtime name is deliberately
# short so SSHAgentSession's <100-byte socket guard accepts it.
longest = (
"/dev/shm/v4194304-abcd/generations/gen-" + "f" * 32
+ "/agent-" + "f" * 16 + ".sock"
)
assert len(longest.encode()) < 100
def test_non_linux_rejects_disk_backed_private_key_fallback(tmp_path, monkeypatch):
monkeypatch.setattr("virsh_panel.database.sys", SimpleNamespace(platform="darwin"))
data_dir = tmp_path / "panel"
with pytest.raises(RemoteHostError, match="仅支持 Linux"):
DatabaseRemoteHostManager(MemoryStore(), data_dir)
assert not list(data_dir.rglob("id_private"))
def test_admin_hash_is_database_only_and_bootstrap_token_is_consumed(tmp_path: Path):
store = MemoryStore()
data_dir = tmp_path / "panel"
state = DatabasePanelState(data_dir, store)
token = state.initialize_setup_token()
assert token
state.create_admin(token, "admin", "a-valid-very-long-password")
assert not (data_dir / "state.json").exists()
assert not (data_dir / "setup-token").exists()
assert stat.S_IMODE(data_dir.stat().st_mode) == 0o700
reopened = DatabasePanelState(data_dir, store)
username, hashed = reopened.admin()
assert username == "admin"
assert verify_password("a-valid-very-long-password", hashed)
assert reopened.initialize_setup_token() is None
def test_templates_are_isolated_by_host_scope_and_atomic_insert():
store = MemoryStore()
templates = DatabaseTemplateStore(store)
record = {"id": "alma10-12345678-abcdef0123456789", "name": "AlmaLinux"}
assert templates.add("a" * 64, record) == record
assert templates.list("a" * 64) == [record]
assert templates.list("b" * 64) == []
with pytest.raises(TemplateError) as duplicate:
templates.add("a" * 64, record)
assert duplicate.value.status == 409
def _host_key() -> str:
blob = struct.pack("!I", 11) + b"ssh-ed25519" + struct.pack("!I", 32) + b"a" * 32
return "ssh-ed25519 " + base64.b64encode(blob).decode("ascii")
def _fake_ssh(argv, **_kwargs):
if argv[0] == "ssh-keyscan":
return subprocess.CompletedProcess(argv, 0, "host.example " + _host_key() + "\n", "")
if argv[0] == "ssh-keygen":
return subprocess.CompletedProcess(argv, 0, "ssh-ed25519 fake-public-key\n", "")
if argv[0] == "ssh":
return subprocess.CompletedProcess(argv, 0, "ok", "")
raise AssertionError(argv)
def _encrypted_ssh(argv, **kwargs):
if argv[0] == "ssh-keygen":
return subprocess.CompletedProcess(argv, 255, "", "passphrase required")
return _fake_ssh(argv, **kwargs)
class FakeAgent:
def __init__(self, generation: Path, _key_path: Path, passphrase: str) -> None:
if passphrase != "open-sesame":
raise RuntimeError("bad passphrase")
self.socket_path = generation / "fake-agent.sock"
self.public_key = _host_key()
self.alive = True
def close(self) -> None:
self.alive = False
def test_remote_host_is_rebuilt_from_database_without_durable_private_key(tmp_path: Path):
store = MemoryStore()
runtime_parent = tmp_path / "simulated-tmpfs"
runtime_parent.mkdir()
data_dir = tmp_path / "panel"
first = DatabaseRemoteHostManager(
store, data_dir, runtime_parent=runtime_parent, runner=_fake_ssh,
)
scan = first.scan("host.example", 22)
profile = HostProfile(
host="host.example", port=22, private_key=PRIVATE_KEY,
host_key=scan["known_hosts_line"], storage_pool="/home/kvm",
iso_pool="/home/iso", default_network="bridge:br0",
)
staged = first.stage(profile, scan["fingerprint"])
assert first.test(staged)["libvirt"] == "available"
current = first.commit(staged)
assert current["host"] == "host.example"
assert current["libvirt_uri"].find("runtime-wrappers") >= 0
assert ("host", "current") in store.records
assert not list(data_dir.rglob("id_private"))
assert not list(data_dir.rglob("profile.json"))
first.close()
second = DatabaseRemoteHostManager(
store, data_dir, runtime_parent=runtime_parent, runner=_fake_ssh,
)
assert second.current()["storage_pool"] == "/home/kvm"
assert second.current()["default_network"] == "bridge:br0"
assert (second._current_generation() / "id_private").read_text() == PRIVATE_KEY
assert not list(data_dir.rglob("id_private"))
second.close()
assert not list(runtime_parent.rglob("id_private"))
def test_encrypted_host_key_is_locked_again_after_process_restart(tmp_path: Path):
store = MemoryStore()
runtime_parent = tmp_path / "simulated-tmpfs"
runtime_parent.mkdir()
data_dir = tmp_path / "panel"
first = DatabaseRemoteHostManager(
store, data_dir, runtime_parent=runtime_parent,
runner=_encrypted_ssh, agent_factory=FakeAgent,
)
scan = first.scan("host.example", 22)
staged = first.stage(HostProfile(
host="host.example", port=22, private_key=PRIVATE_KEY,
host_key=scan["known_hosts_line"], private_key_passphrase="open-sesame",
), scan["fingerprint"])
first.test(staged)
assert first.commit(staged)["key_locked"] is False
first.close()
second = DatabaseRemoteHostManager(
store, data_dir, runtime_parent=runtime_parent,
runner=_encrypted_ssh, agent_factory=FakeAgent,
)
assert second.current()["key_locked"] is True
assert second.unlock_current("open-sesame")["key_locked"] is False
second.close()
def test_startup_prunes_only_marked_runtime_of_dead_process(tmp_path: Path, monkeypatch):
dead = tmp_path / "v99999999-dead"
live = tmp_path / f"v{os.getpid()}-abcd"
dead.mkdir(mode=0o700)
live.mkdir(mode=0o700)
(dead / ".owner").write_text("99999999:123\n")
(live / ".owner").write_text(f"{os.getpid()}:456\n")
(dead / ".owner").chmod(0o600)
(live / ".owner").chmod(0o600)
monkeypatch.setattr(
DatabaseRemoteHostManager, "_process_start_ticks",
staticmethod(lambda pid: "456" if pid == os.getpid() else None),
)
DatabaseRemoteHostManager._clean_stale_runtime(tmp_path)
assert not dead.exists()
assert live.exists()

@ -0,0 +1,84 @@
"""The only local durable configuration is encrypted database bootstrap data."""
from __future__ import annotations
import json
import stat
import pytest
from virsh_panel.database_bootstrap import (
DatabaseBootstrap, DatabaseSetupError, validate_database_config,
)
CONFIG = {
"host": "db.example.test", "port": 3306, "database": "virsh_panel",
"username": "panel", "password": "not-a-public-database-password",
}
def test_bootstrap_requires_token_and_encrypts_connection_settings(tmp_path):
bootstrap = DatabaseBootstrap(tmp_path / "data")
token = bootstrap.ensure_token()
assert bootstrap.ensure_token() == token
calls = []
def connect(config, key):
calls.append((config, key))
return "connected"
with pytest.raises(DatabaseSetupError) as wrong:
bootstrap.configure(CONFIG, "wrong-token", connect)
assert wrong.value.status == 403
assert calls == []
assert bootstrap.configure(CONFIG, token, connect) == "connected"
assert len(calls[0][1]) == 32
assert bootstrap.load_config() == CONFIG
assert CONFIG["password"].encode() not in bootstrap.config_file.read_bytes()
assert CONFIG["username"].encode() not in bootstrap.config_file.read_bytes()
assert stat.S_IMODE(bootstrap.data_dir.stat().st_mode) == 0o700
assert stat.S_IMODE(bootstrap.key_file.stat().st_mode) == 0o600
assert stat.S_IMODE(bootstrap.config_file.stat().st_mode) == 0o600
with pytest.raises(DatabaseSetupError) as repeated:
bootstrap.configure(CONFIG, token, connect)
assert repeated.value.status == 409
def test_bootstrap_does_not_commit_failed_connection(tmp_path):
bootstrap = DatabaseBootstrap(tmp_path / "data")
token = bootstrap.ensure_token()
def fail(_config, _key):
raise ConnectionError("database unavailable")
with pytest.raises(ConnectionError):
bootstrap.configure(CONFIG, token, fail)
assert not bootstrap.configured()
assert bootstrap.ensure_token() == token
def test_bootstrap_rejects_tampering_and_unsafe_files(tmp_path):
bootstrap = DatabaseBootstrap(tmp_path / "data")
token = bootstrap.ensure_token()
bootstrap.configure(CONFIG, token, lambda *_: None)
envelope = json.loads(bootstrap.config_file.read_text())
envelope["ciphertext"] = "AAAA"
bootstrap.config_file.write_text(json.dumps(envelope))
with pytest.raises(ValueError, match="损坏"):
bootstrap.load_config()
bootstrap.config_file.chmod(0o644)
with pytest.raises(ValueError, match="0600"):
bootstrap.load_config()
@pytest.mark.parametrize("bad", [
{**CONFIG, "host": "https://evil.example"},
{**CONFIG, "port": 0},
{**CONFIG, "database": "other;DROP TABLE admin"},
{**CONFIG, "username": "bad\nname"},
{**CONFIG, "password": ""},
])
def test_database_config_validation_rejects_unsafe_values(bad):
with pytest.raises(DatabaseSetupError):
validate_database_config(bad)

@ -0,0 +1,317 @@
"""First-run database and update routes with isolated in-memory dependencies."""
from __future__ import annotations
import json
import stat
import sys
import threading
import types
from concurrent.futures import ThreadPoolExecutor
from pathlib import Path
from types import SimpleNamespace
from fastapi.testclient import TestClient
# The HTTP boundary is tested with fake VM services; native libvirt is not
# available on ordinary development machines.
try:
import libvirt # noqa: F401
except ModuleNotFoundError:
stub = types.ModuleType("libvirt")
stub.libvirtError = type("libvirtError", (Exception,), {})
sys.modules["libvirt"] = stub
from virsh_panel import app as app_module
from virsh_panel.config import Settings
from virsh_panel.database import DatabasePanelState, DatabaseTemplateStore
class MemoryStore:
def __init__(self) -> None:
self.records = {}
def get(self, kind, key):
return self.records.get((kind, key))
def set(self, kind, key, value):
self.records[(kind, key)] = value
def insert(self, kind, key, value):
if (kind, key) in self.records:
return False
self.set(kind, key, value)
return True
def delete(self, kind, key):
self.records.pop((kind, key), None)
def list(self, kind):
return {key: value for (record_type, key), value in self.records.items()
if record_type == kind}
def get_secret(self, key):
return self.get("secret", key)
def set_secret(self, key, value):
self.set("secret", key, value)
def get_value(self, key):
return self.get("value", key)
def set_value(self, key, value):
self.set("value", key, value)
class FakeManager:
def current(self):
return None
def close(self):
pass
def test_first_run_requires_database_then_admin_and_ignores_old_json(monkeypatch, tmp_path):
data_dir = tmp_path / "data"
data_dir.mkdir(mode=0o700)
(data_dir / "state.json").write_text(
'{"version":1,"admin":{"username":"old","password_hash":"old"}}',
encoding="utf-8",
)
store = MemoryStore()
calls = []
def make_components(directory, config, key, _ssh_binary):
calls.append((config, key))
return (DatabasePanelState(directory, store), FakeManager(),
DatabaseTemplateStore(store), store)
monkeypatch.setattr(app_module, "make_components", make_components)
settings = Settings(data_dir=data_dir,
static_dir=Path(__file__).resolve().parents[1] / "static")
app = app_module.create_app(settings)
token = (data_dir / "setup-token").read_text(encoding="ascii").strip()
config = {
"host": "127.0.0.1", "port": 3306, "database": "virsh_panel",
"username": "panel", "password": "test-database-password",
}
with TestClient(app, base_url="https://panel.example.test") as client:
assert client.get("/api/v1/database/status").json() == {
"configured": False, "setup_required": True,
}
assert client.get("/api/v1/setup/status").status_code == 409
assert client.post("/api/v1/database/setup", json={
**config, "setup_token": "invalid",
}).status_code == 403
assert calls == []
response = client.post("/api/v1/database/setup", json={
**config, "setup_token": token,
})
assert response.status_code == 200
assert response.json() == {"configured": True}
assert calls[0][0] == config and len(calls[0][1]) == 32
assert client.get("/api/v1/setup/status").json() == {"setup_required": True}
created = client.post("/api/v1/setup/admin", json={
"token": token, "username": "admin",
"password": "correct-horse-battery-staple",
})
assert created.status_code == 200
assert client.get("/api/v1/setup/status").json() == {"setup_required": False}
session_cookie = client.cookies.get("virsh_panel_session")
assert ("admin", "singleton") in store.records
assert not (data_dir / "setup-token").exists()
encrypted = (data_dir / "database-config.json").read_bytes()
assert b"test-database-password" not in encrypted
assert stat.S_IMODE((data_dir / "master.key").stat().st_mode) == 0o600
store.set("import_job", "interrupted-job", json.dumps({
"status": "running", "scope": "previous-host",
}))
restarted = app_module.create_app(settings)
assert json.loads(store.get("import_job", "interrupted-job"))["status"] == "failed"
with TestClient(restarted, base_url="https://panel.example.test") as client:
client.cookies.set("virsh_panel_session", session_cookie)
assert client.get("/api/v1/session").json()["authenticated"] is True
def test_update_routes_require_auth_and_never_return_token(monkeypatch, tmp_path):
data_dir = tmp_path / "data"
store = MemoryStore()
monkeypatch.setattr(app_module, "make_components", lambda directory, *_: (
DatabasePanelState(directory, store), FakeManager(),
DatabaseTemplateStore(store), store,
))
settings = Settings(data_dir=data_dir,
static_dir=Path(__file__).resolve().parents[1] / "static")
app = app_module.create_app(settings)
token = (data_dir / "setup-token").read_text(encoding="ascii").strip()
class FakeUpdater:
def __init__(self, *_args):
self.token = None
self.job = None
def settings(self):
return {
"repository": "https://g.luoli.live/root/virt.git", "branch": "main",
"token_configured": self.token is not None, "checkout_ready": True,
"current_commit": "a" * 40, "active_job_id": None,
}
def set_token(self, token):
self.token = token
def check(self):
return {
"repository": "https://g.luoli.live/root/virt.git", "branch": "main",
"current_commit": "a" * 40, "remote_commit": "b" * 40,
"status": "update_available",
}
def create_job(self, *, expected_current_commit=None, expected_remote_commit=None):
assert expected_current_commit == "a" * 40
assert expected_remote_commit == "b" * 40
self.job = {"job_id": "test-job-00000001", "status": "queued"}
return self.job
def get_job(self, job_id):
return self.job if self.job and job_id == self.job["job_id"] else None
def fail_job(self, job_id, error):
self.job = {"job_id": job_id, "status": "failed", "error": error}
monkeypatch.setattr(app_module, "Updater", FakeUpdater)
monkeypatch.setattr(app_module.subprocess, "run", lambda *args, **kwargs:
SimpleNamespace(returncode=0, stdout="inactive"))
with TestClient(app, base_url="https://panel.example.test") as client:
assert client.get("/api/v1/update/settings").status_code == 401
client.post("/api/v1/database/setup", json={
"host": "127.0.0.1", "port": 3306, "database": "virsh_panel",
"username": "panel", "password": "test-database-password",
"setup_token": token,
})
response = client.post("/api/v1/setup/admin", json={
"token": token, "username": "admin",
"password": "correct-horse-battery-staple",
})
assert response.status_code == 200
csrf = response.json()["csrf_token"]
assert client.put("/api/v1/update/settings", json={
"access_token": "some-very-private-gitea-token",
}).status_code == 403
saved = client.put("/api/v1/update/settings", json={
"access_token": "some-very-private-gitea-token",
}, headers={"X-CSRF-Token": csrf})
assert saved.status_code == 200
assert saved.json()["configured"] is True
assert "some-very-private-gitea-token" not in saved.text
checked = client.post("/api/v1/update/check", headers={
"X-CSRF-Token": csrf,
})
assert checked.status_code == 200
assert checked.json()["update_available"] is True
queued = client.post("/api/v1/update/apply", json={
"expected_current_commit": "a" * 40,
"expected_remote_commit": "b" * 40,
}, headers={
"X-CSRF-Token": csrf,
})
assert queued.status_code == 202
job_id = queued.json()["job_id"]
assert client.get(f"/api/v1/update/jobs/{job_id}").json()["status"] == "queued"
def test_vm_creation_finishes_before_update_is_queued(monkeypatch, tmp_path):
data_dir = tmp_path / "data"
store = MemoryStore()
vm_started = threading.Event()
release_vm = threading.Event()
update_received = threading.Event()
update_queued = threading.Event()
class ConfiguredManager(FakeManager):
def current(self):
return {"key_locked": False}
class BlockingVMService:
def create_vm(self, _spec):
vm_started.set()
assert release_vm.wait(timeout=5), "test did not release VM creation"
return {"uuid": "00000000-0000-4000-8000-000000000001"}
class FakeUpdater:
def __init__(self, _repo_dir, data_store):
self.store = data_store
self.job = None
def create_job(self, **_kwargs):
self.job = {"job_id": "test-job-00000001", "status": "queued"}
self.store.set_value("update.active_job", self.job["job_id"])
update_queued.set()
return self.job
def get_job(self, job_id):
return self.job if self.job and job_id == self.job["job_id"] else None
def fail_job(self, _job_id, _message):
raise AssertionError("the mocked update service must start")
monkeypatch.setattr(app_module, "make_components", lambda directory, *_: (
DatabasePanelState(directory, store), ConfiguredManager(),
DatabaseTemplateStore(store), store,
))
monkeypatch.setattr(app_module, "Updater", FakeUpdater)
monkeypatch.setattr(
app_module.subprocess, "run",
lambda argv, **_kwargs: SimpleNamespace(
returncode=3 if "is-active" in argv else 0,
stdout="inactive" if "is-active" in argv else "",
),
)
settings = Settings(data_dir=data_dir,
static_dir=Path(__file__).resolve().parents[1] / "static")
app = app_module.create_app(settings, service_factory=lambda _profile: BlockingVMService())
@app.middleware("http")
async def observe_update(request, call_next):
if request.url.path == "/api/v1/update/apply":
update_received.set()
return await call_next(request)
token = (data_dir / "setup-token").read_text(encoding="ascii").strip()
with TestClient(app, base_url="https://panel.example.test") as client:
configured = client.post("/api/v1/database/setup", json={
"host": "127.0.0.1", "port": 3306, "database": "virsh_panel",
"username": "panel", "password": "test-database-password",
"setup_token": token,
})
assert configured.status_code == 200
admin = client.post("/api/v1/setup/admin", json={
"token": token, "username": "admin",
"password": "correct-horse-battery-staple",
})
assert admin.status_code == 200
headers = {"X-CSRF-Token": admin.json()["csrf_token"]}
with ThreadPoolExecutor(max_workers=2) as executor:
creating = executor.submit(client.post, "/api/v1/vms", json={
"name": "new-vm", "vcpu": 2, "memory_mib": 2048,
"disk_gib": 20, "network": "default", "iso": "AlmaLinux-10.iso",
}, headers=headers)
assert vm_started.wait(timeout=5)
updating = executor.submit(client.post, "/api/v1/update/apply", json={
"expected_current_commit": "a" * 40,
"expected_remote_commit": "b" * 40,
}, headers=headers)
try:
assert update_received.wait(timeout=5)
assert not update_queued.wait(timeout=0.2)
assert not updating.done()
finally:
release_vm.set()
assert creating.result(timeout=5).status_code == 201
assert updating.result(timeout=5).status_code == 202
assert update_queued.is_set()
blocked = client.post("/api/v1/vms", json={
"name": "another-vm", "vcpu": 2, "memory_mib": 2048,
"disk_gib": 20, "network": "default", "iso": "AlmaLinux-10.iso",
}, headers=headers)
assert blocked.status_code == 409

@ -0,0 +1,83 @@
"""The systemd post-stop hook must resolve interrupted update jobs."""
from __future__ import annotations
import unittest
from pathlib import Path
from unittest.mock import patch
from virsh_panel import update_worker
class FakeStore:
def __init__(self, job_id: str | None):
self.job_id = job_id
def get_value(self, name: str) -> str | None:
if name == "update.active_job":
return self.job_id
raise AssertionError(name)
class FakeUpdater:
def __init__(self, job: dict | None):
self.job = job
self.failed: list[tuple[str, str]] = []
def get_job(self, _job_id: str) -> dict | None:
return self.job
def fail_job(self, job_id: str, message: str) -> None:
self.failed.append((job_id, message))
if self.job is not None:
self.job["status"] = "failed"
class FinalizeIncompleteTests(unittest.TestCase):
def test_running_job_is_marked_failed_once(self):
store = FakeStore("job-1234567890123456")
updater = FakeUpdater({"status": "running"})
self.assertTrue(update_worker.finalize_incomplete_job(updater, store))
self.assertEqual(updater.job["status"], "failed")
self.assertEqual(len(updater.failed), 1)
self.assertIn("日志", updater.failed[0][1])
self.assertFalse(update_worker.finalize_incomplete_job(updater, store))
self.assertEqual(len(updater.failed), 1)
def test_queued_job_is_marked_failed(self):
store = FakeStore("job-1234567890123456")
updater = FakeUpdater({"status": "queued"})
self.assertTrue(update_worker.finalize_incomplete_job(updater, store))
self.assertEqual(updater.job["status"], "failed")
def test_terminal_or_missing_job_is_not_modified(self):
for status in ("succeeded", "failed"):
with self.subTest(status=status):
updater = FakeUpdater({"status": status})
self.assertFalse(update_worker.finalize_incomplete_job(
updater, FakeStore("job-1234567890123456")))
self.assertEqual(updater.failed, [])
self.assertFalse(update_worker.finalize_incomplete_job(
FakeUpdater(None), FakeStore("job-1234567890123456")))
self.assertFalse(update_worker.finalize_incomplete_job(
FakeUpdater({"status": "running"}), FakeStore(None)))
def test_cli_finalize_mode_does_not_run_update(self):
store = FakeStore("job-1234567890123456")
updater = FakeUpdater({"status": "running"})
with patch.object(update_worker, "_load_updater", return_value=(updater, store)):
self.assertEqual(update_worker.main(["--finalize-incomplete"]), 0)
self.assertEqual(updater.job["status"], "failed")
def test_service_invokes_post_stop_finalizer(self):
unit = (Path(__file__).resolve().parent.parent / "deploy" /
"virsh-panel-update.service").read_text(encoding="utf-8")
self.assertIn(
"ExecStopPost=/home/virsh-panel/.venv/bin/python "
"-m virsh_panel.update_worker --finalize-incomplete",
unit,
)
if __name__ == "__main__":
unittest.main()

@ -0,0 +1,255 @@
"""Offline checks for the private-repository update safety boundary."""
from __future__ import annotations
import subprocess
import tempfile
import unittest
from pathlib import Path
from virsh_panel.updater import REPOSITORY_URL, UpdateError, Updater
class MemoryStore:
def __init__(self):
self.secrets: dict[str, str] = {}
self.values: dict[str, str] = {}
def get_secret(self, name):
return self.secrets.get(name)
def set_secret(self, name, value):
self.secrets[name] = value
def delete_secret(self, name):
self.secrets.pop(name, None)
def get_value(self, name):
return self.values.get(name)
def set_value(self, name, value):
self.values[name] = value
def git(path: Path, *args: str) -> str:
result = subprocess.run(
["git", *args], cwd=path, capture_output=True, text=True, check=True,
)
return result.stdout.strip()
def make_repo(tmp_path: Path) -> Path:
source = tmp_path / "source"
source.mkdir()
git(source, "init", "-b", "main")
git(source, "config", "user.name", "Updater Test")
git(source, "config", "user.email", "updater@example.test")
(source / "README.md").write_text("old\n", encoding="utf-8")
(source / "requirements.txt").write_text("example-package==1.0\n", encoding="utf-8")
git(source, "add", "README.md", "requirements.txt")
git(source, "commit", "-m", "initial")
checkout = tmp_path / "panel"
subprocess.run(
["git", "clone", "--branch", "main", str(source), str(checkout)],
capture_output=True, text=True, check=True,
)
git(checkout, "remote", "set-url", "origin", REPOSITORY_URL)
return checkout
def advance_source(source: Path, *, filename: str = "README.md") -> str:
(source / filename).parent.mkdir(parents=True, exist_ok=True)
(source / filename).write_text("new\n", encoding="utf-8")
git(source, "add", filename)
git(source, "commit", "-m", "next")
return git(source, "rev-parse", "HEAD")
def local_fetch(updater: Updater, source: Path):
def fetch() -> str:
git(updater.repo_dir, "fetch", "--no-tags", str(source), "refs/heads/main")
return git(updater.repo_dir, "rev-parse", "FETCH_HEAD")
updater._fetch_remote = fetch
updater._install_requirements = lambda _target: None
class UpdaterTests(unittest.TestCase):
def setUp(self):
self.temp = tempfile.TemporaryDirectory(prefix="virsh-panel-updater-test-")
self.addCleanup(self.temp.cleanup)
self.tmp_path = Path(self.temp.name)
def test_settings_and_token_never_reveal_secret(self):
checkout = make_repo(self.tmp_path)
store = MemoryStore()
updater = Updater(checkout, store)
updater.set_token("a-test-access-token-123")
settings = updater.settings()
self.assertEqual(settings["repository"], REPOSITORY_URL)
self.assertTrue(settings["token_configured"])
self.assertTrue(settings["checkout_ready"])
self.assertIsNone(settings["active_job_id"])
self.assertIsNone(settings["last_job_id"])
self.assertNotIn("a-test-access-token-123", repr(settings))
with updater._git_auth() as env:
self.assertEqual(env["VIRSH_PANEL_GIT_TOKEN"], "a-test-access-token-123")
self.assertNotIn("a-test-access-token-123", Path(env["GIT_ASKPASS"]).read_text())
updater.clear_token()
self.assertFalse(updater.settings()["token_configured"])
def test_check_is_read_only_and_reports_new_version(self):
checkout = make_repo(self.tmp_path)
updater = Updater(checkout, MemoryStore())
current = git(checkout, "rev-parse", "HEAD")
updater._remote_head = lambda: current
self.assertEqual(updater.check()["status"], "current")
updater._remote_head = lambda: "a" * 40
self.assertEqual(updater.check()["status"], "update_available")
self.assertEqual(git(checkout, "rev-parse", "HEAD"), current)
def test_zip_or_dirty_checkout_is_rejected(self):
plain = self.tmp_path / "plain"
plain.mkdir()
with self.assertRaisesRegex(UpdateError, "Git"):
Updater(plain, MemoryStore()).check()
checkout = make_repo(self.tmp_path)
(checkout / "README.md").write_text("user changes\n", encoding="utf-8")
updater = Updater(checkout, MemoryStore())
with self.assertRaisesRegex(UpdateError, "未提交"):
updater.create_job()
with self.assertRaisesRegex(UpdateError, "未提交"):
updater.apply()
def test_fast_forward_job_is_persisted_and_calls_restart(self):
checkout = make_repo(self.tmp_path)
source = self.tmp_path / "source"
old = git(checkout, "rev-parse", "HEAD")
target = advance_source(source)
store = MemoryStore()
updater = Updater(checkout, store)
updater.set_token("a-test-access-token-123")
local_fetch(updater, source)
queued = updater.create_job()
self.assertEqual(updater.settings()["active_job_id"], queued["job_id"])
restarted = []
result = updater.run_pending_job(restart=lambda: restarted.append(True))
self.assertEqual(result["status"], "succeeded")
self.assertEqual(result["old_commit"], old)
self.assertEqual(result["new_commit"], target)
self.assertTrue(result["rollback_ref"].startswith("refs/virsh-panel/rollback/"))
self.assertEqual(updater.get_job(queued["job_id"]), result)
self.assertEqual(updater.settings()["last_job_id"], queued["job_id"])
self.assertIsNone(updater.settings()["active_job_id"])
self.assertEqual(restarted, [True])
self.assertEqual(git(checkout, "rev-parse", "HEAD"), target)
self.assertEqual(git(checkout, "rev-parse", result["rollback_ref"]), old)
def test_remote_history_rewrite_never_overwrites_local_code(self):
checkout = make_repo(self.tmp_path)
source = self.tmp_path / "source"
target = advance_source(source)
git(checkout, "config", "user.name", "Updater Test")
git(checkout, "config", "user.email", "updater@example.test")
(checkout / "README.md").write_text("local fork\n", encoding="utf-8")
git(checkout, "add", "README.md")
git(checkout, "commit", "-m", "local fork")
local = git(checkout, "rev-parse", "HEAD")
updater = Updater(checkout, MemoryStore())
local_fetch(updater, source)
with self.assertRaisesRegex(UpdateError, "分叉"):
updater.apply()
self.assertEqual(git(checkout, "rev-parse", "HEAD"), local)
self.assertNotEqual(local, target)
def test_failed_dependency_sync_leaves_code_unchanged(self):
checkout = make_repo(self.tmp_path)
source = self.tmp_path / "source"
advance_source(source)
updater = Updater(checkout, MemoryStore())
local_fetch(updater, source)
old = git(checkout, "rev-parse", "HEAD")
def fail_install(_target):
raise UpdateError("依赖失败", 502)
updater._install_requirements = fail_install
with self.assertRaisesRegex(UpdateError, "依赖失败"):
updater.apply()
self.assertEqual(git(checkout, "rev-parse", "HEAD"), old)
def test_git_url_rewrite_is_rejected_before_sending_token(self):
checkout = make_repo(self.tmp_path)
git(checkout, "config", "url.https://evil.example/.insteadOf", "https://g.luoli.live/")
updater = Updater(checkout, MemoryStore())
updater.set_token("a-test-access-token-123")
with self.assertRaisesRegex(UpdateError, "URL 重写"):
updater.check()
def test_new_code_cannot_track_private_data_or_submodules(self):
checkout = make_repo(self.tmp_path)
source = self.tmp_path / "source"
target = advance_source(source, filename="data/master.key")
updater = Updater(checkout, MemoryStore())
local_fetch(updater, source)
old = git(checkout, "rev-parse", "HEAD")
with self.assertRaisesRegex(UpdateError, "数据目录"):
updater.apply()
self.assertEqual(git(checkout, "rev-parse", "HEAD"), old)
self.assertNotEqual(old, target)
def test_failed_restart_is_persisted_without_hiding_applied_commit(self):
checkout = make_repo(self.tmp_path)
source = self.tmp_path / "source"
target = advance_source(source)
updater = Updater(checkout, MemoryStore())
updater.set_token("a-test-access-token-123")
local_fetch(updater, source)
job = updater.create_job()
def fail_restart():
raise UpdateError("重启失败", 500)
with self.assertRaisesRegex(UpdateError, "重启失败"):
updater.run_pending_job(restart=fail_restart)
stored = updater.get_job(job["job_id"])
self.assertEqual(stored["status"], "failed")
self.assertEqual(stored["new_commit"], target)
self.assertTrue(stored["rollback_ref"])
self.assertIn("代码可能已切换", stored["error"])
def test_checked_remote_commit_is_pinned_through_worker_execution(self):
checkout = make_repo(self.tmp_path)
source = self.tmp_path / "source"
old = git(checkout, "rev-parse", "HEAD")
checked = advance_source(source)
store = MemoryStore()
updater = Updater(checkout, store)
updater.set_token("a-test-access-token-123")
updater._remote_head = lambda: checked
local_fetch(updater, source)
queued = updater.create_job(
expected_current_commit=old,
expected_remote_commit=checked,
)
advance_source(source, filename="VERSION")
with self.assertRaisesRegex(UpdateError, "main 分支已变化"):
updater.run_pending_job(restart=lambda: None)
self.assertEqual(git(checkout, "rev-parse", "HEAD"), old)
self.assertEqual(updater.get_job(queued["job_id"])["status"], "failed")
def test_create_job_rejects_changed_remote_since_check(self):
checkout = make_repo(self.tmp_path)
updater = Updater(checkout, MemoryStore())
updater.set_token("a-test-access-token-123")
updater._remote_head = lambda: "b" * 40
with self.assertRaisesRegex(UpdateError, "main 分支已变化"):
updater.create_job(
expected_current_commit=git(checkout, "rev-parse", "HEAD"),
expected_remote_commit="a" * 40,
)
if __name__ == "__main__":
unittest.main()

@ -5,8 +5,10 @@ from __future__ import annotations
import asyncio
import hmac
import ipaddress
import json
import logging
import secrets
import subprocess
import threading
import uuid
from concurrent.futures import ThreadPoolExecutor
@ -19,7 +21,7 @@ from fastapi.responses import FileResponse, JSONResponse
from fastapi.staticfiles import StaticFiles
from pydantic import BaseModel, ConfigDict, Field, SecretStr
from .auth import LoginLimiter, Session, SessionStore, verify_password
from .auth import DatabaseSessionStore, LoginLimiter, Session, SessionStore, verify_password
from .cloud_init import _validate_guest_auth, hash_root_password
from .cloud_templates import (
TemplateError, TemplateStore, download_verified_image, template_id_for,
@ -27,9 +29,12 @@ from .cloud_templates import (
)
from .config import Settings
from .console import ConsoleRelayError, relay_console
from .database import DatabaseError, make_components
from .database_bootstrap import DatabaseBootstrap, DatabaseSetupError
from .libvirt_service import VMError, VMService
from .panel_state import PanelState, SetupError
from .remote_host import HostProfile, RemoteHostError, RemoteHostManager
from .updater import BRANCH, REPOSITORY_URL, UpdateError, Updater
COOKIE_NAME = "virsh_panel_session"
@ -45,6 +50,32 @@ class SetupBody(BaseModel):
password: str = Field(min_length=12, max_length=1024)
class DatabaseSetupBody(BaseModel):
model_config = ConfigDict(extra="forbid")
host: str = Field(min_length=1, max_length=253)
port: int = Field(ge=1, le=65535)
database: str = Field(min_length=1, max_length=64)
username: str = Field(min_length=1, max_length=128)
password: SecretStr
setup_token: str = Field(min_length=1, max_length=256)
class UpdateSettingsBody(BaseModel):
model_config = ConfigDict(extra="forbid")
repository_url: str = Field(default=REPOSITORY_URL, max_length=2048)
branch: str = Field(default=BRANCH, max_length=128)
access_token: SecretStr | None = None
class UpdateApplyBody(BaseModel):
model_config = ConfigDict(extra="forbid")
expected_current_commit: str = Field(pattern=r"^(?:[0-9a-f]{40}|[0-9a-f]{64})$")
expected_remote_commit: str = Field(pattern=r"^(?:[0-9a-f]{40}|[0-9a-f]{64})$")
class LoginBody(BaseModel):
model_config = ConfigDict(extra="forbid")
@ -206,14 +237,41 @@ def create_app(
) -> FastAPI:
settings = settings or Settings.from_env()
settings.validate()
state = panel_state or PanelState(settings.data_dir)
setup_token = state.initialize_setup_token()
# Injected objects keep the existing isolated HTTP test harness working.
# Normal production startup never uses the old JSON-backed stores.
database_mode = panel_state is None and remote_manager is None
bootstrap = DatabaseBootstrap(settings.data_dir) if database_mode else None
data_store = None
updater = None
if database_mode:
configured_database = bootstrap.load_config()
if configured_database is None:
setup_token = bootstrap.ensure_token()
state = None
manager = None
templates = None
else:
state, manager, templates, data_store = make_components(
settings.data_dir, configured_database, bootstrap.master_key(),
settings.ssh_binary,
)
setup_token = (bootstrap.ensure_token()
if state.setup_required() else state.initialize_setup_token())
else:
state = panel_state or PanelState(settings.data_dir)
setup_token = state.initialize_setup_token()
manager = remote_manager or RemoteHostManager(
settings.data_dir, ssh_binary=settings.ssh_binary)
templates = TemplateStore(settings.data_dir)
if setup_token is not None:
# Uvicorn writes this logger to stderr, which the supplied systemd
# service captures in its journal. Never expose the token over HTTP.
STARTUP_LOG.warning("VIRSH_PANEL_SETUP_TOKEN=%s", setup_token)
manager = remote_manager or RemoteHostManager(settings.data_dir, ssh_binary=settings.ssh_binary)
templates = TemplateStore(settings.data_dir)
if database_mode and (settings.data_dir / "generations").exists():
STARTUP_LOG.warning(
"Legacy data/generations detected; its old SSH key files are not migrated "
"or automatically removed. Verify and remove them separately."
)
import_executor = ThreadPoolExecutor(max_workers=1, thread_name_prefix="cloud-image-import")
import_lock = threading.RLock()
import_jobs: dict[str, dict] = {}
@ -222,7 +280,38 @@ def create_app(
reinstall_lock = threading.RLock()
reinstall_jobs: dict[str, dict] = {}
pending_reinstalls: set[tuple[str, str]] = set()
sessions = SessionStore()
def save_job(kind: str, job_id: str, job: dict) -> None:
if data_store is not None:
data_store.set(kind, job_id, json.dumps(
job, ensure_ascii=False, separators=(",", ":")))
def delete_job(kind: str, job_id: str) -> None:
if data_store is not None:
data_store.delete(kind, job_id)
def restore_jobs() -> None:
"""Expose interrupted jobs as failed, never pretend work resumed."""
if data_store is None:
return
for kind, destination in (("import_job", import_jobs),
("reinstall_job", reinstall_jobs)):
for job_id, raw in data_store.list(kind).items():
try:
job = json.loads(raw)
except (TypeError, ValueError) as exc:
raise DatabaseError("数据库任务记录损坏") from exc
if not isinstance(job, dict):
raise DatabaseError("数据库任务记录损坏")
if job.get("status") in {"queued", "running"}:
job["status"] = "failed"
job["phase"] = "面板重启,任务已中断"
job["error"] = "面板在任务执行期间重启;请检查宿主机实际状态,勿直接重复提交"
save_job(kind, job_id, job)
destination[job_id] = job
restore_jobs()
sessions = DatabaseSessionStore(data_store) if data_store is not None else SessionStore()
login_limiter = LoginLimiter()
setup_limiter = LoginLimiter()
unlock_limiter = LoginLimiter()
@ -234,7 +323,7 @@ def create_app(
finally:
reinstall_executor.shutdown(wait=True, cancel_futures=False)
import_executor.shutdown(wait=True, cancel_futures=False)
close_manager = getattr(manager, "close", None)
close_manager = getattr(manager, "close", None) if manager is not None else None
if callable(close_manager):
close_manager()
@ -284,6 +373,18 @@ def create_app(
async def handle_setup_error(_request: Request, exc: SetupError):
return JSONResponse(status_code=exc.status, content={"error": str(exc)})
@app.exception_handler(DatabaseSetupError)
async def handle_database_setup_error(_request: Request, exc: DatabaseSetupError):
return JSONResponse(status_code=exc.status, content={"error": str(exc)})
@app.exception_handler(DatabaseError)
async def handle_database_error(_request: Request, exc: DatabaseError):
return JSONResponse(status_code=exc.status, content={"error": str(exc)})
@app.exception_handler(UpdateError)
async def handle_update_error(_request: Request, exc: UpdateError):
return JSONResponse(status_code=exc.status, content={"error": str(exc)})
@app.exception_handler(TemplateError)
async def handle_template_error(_request: Request, exc: TemplateError):
return JSONResponse(status_code=exc.status, content={"error": str(exc)})
@ -301,6 +402,23 @@ def create_app(
raise HTTPException(status_code=403, detail="请求验证失败")
return session
def current_updater() -> Updater:
nonlocal updater
if data_store is None:
raise UpdateError("请先完成数据库配置", 409)
if updater is None:
updater = Updater(settings.static_dir.parent, data_store)
return updater
def forbid_long_job_during_update() -> None:
if data_store is None:
return
active_id = data_store.get_value("update.active_job")
if active_id:
job = current_updater().get_job(active_id)
if job is not None and job.get("status") in {"queued", "running"}:
raise HTTPException(status_code=409, detail="面板正在更新,暂时不能开始新任务")
def current_profile() -> dict:
profile = manager.current()
if profile is None:
@ -366,14 +484,68 @@ def create_app(
@app.get("/api/v1/health")
def health():
if data_store is not None:
# A running HTTP listener alone is not a usable post-update panel.
# The updater treats this endpoint as readiness for the configured DB.
data_store.get("admin", "singleton")
return {"status": "ok"}
@app.get("/api/v1/database/status")
def database_status():
if bootstrap is None:
return {"configured": True, "setup_required": False}
return {"configured": bootstrap.configured(),
"setup_required": not bootstrap.configured()}
@app.post("/api/v1/database/setup")
def setup_database(body: DatabaseSetupBody, request: Request):
nonlocal state, manager, templates, data_store, updater, sessions
if bootstrap is None:
raise DatabaseSetupError("数据库初始化仅供正常部署使用", 409)
peer = _peer(request)
if not setup_limiter.allowed(peer):
raise HTTPException(status_code=429, detail="初始化尝试过多,请稍后再试")
def connect(config: dict, master_key: bytes):
try:
return make_components(
settings.data_dir, config, master_key, settings.ssh_binary)
except Exception as exc:
# Connector errors may include database host details. Never
# reflect the exception, credentials or driver SQL in HTTP.
LOG.warning("database setup connection failed: %s", type(exc).__name__)
raise DatabaseSetupError(
"无法连接或初始化 MariaDB;请检查地址、账号、数据库和建表权限", 502,
) from exc
try:
components = bootstrap.configure({
"host": body.host,
"port": body.port,
"database": body.database,
"username": body.username,
"password": body.password.get_secret_value(),
}, body.setup_token, connect)
except DatabaseSetupError:
setup_limiter.failed(peer)
raise
state, manager, templates, data_store = components
sessions = DatabaseSessionStore(data_store)
restore_jobs()
setup_limiter.succeeded(peer)
LOG.info("panel database configured")
return {"configured": True}
@app.get("/api/v1/setup/status")
def setup_status():
if state is None:
raise HTTPException(status_code=409, detail="请先配置数据库")
return {"setup_required": state.setup_required()}
@app.post("/api/v1/setup/admin")
def setup_admin(body: SetupBody, request: Request):
if state is None:
raise HTTPException(status_code=409, detail="请先配置数据库")
peer = _peer(request)
if not setup_limiter.allowed(peer):
raise HTTPException(status_code=429, detail="初始化尝试过多,请稍后再试")
@ -399,6 +571,8 @@ def create_app(
@app.post("/api/v1/login")
def login(body: LoginBody, request: Request):
if state is None:
raise HTTPException(status_code=409, detail="请先配置数据库")
peer = _peer(request)
if not login_limiter.allowed(peer):
raise HTTPException(status_code=429, detail="登录尝试过多,请稍后再试")
@ -421,6 +595,94 @@ def create_app(
response.delete_cookie(COOKIE_NAME, path="/")
return response
def public_update_settings() -> dict:
info = current_updater().settings()
return {
"repository_url": info["repository"],
"branch": info["branch"],
"token_configured": info["token_configured"],
"checkout_ready": info["checkout_ready"],
"configured": info["token_configured"] and info["checkout_ready"],
"current_version": info["current_commit"],
"active_job_id": info.get("active_job_id"),
"last_job_id": info.get("last_job_id"),
"checkout_error": info.get("checkout_error"),
}
@app.get("/api/v1/update/settings")
def update_settings(_session: Session = Depends(require_session)):
return public_update_settings()
@app.put("/api/v1/update/settings")
def save_update_settings(body: UpdateSettingsBody,
_session: Session = Depends(require_write)):
if body.repository_url != REPOSITORY_URL or body.branch != BRANCH:
raise UpdateError("更新仓库和分支固定为面板指定的 Gitea main 分支", 422)
service = current_updater()
if body.access_token is not None:
token = body.access_token.get_secret_value()
if token:
service.set_token(token)
if not service.settings()["token_configured"]:
raise UpdateError("请填写 Gitea 私有仓库访问令牌", 422)
LOG.info("panel update access token configured: admin=%s", _session.username)
return public_update_settings()
@app.post("/api/v1/update/check")
def check_update(_session: Session = Depends(require_write)):
result = current_updater().check()
return {
"repository_url": result["repository"],
"branch": result["branch"],
"current_version": result["current_commit"],
"latest_version": result["remote_commit"],
"update_available": result["status"] == "update_available",
}
@app.post("/api/v1/update/apply", status_code=202)
def apply_update(body: UpdateApplyBody, _session: Session = Depends(require_write)):
with import_lock, reinstall_lock:
if pending_templates or pending_reinstalls:
raise UpdateError("云镜像导入或虚拟机重装正在执行,请等待完成后再更新面板", 409)
try:
unit = subprocess.run(
["/usr/bin/systemctl", "is-active", "virsh-panel-update.service"],
capture_output=True, text=True, timeout=5, check=False,
)
except (OSError, subprocess.TimeoutExpired):
unit = None
if unit is not None and unit.stdout.strip() in {
"activating", "active", "deactivating", "reloading",
}:
raise UpdateError("独立更新服务仍在运行,请等待其完全结束后再提交", 409)
service = current_updater()
job = service.create_job(
expected_current_commit=body.expected_current_commit,
expected_remote_commit=body.expected_remote_commit,
)
try:
# The web service has a read-only code tree. A separate one-shot
# unit performs the Git update and restarts this service.
trigger = subprocess.run(
["/usr/bin/systemctl", "--no-block", "start", "virsh-panel-update.service"],
capture_output=True, text=True, timeout=10, check=False,
)
except (OSError, subprocess.TimeoutExpired):
trigger = None
if trigger is None or trigger.returncode != 0:
service.fail_job(job["job_id"],
"无法启动独立更新服务;请检查 virsh-panel-update.service 是否已安装")
raise UpdateError("无法启动独立更新服务;请检查 systemd 配置", 503)
LOG.info("panel update queued: job=%s admin=%s", job["job_id"], _session.username)
return {"job_id": job["job_id"], "status": "queued"}
@app.get("/api/v1/update/jobs/{job_id}")
def update_job(job_id: str, _session: Session = Depends(require_session)):
job = current_updater().get_job(job_id)
if job is None:
raise UpdateError("更新任务不存在", 404)
return job
@app.get("/api/v1/host")
def host(_session: Session = Depends(require_session)):
return _public_host(manager.current())
@ -463,6 +725,7 @@ def create_app(
# A running reinstall uses the saved SSH host identity and paths. Do
# not replace them while its libvirt operation is in flight.
with reinstall_lock:
forbid_long_job_during_update()
if pending_reinstalls or any(
job.get("status") == "succeeded" and "generated_password" in job
for job in reinstall_jobs.values()):
@ -514,6 +777,7 @@ def create_app(
with import_lock:
import_jobs[job_id] = {"scope": scope, "status": "completed",
"template": record}
save_job("import_job", job_id, import_jobs[job_id])
except Exception as exc:
if isinstance(exc, (TemplateError, VMError)):
error = str(exc)
@ -524,6 +788,7 @@ def create_app(
error += f";宿主机模板卷 {volume_name} 可能需要人工检查"
with import_lock:
import_jobs[job_id] = {"scope": scope, "status": "failed", "error": error}
save_job("import_job", job_id, import_jobs[job_id])
finally:
if image_path is not None:
image_path.unlink(missing_ok=True)
@ -541,6 +806,7 @@ def create_app(
scope = template_scope(profile)
template_id = template_id_for(scope, body.sha256.lower())
with import_lock:
forbid_long_job_during_update()
if any(row["id"] == template_id for row in templates.list(scope)):
raise TemplateError("此云镜像已经导入", 409)
if (scope, template_id) in pending_templates:
@ -550,12 +816,14 @@ def create_app(
job_id = str(uuid.uuid4())
pending_templates.add((scope, template_id))
import_jobs[job_id] = {"scope": scope, "status": "running"}
save_job("import_job", job_id, import_jobs[job_id])
try:
import_executor.submit(run_template_import, job_id, profile,
scope, body, template_id)
except RuntimeError as exc:
pending_templates.discard((scope, template_id))
import_jobs.pop(job_id, None)
delete_job("import_job", job_id)
raise TemplateError("面板正在停止,无法开始导入任务", 503) from exc
LOG.info("cloud template import queued: job=%s admin=%s", job_id, _session.username)
return {"job_id": job_id, "status": "running"}
@ -580,30 +848,34 @@ def create_app(
@app.post("/api/v1/vms", status_code=201)
def create_vm(body: CreateISOBody | CreateCloudBody,
_session: Session = Depends(require_write)):
if isinstance(body, CreateCloudBody):
public_key = body.guest_ssh_public_key.strip()
root_password = (body.root_password.get_secret_value()
if body.root_password is not None else "")
if bool(public_key) == bool(root_password):
raise HTTPException(
status_code=422,
detail="虚拟机 SSH 公钥和初始 root 密码必须且只能填写一项",
)
password_hash = None
if root_password:
try:
password_hash = hash_root_password(root_password)
except ValueError as exc:
raise HTTPException(status_code=422, detail=str(exc)) from exc
profile = current_profile()
record = templates.get(template_scope(profile), body.template_id)
spec = body.model_dump(exclude={"source", "template_id", "root_password"})
spec["guest_ssh_public_key"] = public_key
if password_hash is not None:
spec["root_password_hash"] = password_hash
vm = new_service(profile).create_cloud_vm(spec, record["volume_name"])
else:
vm = current_service().create_vm(body.model_dump(exclude={"source"}))
# Keep the update submission lock until libvirt has finished creating
# the VM. Otherwise an update can restart the web process mid-create.
with reinstall_lock:
forbid_long_job_during_update()
if isinstance(body, CreateCloudBody):
public_key = body.guest_ssh_public_key.strip()
root_password = (body.root_password.get_secret_value()
if body.root_password is not None else "")
if bool(public_key) == bool(root_password):
raise HTTPException(
status_code=422,
detail="虚拟机 SSH 公钥和初始 root 密码必须且只能填写一项",
)
password_hash = None
if root_password:
try:
password_hash = hash_root_password(root_password)
except ValueError as exc:
raise HTTPException(status_code=422, detail=str(exc)) from exc
profile = current_profile()
record = templates.get(template_scope(profile), body.template_id)
spec = body.model_dump(exclude={"source", "template_id", "root_password"})
spec["guest_ssh_public_key"] = public_key
if password_hash is not None:
spec["root_password_hash"] = password_hash
vm = new_service(profile).create_cloud_vm(spec, record["volume_name"])
else:
vm = current_service().create_vm(body.model_dump(exclude={"source"}))
LOG.info("vm created: uuid=%s admin=%s", vm.get("uuid"), _session.username)
return vm
@ -619,11 +891,13 @@ def create_app(
job = reinstall_jobs.get(job_id)
if job is not None and job["status"] == "running":
job["phase"] = phase[:200]
save_job("reinstall_job", job_id, job)
try:
with reinstall_lock:
reinstall_jobs[job_id]["status"] = "running"
reinstall_jobs[job_id]["phase"] = "正在检查虚拟机"
save_job("reinstall_job", job_id, reinstall_jobs[job_id])
result = new_service(profile).reinstall_cloud_vm(
vm_id, template_volume_name,
ssh_public_key=ssh_public_key,
@ -637,10 +911,10 @@ def create_app(
if isinstance(result, dict) and result.get("warning"):
job["warning"] = str(result["warning"])
if generated_password is not None:
# The plaintext exists only in RAM. Keep it until the
# operator explicitly acknowledges saving it, so a lost
# HTTP response cannot make the new VM inaccessible.
# DatabaseStore encrypts this one-time password. Keep it
# until the operator explicitly acknowledges saving it.
job["generated_password"] = generated_password
save_job("reinstall_job", job_id, job)
LOG.info("vm reinstall succeeded: job=%s uuid=%s", job_id, vm_id)
except Exception as exc:
if isinstance(exc, (VMError, TemplateError, ValueError)):
@ -653,6 +927,7 @@ def create_app(
job["status"] = "failed"
job["phase"] = "重装失败"
job["error"] = error
save_job("reinstall_job", job_id, job)
LOG.warning("vm reinstall failed: job=%s uuid=%s", job_id, vm_id)
finally:
with reinstall_lock:
@ -685,6 +960,7 @@ def create_app(
raise HTTPException(status_code=422, detail=str(exc)) from exc
with reinstall_lock:
forbid_long_job_during_update()
profile = current_profile()
scope = template_scope(profile)
record = templates.get(scope, body.template_id)
@ -706,6 +982,7 @@ def create_app(
"vm_id": normalized_id,
"template_id": record["id"],
}
save_job("reinstall_job", job_id, reinstall_jobs[job_id])
pending_reinstalls.add(key)
try:
reinstall_executor.submit(
@ -716,6 +993,7 @@ def create_app(
except RuntimeError as exc:
pending_reinstalls.discard(key)
reinstall_jobs.pop(job_id, None)
delete_job("reinstall_job", job_id)
raise VMError("面板正在停止,无法开始重装任务", 503) from exc
LOG.info("vm reinstall queued: job=%s uuid=%s admin=%s",
job_id, normalized_id, _session.username)
@ -747,11 +1025,13 @@ def create_app(
if job["status"] != "succeeded":
raise VMError("重装任务尚未成功,不能确认密码", 409)
job.pop("generated_password", None)
save_job("reinstall_job", job_id, job)
return {"acknowledged": True}
@app.post("/api/v1/vms/{vm_id}/actions")
def action(vm_id: str, body: ActionBody, _session: Session = Depends(require_write)):
with reinstall_lock:
forbid_long_job_during_update()
profile = current_profile()
try:
normalized_id = str(uuid.UUID(vm_id))
@ -770,6 +1050,7 @@ def create_app(
_session: Session = Depends(require_write),
):
with reinstall_lock:
forbid_long_job_during_update()
profile = current_profile()
try:
normalized_id = str(uuid.UUID(vm_id))
@ -793,7 +1074,7 @@ def create_app(
if not _origin_matches_host(websocket.headers.get("origin"), host):
await websocket.close(code=4403)
return
if sessions.get(websocket.cookies.get(COOKIE_NAME)) is None:
if await asyncio.to_thread(sessions.get, websocket.cookies.get(COOKIE_NAME)) is None:
await websocket.close(code=4401)
return
profile = manager.current()

@ -4,10 +4,12 @@ from __future__ import annotations
import hashlib
import hmac
import json
import secrets
import threading
import time
from dataclasses import dataclass
from typing import Protocol
PASSWORD_ITERATIONS = 600_000
@ -82,6 +84,77 @@ class SessionStore:
self._sessions.pop(token, None)
class _SessionDatabase(Protocol):
def get(self, record_type: str, record_key: str) -> str | None: ...
def set(self, record_type: str, record_key: str, value: str) -> None: ...
def delete(self, record_type: str, record_key: str) -> None: ...
class DatabaseSessionStore:
"""Server-side sessions that survive a web-process restart.
Only a SHA-256 fingerprint of the bearer token is used as the database
record key. The username, CSRF token and expiry are encrypted by the
database store; the raw bearer token is never persisted.
"""
def __init__(self, database: _SessionDatabase) -> None:
self._database = database
@staticmethod
def _key(token: str) -> str:
return hashlib.sha256(token.encode("ascii")).hexdigest()
def issue(self, username: str) -> Session:
session = Session(
token=secrets.token_urlsafe(32),
username=username,
csrf_token=secrets.token_urlsafe(32),
expires_at=time.time() + SESSION_LIFETIME_SECONDS,
)
payload = json.dumps({
"username": session.username,
"csrf_token": session.csrf_token,
"expires_at": session.expires_at,
}, separators=(",", ":"))
self._database.set("session", self._key(session.token), payload)
return session
def get(self, token: str | None) -> Session | None:
if not isinstance(token, str) or not token or len(token) > 256:
return None
try:
key = self._key(token)
except UnicodeEncodeError:
return None
raw = self._database.get("session", key)
if raw is None:
return None
try:
data = json.loads(raw)
username = data["username"]
csrf_token = data["csrf_token"]
expires_at = data["expires_at"]
except (TypeError, ValueError, KeyError):
return None
if (not isinstance(username, str) or not isinstance(csrf_token, str)
or not isinstance(expires_at, (int, float))):
return None
if expires_at <= time.time():
self._database.delete("session", key)
return None
return Session(token, username, csrf_token, float(expires_at))
def revoke(self, token: str | None) -> None:
if not isinstance(token, str) or not token or len(token) > 256:
return
try:
key = self._key(token)
except UnicodeEncodeError:
return
self._database.delete("session", key)
class LoginLimiter:
"""Small in-memory limit for failed logins from one peer address."""

@ -0,0 +1,698 @@
"""MariaDB-backed panel state with authenticated encryption at rest.
The database is the durable source of truth. OpenSSH still needs ordinary
files while it runs, so the remote-host adapter builds those in a private
tmpfs directory on Linux and removes them when the panel stops. Only a
non-secret executable wrapper is written to the panel's data directory.
"""
from __future__ import annotations
import hmac
import json
import os
import re
import secrets
import shutil
import stat
import sys
import threading
from pathlib import Path
from typing import Any, Mapping
from urllib.parse import quote
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
try:
import pymysql
except ImportError: # Allows package tooling to import without optional DB extras.
pymysql = None
from .auth import hash_password
from .cloud_templates import TemplateError
from .panel_state import PanelState, SetupError, _USERNAME
from .remote_host import (
LIBVIRT_URI,
SSH_ALIAS,
RemoteHostError,
RemoteHostManager,
StagedHost,
_fingerprint,
_key_parts,
_quoted_path,
_validate_host,
_validate_network_selector,
_validate_pool_selector,
_validate_port,
_validate_private_key,
_write_private,
)
from .ssh_agent import SSHAgentSession, _ASKPASS_SOURCE
_RECORD_NAME = re.compile(r"[A-Za-z0-9_.:-]{1,191}\Z")
_RUNTIME_NAME = re.compile(r"v([0-9]+)-[0-9a-f]{4}\Z")
_ENVELOPE_VERSION = b"vp1"
_SCHEMA = """
CREATE TABLE IF NOT EXISTS panel_records (
record_type VARCHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
record_key VARCHAR(191) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
encrypted_value LONGBLOB NOT NULL,
PRIMARY KEY (record_type, record_key)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
"""
class DatabaseError(Exception):
"""A database failure that does not echo connection credentials."""
def __init__(self, message: str = "数据库连接或读写失败,请检查数据库配置和服务状态") -> None:
super().__init__(message)
self.status = 503
class DatabaseStore:
"""Small encrypted record store backed by a single InnoDB table.
A unique `(record_type, record_key)` key makes insert-only operations
atomic across panel processes. Each record uses a fresh AES-GCM nonce and
binds the ciphertext to its database key through associated data.
"""
def __init__(self, config: Mapping[str, Any], master_key: bytes) -> None:
if pymysql is None:
raise DatabaseError("缺少 PyMySQL 依赖,请安装面板 requirements.txt")
if not isinstance(master_key, bytes) or len(master_key) != 32:
raise ValueError("Database master key must be 32 bytes")
if not isinstance(config, Mapping):
raise ValueError("Database configuration is invalid")
try:
host = config["host"]
port = config["port"]
database = config["database"]
username = config["username"]
password = config["password"]
except KeyError as exc:
raise ValueError("Database configuration is incomplete") from exc
if (not isinstance(host, str) or not 1 <= len(host) <= 253
or any(char in host for char in "\r\n\x00")):
raise ValueError("Database host is invalid")
if isinstance(port, bool) or not isinstance(port, int) or not 1 <= port <= 65535:
raise ValueError("Database port is invalid")
if (not isinstance(database, str) or not re.fullmatch(r"[A-Za-z0-9_]{1,64}", database)
or not isinstance(username, str) or not 1 <= len(username) <= 128
or any(char in username for char in "\r\n\x00")
or not isinstance(password, str)):
raise ValueError("Database credentials are invalid")
self._config = {
"host": host,
"port": port,
"database": database,
"user": username,
"password": password,
"charset": "utf8mb4",
"cursorclass": pymysql.cursors.DictCursor,
"connect_timeout": 5,
"read_timeout": 10,
"write_timeout": 10,
"autocommit": False,
}
self._cipher = AESGCM(master_key)
self._initialize_schema()
@staticmethod
def _validate_key(record_type: str, record_key: str) -> None:
if (not isinstance(record_type, str) or len(record_type) > 32
or not _RECORD_NAME.fullmatch(record_type)
or not isinstance(record_key, str) or not _RECORD_NAME.fullmatch(record_key)):
raise ValueError("Database record name is invalid")
def _connect(self):
try:
return pymysql.connect(**self._config)
except pymysql.MySQLError as exc:
raise DatabaseError() from exc
def _initialize_schema(self) -> None:
connection = self._connect()
try:
with connection.cursor() as cursor:
cursor.execute(_SCHEMA)
connection.commit()
except pymysql.MySQLError as exc:
connection.rollback()
raise DatabaseError("无法初始化数据库表,请检查账号建表权限") from exc
finally:
connection.close()
def _encrypt(self, record_type: str, record_key: str, value: str) -> bytes:
if not isinstance(value, str):
raise TypeError("Database value must be a string")
nonce = secrets.token_bytes(12)
associated_data = f"{record_type}\x00{record_key}".encode("ascii")
return _ENVELOPE_VERSION + nonce + self._cipher.encrypt(
nonce, value.encode("utf-8"), associated_data,
)
def _decrypt(self, record_type: str, record_key: str, payload: bytes) -> str:
if not isinstance(payload, (bytes, bytearray)) or not payload.startswith(_ENVELOPE_VERSION):
raise DatabaseError("数据库密文格式无效或主密钥不匹配")
nonce = bytes(payload[3:15])
ciphertext = bytes(payload[15:])
if len(nonce) != 12 or len(ciphertext) < 16:
raise DatabaseError("数据库密文格式无效或主密钥不匹配")
try:
return self._cipher.decrypt(
nonce, ciphertext, f"{record_type}\x00{record_key}".encode("ascii"),
).decode("utf-8")
except (ValueError, UnicodeError) as exc:
raise DatabaseError("数据库密文格式无效或主密钥不匹配") from exc
except Exception as exc:
# InvalidTag does not reveal whether the key or ciphertext is wrong.
raise DatabaseError("数据库密文格式无效或主密钥不匹配") from exc
def get(self, record_type: str, record_key: str) -> str | None:
self._validate_key(record_type, record_key)
connection = self._connect()
try:
with connection.cursor() as cursor:
cursor.execute(
"SELECT encrypted_value FROM panel_records "
"WHERE record_type=%s AND record_key=%s",
(record_type, record_key),
)
row = cursor.fetchone()
return None if row is None else self._decrypt(
record_type, record_key, row["encrypted_value"],
)
except pymysql.MySQLError as exc:
raise DatabaseError() from exc
finally:
connection.close()
def set(self, record_type: str, record_key: str, value: str) -> None:
self._validate_key(record_type, record_key)
payload = self._encrypt(record_type, record_key, value)
connection = self._connect()
try:
with connection.cursor() as cursor:
cursor.execute(
"INSERT INTO panel_records (record_type, record_key, encrypted_value) "
"VALUES (%s, %s, %s) ON DUPLICATE KEY UPDATE encrypted_value=VALUES(encrypted_value)",
(record_type, record_key, payload),
)
connection.commit()
except pymysql.MySQLError as exc:
connection.rollback()
raise DatabaseError() from exc
finally:
connection.close()
def insert(self, record_type: str, record_key: str, value: str) -> bool:
"""Insert once; return False if another process already inserted it."""
self._validate_key(record_type, record_key)
payload = self._encrypt(record_type, record_key, value)
connection = self._connect()
try:
with connection.cursor() as cursor:
cursor.execute(
"INSERT INTO panel_records "
"(record_type, record_key, encrypted_value) VALUES (%s, %s, %s)",
(record_type, record_key, payload),
)
connection.commit()
return True
except pymysql.err.IntegrityError as exc:
connection.rollback()
if exc.args and exc.args[0] == 1062:
return False
raise DatabaseError() from exc
except pymysql.MySQLError as exc:
connection.rollback()
raise DatabaseError() from exc
finally:
connection.close()
def delete(self, record_type: str, record_key: str) -> None:
self._validate_key(record_type, record_key)
connection = self._connect()
try:
with connection.cursor() as cursor:
cursor.execute(
"DELETE FROM panel_records WHERE record_type=%s AND record_key=%s",
(record_type, record_key),
)
connection.commit()
except pymysql.MySQLError as exc:
connection.rollback()
raise DatabaseError() from exc
finally:
connection.close()
def list(self, record_type: str) -> dict[str, str]:
self._validate_key(record_type, "x")
connection = self._connect()
try:
with connection.cursor() as cursor:
cursor.execute(
"SELECT record_key, encrypted_value FROM panel_records WHERE record_type=%s",
(record_type,),
)
rows = cursor.fetchall()
return {
row["record_key"]: self._decrypt(
record_type, row["record_key"], row["encrypted_value"],
) for row in rows
}
except pymysql.MySQLError as exc:
raise DatabaseError() from exc
finally:
connection.close()
def get_secret(self, name: str) -> str | None:
return self.get("secret", name)
def set_secret(self, name: str, value: str) -> None:
self.set("secret", name, value)
def delete_secret(self, name: str) -> None:
self.delete("secret", name)
def get_value(self, name: str) -> str | None:
return self.get("value", name)
def set_value(self, name: str, value: str) -> None:
self.set("value", name, value)
def delete_value(self, name: str) -> None:
self.delete("value", name)
class DatabasePanelState(PanelState):
"""Admin in MariaDB; the one-time bootstrap token remains a local file."""
def __init__(self, data_dir: Path, store: DatabaseStore) -> None:
super().__init__(data_dir)
self.store = store
def admin(self) -> tuple[str, str] | None:
raw = self.store.get("admin", "singleton")
if raw is None:
return None
try:
record = json.loads(raw)
except (TypeError, ValueError) as exc:
raise DatabaseError("数据库管理员记录格式无效") from exc
if (not isinstance(record, dict) or not isinstance(record.get("username"), str)
or not isinstance(record.get("password_hash"), str)):
raise DatabaseError("数据库管理员记录格式无效")
return record["username"], record["password_hash"]
def create_admin(self, token: str, username: str, password: str) -> str:
if not isinstance(username, str) or not _USERNAME.fullmatch(username):
raise SetupError("用户名应为 3 至 32 位字母、数字、点、下划线或连字符")
if not isinstance(password, str) or len(password) < 12 or len(password) > 1024:
raise SetupError("管理员密码长度须在 12 至 1024 位之间")
with self._setup_lock():
if self.admin() is not None:
raise SetupError("管理员已创建", 409)
try:
expected = self._read_token()
except FileNotFoundError as exc:
raise SetupError("初始化口令不可用,请重新启动面板并查看启动终端输出", 503) from exc
if not isinstance(token, str) or not hmac.compare_digest(token, expected):
raise SetupError("初始化口令无效", 403)
record = json.dumps(
{"username": username, "password_hash": hash_password(password)},
ensure_ascii=False, separators=(",", ":"),
)
if not self.store.insert("admin", "singleton", record):
raise SetupError("管理员已创建", 409)
self.token_file.unlink(missing_ok=True)
self._fsync_directory()
return username
class DatabaseTemplateStore:
"""Cloud-image catalog records stored independently in MariaDB."""
def __init__(self, store: DatabaseStore) -> None:
self.store = store
def list(self, scope: str) -> list[dict]:
prefix = f"{scope}:"
records = []
for key, payload in self.store.list("template").items():
if not key.startswith(prefix):
continue
try:
record = json.loads(payload)
except (TypeError, ValueError) as exc:
raise TemplateError("数据库模板记录损坏", 500) from exc
if not isinstance(record, dict):
raise TemplateError("数据库模板记录损坏", 500)
records.append(record)
return records
def get(self, scope: str, template_id: str) -> dict:
for record in self.list(scope):
if record.get("id") == template_id:
return record
raise TemplateError("模板不存在或不属于当前宿主机", 404)
def add(self, scope: str, record: dict) -> dict:
if not isinstance(record, dict) or not isinstance(record.get("id"), str):
raise TemplateError("模板记录无效")
key = f"{scope}:{record['id']}"
if not self.store.insert("template", key, json.dumps(
record, ensure_ascii=False, separators=(",", ":"))):
raise TemplateError("此云镜像已导入", 409)
return record
class DatabaseStagedHost(StagedHost):
def __init__(self, staged: StagedHost, wrapper_path: Path) -> None:
super().__init__(staged.path, staged.metadata, staged.tested)
self.wrapper_path = wrapper_path
@property
def libvirt_uri(self) -> str:
return f"{LIBVIRT_URI}&command={quote(str(self.wrapper_path), safe='/')}"
class _DatabaseSSHAgentSession(SSHAgentSession):
"""Keep the no-secret askpass executable off possibly-noexec tmpfs."""
def __init__(self, generation: Path, key_path: Path, passphrase: str,
helper_dir: Path) -> None:
self._helper_dir = helper_dir
super().__init__(generation, key_path, passphrase)
def _create_helper(self) -> Path:
helper = self._helper_dir / ("askpass-" + secrets.token_hex(8))
_write_private(helper, _ASKPASS_SOURCE)
helper.chmod(0o700)
self._helper_path = helper
return helper
class DatabaseRemoteHostManager(RemoteHostManager):
"""Existing SSH workflow, with encrypted DB persistence and tmpfs keys."""
@staticmethod
def _process_start_ticks(pid: int) -> str | None:
"""Linux process birth marker, to distinguish a recycled PID."""
try:
content = Path(f"/proc/{pid}/stat").read_text(encoding="ascii")
fields = content[content.rfind(")") + 2:].split()
return fields[19] # /proc stat field 22; tail starts at field 3.
except (FileNotFoundError, IndexError, OSError, ValueError):
return None
@classmethod
def _clean_stale_runtime(cls, parent: Path) -> None:
"""Remove only our private, marked dirs whose exact owner process died."""
try:
entries = list(parent.iterdir())
except OSError:
return
for entry in entries:
match = _RUNTIME_NAME.fullmatch(entry.name)
if match is None:
continue
try:
info = entry.lstat()
if (not stat.S_ISDIR(info.st_mode) or info.st_uid != os.geteuid()
or stat.S_IMODE(info.st_mode) != 0o700):
continue
marker = entry / ".owner"
marker_info = marker.lstat()
if (not stat.S_ISREG(marker_info.st_mode)
or marker_info.st_uid != os.geteuid()
or stat.S_IMODE(marker_info.st_mode) != 0o600):
continue
owner = marker.read_text(encoding="ascii").strip().split(":")
pid = int(match.group(1))
if len(owner) != 2 or owner[0] != str(pid) or not owner[1].isdigit():
continue
birth = cls._process_start_ticks(pid)
if birth is None or birth != owner[1]:
shutil.rmtree(entry)
except (OSError, UnicodeError, ValueError):
# Never prune a directory whose ownership cannot be proven.
continue
def __init__(
self, store: DatabaseStore, data_dir: Path, *, ssh_binary: str = "ssh",
runtime_parent: Path | None = None, **kwargs: Any,
) -> None:
self.store = store
if Path(data_dir).is_symlink():
raise RemoteHostError("面板数据目录不能是符号链接", 500)
self._persistent_dir = Path(data_dir).resolve()
self._persistent_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
if stat.S_IMODE(self._persistent_dir.stat().st_mode) & 0o077:
raise RemoteHostError("面板数据目录权限不安全", 500)
wrapper_dir = self._persistent_dir / "runtime-wrappers"
if wrapper_dir.is_symlink():
raise RemoteHostError("SSH 包装器目录不能是符号链接", 500)
wrapper_dir.mkdir(mode=0o700, exist_ok=True)
if stat.S_IMODE(wrapper_dir.stat().st_mode) & 0o077:
raise RemoteHostError("SSH 包装器目录权限不安全", 500)
self._wrapper_dir = wrapper_dir
self._wrapper_paths: set[Path] = set()
if runtime_parent is None:
if sys.platform == "linux":
runtime_parent = Path("/dev/shm")
if not runtime_parent.is_dir() or not os.access(runtime_parent, os.W_OK):
raise RemoteHostError("/dev/shm 不可用,无法安全存放临时 SSH 密钥", 500)
else:
# A disk-backed fallback would leave the decrypted SSH key in
# data/ after an unclean shutdown. Tests may supply an
# explicit isolated runtime parent, but production requires
# the Linux tmpfs path above.
raise RemoteHostError("数据库模式仅支持 Linux 的 /dev/shm 临时密钥目录", 500)
if sys.platform == "linux":
self._clean_stale_runtime(Path(runtime_parent))
# SSHAgentSession requires a socket path under 100 bytes. The fixed
# `generations/gen-.../agent-...sock` suffix leaves only a tiny prefix
# budget under /dev/shm on Linux, so mkdtemp's eight-byte suffix is
# too long for systems with seven-digit PIDs.
self._runtime_dir = None
for _attempt in range(16):
candidate = Path(runtime_parent) / f"v{os.getpid()}-{secrets.token_hex(2)}"
try:
candidate.mkdir(mode=0o700)
except FileExistsError:
continue
self._runtime_dir = candidate
break
if self._runtime_dir is None:
raise RemoteHostError("无法创建独立的 SSH 临时目录", 500)
self._runtime_dir.chmod(0o700)
if sys.platform == "linux":
birth = self._process_start_ticks(os.getpid())
if birth is None:
shutil.rmtree(self._runtime_dir, ignore_errors=True)
raise RemoteHostError("无法确认面板进程身份,拒绝存放 SSH 密钥", 500)
_write_private(self._runtime_dir / ".owner",
f"{os.getpid()}:{birth}\n".encode("ascii"))
try:
kwargs.setdefault(
"agent_factory",
lambda generation, key_path, passphrase: _DatabaseSSHAgentSession(
generation, key_path, passphrase, self._wrapper_dir,
),
)
super().__init__(
self._runtime_dir, ssh_binary=ssh_binary,
ssh_user_config_path=self._runtime_dir / ".ssh" / "config",
**kwargs,
)
self._restore_current()
except BaseException:
shutil.rmtree(self._runtime_dir, ignore_errors=True)
for wrapper in self._wrapper_paths:
wrapper.unlink(missing_ok=True)
raise
def _wrapper_for(self, generation: Path) -> Path:
return self._wrapper_dir / generation.name
def _write_wrapper(self, generation: Path) -> Path:
destination = self._wrapper_for(generation)
source = (
"#!/usr/bin/env python3\n"
"import os\nimport sys\n"
f"os.execvp({self.ssh_binary!r}, "
f"[{self.ssh_binary!r}, '-F', {str(generation / 'config')!r}, *sys.argv[1:]])\n"
)
_write_private(destination, source.encode("ascii"))
destination.chmod(0o700)
self._wrapper_paths.add(destination)
return destination
def stage(self, profile, confirmed_fingerprint: str) -> DatabaseStagedHost:
staged = super().stage(profile, confirmed_fingerprint)
try:
wrapper = self._write_wrapper(staged.path)
except BaseException:
super().abort(staged)
raise
return DatabaseStagedHost(staged, wrapper)
def abort(self, staged: StagedHost) -> None:
super().abort(staged)
wrapper = self._wrapper_for(staged.path)
wrapper.unlink(missing_ok=True)
self._wrapper_paths.discard(wrapper)
def _staged_record(self, staged: StagedHost) -> dict:
try:
return {
"metadata": staged.metadata,
"private_key": (staged.path / "id_private").read_text(encoding="ascii"),
"known_hosts": (staged.path / "known_hosts").read_text(encoding="ascii"),
"identity_public": (
(staged.path / "identity.pub").read_text(encoding="ascii")
if (staged.path / "identity.pub").exists() else None
),
}
except (OSError, UnicodeError) as exc:
raise RemoteHostError("暂存宿主机密钥无法读取", 500) from exc
def commit(self, staged: StagedHost) -> dict[str, Any]:
self._check_staged(staged)
if not staged.tested:
raise RemoteHostError("保存前必须先测试宿主机连接", 409)
# Check the runtime activation preconditions before committing DB.
self._ensure_user_ssh_config()
previous = self.store.get("host", "current")
payload = json.dumps(self._staged_record(staged), ensure_ascii=False,
separators=(",", ":"))
self.store.set("host", "current", payload)
try:
return super().commit(staged)
except BaseException:
if previous is None:
self.store.delete("host", "current")
else:
self.store.set("host", "current", previous)
raise
def _restore_current(self) -> None:
raw = self.store.get("host", "current")
if raw is None:
return
try:
record = json.loads(raw)
metadata = record["metadata"]
host = _validate_host(metadata["host"])
port = _validate_port(metadata["port"])
storage_pool = _validate_pool_selector(metadata["storage_pool"], "磁盘池")
iso_pool = _validate_pool_selector(metadata["iso_pool"], "ISO 池")
default_network = _validate_network_selector(metadata["default_network"])
private_key = _validate_private_key(record["private_key"])
known_hosts = record["known_hosts"].strip()
key_type, encoded = _key_parts(known_hosts)
if (not known_hosts.startswith(SSH_ALIAS + " ")
or metadata["fingerprint"] != _fingerprint(f"{key_type} {encoded}")):
raise ValueError("Host key mismatch")
encrypted = bool(metadata["private_key_encrypted"])
identity_public = record["identity_public"]
if encrypted and (not isinstance(identity_public, str)
or len(identity_public.split()) < 2):
raise ValueError("Encrypted host identity is missing")
except (KeyError, TypeError, ValueError, RemoteHostError, UnicodeError) as exc:
raise RemoteHostError("数据库宿主机配置损坏", 500) from exc
self._ensure_storage()
generation = self.data_dir / "generations" / ("gen-" + secrets.token_hex(16))
generation.mkdir(mode=0o700)
try:
_write_private(generation / "id_private", private_key)
_write_private(generation / "known_hosts", (known_hosts + "\n").encode("ascii"))
identity_path = generation / "id_private"
if encrypted:
_write_private(generation / "identity.pub", identity_public.encode("ascii"))
identity_path = generation / "identity.pub"
config_text = (
f"Host {SSH_ALIAS}\n"
f" HostName {host}\n"
f" Port {port}\n"
" User root\n"
f" IdentityFile {_quoted_path(identity_path)}\n"
f" UserKnownHostsFile {_quoted_path(generation / 'known_hosts')}\n"
" GlobalKnownHostsFile /dev/null\n"
f" HostKeyAlias {SSH_ALIAS}\n"
" HostKeyAlgorithms ssh-ed25519\n"
" StrictHostKeyChecking yes\n"
" VerifyHostKeyDNS no\n"
" BatchMode yes\n"
" IdentitiesOnly yes\n"
" IdentityAgent none\n"
" PreferredAuthentications publickey\n"
" PasswordAuthentication no\n"
" KbdInteractiveAuthentication no\n"
" GSSAPIAuthentication no\n"
" ForwardAgent no\n"
" ProxyCommand none\n"
" ProxyJump none\n"
" CanonicalizeHostname no\n"
" ControlMaster no\n"
" ControlPath none\n"
" UpdateHostKeys no\n"
" RequestTTY no\n"
" ServerAliveInterval 15\n"
" ServerAliveCountMax 2\n"
" ConnectTimeout 10\n"
)
_write_private(generation / "config", config_text.encode("ascii"))
_write_private(generation / "profile.json", json.dumps(
{**metadata, "host": host, "port": port,
"storage_pool": storage_pool, "iso_pool": iso_pool,
"default_network": default_network},
ensure_ascii=False,
).encode("utf-8"))
wrapper = self._write_wrapper(generation)
self._ensure_user_ssh_config()
temporary_link = self.data_dir / (".current-" + secrets.token_hex(8))
temporary_link.symlink_to(generation)
os.replace(temporary_link, self.data_dir / "current")
assert wrapper.exists()
except BaseException:
shutil.rmtree(generation, ignore_errors=True)
raise
@property
def libvirt_uri(self) -> str:
generation = self._current_generation()
if generation is None:
return LIBVIRT_URI
return f"{LIBVIRT_URI}&command={quote(str(self._wrapper_for(generation)), safe='/')}"
def current(self) -> dict[str, Any] | None:
profile = super().current()
if profile is None:
return None
profile["libvirt_uri"] = self.libvirt_uri
return profile
def close(self) -> None:
super().close()
shutil.rmtree(self._runtime_dir, ignore_errors=True)
for wrapper in self._wrapper_paths:
wrapper.unlink(missing_ok=True)
self._wrapper_paths.clear()
def make_components(
data_dir: Path, db_config: Mapping[str, Any], master_key: bytes,
ssh_binary: str = "ssh",
) -> tuple[DatabasePanelState, DatabaseRemoteHostManager, DatabaseTemplateStore, DatabaseStore]:
"""Create ready-to-use DB-backed application components."""
store = DatabaseStore(db_config, master_key)
state = DatabasePanelState(data_dir, store)
manager = DatabaseRemoteHostManager(store, data_dir, ssh_binary=ssh_binary)
templates = DatabaseTemplateStore(store)
return state, manager, templates, store

@ -0,0 +1,237 @@
"""Private, encrypted bootstrap configuration for the panel database.
The database cannot contain its own connection password. The only durable
local state is therefore a 0600 encryption key, an encrypted connection
document and the one-time setup token (until an administrator is created).
"""
from __future__ import annotations
import base64
import fcntl
import hmac
import ipaddress
import json
import os
import re
import secrets
import stat
import tempfile
import threading
from contextlib import contextmanager
from pathlib import Path
from typing import Callable, Mapping, TypeVar
from cryptography.exceptions import InvalidTag
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
_AAD = b"virsh-panel/database-bootstrap/v1"
_DATABASE_NAME = re.compile(r"[A-Za-z0-9_]{1,64}\Z")
_DNS_LABEL = re.compile(r"[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\Z")
_T = TypeVar("_T")
class DatabaseSetupError(Exception):
def __init__(self, message: str, status: int = 400) -> None:
super().__init__(message)
self.status = status
def validate_database_config(config: Mapping[str, object]) -> dict[str, object]:
"""Normalize user-entered connection parameters without SQL interpolation."""
host = config.get("host")
port = config.get("port")
database = config.get("database")
username = config.get("username")
password = config.get("password")
if not isinstance(host, str) or not host or len(host) > 253 or host != host.strip():
raise DatabaseSetupError("数据库地址格式无效")
try:
ipaddress.ip_address(host)
except ValueError:
if not all(_DNS_LABEL.fullmatch(label) for label in host.split(".")):
raise DatabaseSetupError("数据库地址必须是 IP 或 DNS 名称") from None
host = host.lower()
if isinstance(port, bool) or not isinstance(port, int) or not 1 <= port <= 65535:
raise DatabaseSetupError("数据库端口必须介于 1 到 65535")
if not isinstance(database, str) or not _DATABASE_NAME.fullmatch(database):
raise DatabaseSetupError("数据库名仅支持 1 至 64 位字母、数字和下划线")
if (not isinstance(username, str) or not 1 <= len(username) <= 128
or any(ord(char) < 33 or ord(char) == 127 for char in username)):
raise DatabaseSetupError("数据库用户名格式无效")
if not isinstance(password, str) or not 1 <= len(password) <= 1024 or "\x00" in password:
raise DatabaseSetupError("数据库密码不能为空或格式无效")
return {
"host": host, "port": port, "database": database,
"username": username, "password": password,
}
class DatabaseBootstrap:
def __init__(self, data_dir: Path) -> None:
requested = Path(data_dir)
if requested.is_symlink():
raise ValueError("面板数据目录不能是符号链接")
self.data_dir = requested.resolve()
self.data_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
info = self.data_dir.lstat()
if not stat.S_ISDIR(info.st_mode) or info.st_mode & 0o077:
raise ValueError("面板数据目录权限必须为 0700")
self.config_file = self.data_dir / "database-config.json"
self.key_file = self.data_dir / "master.key"
self.token_file = self.data_dir / "setup-token"
self.lock_file = self.data_dir / ".database.lock"
self._lock = threading.RLock()
@staticmethod
def _read_private(path: Path) -> bytes:
info = path.lstat()
if not stat.S_ISREG(info.st_mode) or info.st_mode & 0o077:
raise ValueError(f"敏感配置文件权限必须为 0600:{path.name}")
flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
descriptor = os.open(path, flags)
try:
return os.read(descriptor, 1024 * 1024 + 1)
finally:
os.close(descriptor)
def _sync_directory(self) -> None:
descriptor = os.open(self.data_dir, os.O_RDONLY)
try:
os.fsync(descriptor)
finally:
os.close(descriptor)
def _write_private(self, path: Path, content: bytes) -> None:
descriptor, raw_path = tempfile.mkstemp(prefix=f".{path.name}-", dir=self.data_dir)
try:
os.fchmod(descriptor, 0o600)
with os.fdopen(descriptor, "wb") as stream:
stream.write(content)
stream.flush()
os.fsync(stream.fileno())
os.replace(raw_path, path)
self._sync_directory()
finally:
if os.path.exists(raw_path):
os.unlink(raw_path)
@contextmanager
def _exclusive(self):
with self._lock:
flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0)
descriptor = os.open(self.lock_file, flags, 0o600)
try:
info = os.fstat(descriptor)
if not stat.S_ISREG(info.st_mode) or info.st_mode & 0o077:
raise ValueError("数据库初始化锁文件权限必须为 0600")
fcntl.flock(descriptor, fcntl.LOCK_EX)
try:
yield
finally:
fcntl.flock(descriptor, fcntl.LOCK_UN)
finally:
os.close(descriptor)
def configured(self) -> bool:
return self.config_file.exists()
def ensure_token(self) -> str:
"""Create once; database and administrator setup share the same token."""
with self._exclusive():
try:
token = self._read_private(self.token_file).decode("ascii").strip()
if len(token) < 32:
raise ValueError("初始化令牌文件无效")
return token
except FileNotFoundError:
token = secrets.token_urlsafe(32)
flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
descriptor = os.open(self.token_file, flags, 0o600)
try:
with os.fdopen(descriptor, "wb") as stream:
stream.write((token + "\n").encode("ascii"))
stream.flush()
os.fsync(stream.fileno())
self._sync_directory()
except BaseException:
self.token_file.unlink(missing_ok=True)
raise
return token
def master_key(self, *, create: bool = False) -> bytes:
try:
key = self._read_private(self.key_file)
except FileNotFoundError:
if not create:
raise ValueError("数据库加密主密钥不存在") from None
key = secrets.token_bytes(32)
flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
try:
descriptor = os.open(self.key_file, flags, 0o600)
except FileExistsError:
return self.master_key()
try:
with os.fdopen(descriptor, "wb") as stream:
stream.write(key)
stream.flush()
os.fsync(stream.fileno())
self._sync_directory()
except BaseException:
self.key_file.unlink(missing_ok=True)
raise
if len(key) != 32:
raise ValueError("数据库加密主密钥无效")
return key
def load_config(self) -> dict[str, object] | None:
try:
content = self._read_private(self.config_file)
except FileNotFoundError:
return None
try:
envelope = json.loads(content)
if envelope.get("version") != 1:
raise ValueError("版本无效")
nonce = base64.b64decode(envelope["nonce"], validate=True)
ciphertext = base64.b64decode(envelope["ciphertext"], validate=True)
if len(nonce) != 12 or len(ciphertext) > 4096:
raise ValueError("密文无效")
raw = AESGCM(self.master_key()).decrypt(nonce, ciphertext, _AAD)
return validate_database_config(json.loads(raw))
except (KeyError, TypeError, ValueError, InvalidTag) as exc:
raise ValueError("数据库连接配置损坏或加密主密钥不匹配") from exc
def configure(
self, config: Mapping[str, object], setup_token: str,
connect: Callable[[dict[str, object], bytes], _T],
) -> _T:
"""Verify token and DB access, then atomically commit encrypted config."""
normalized = validate_database_config(config)
with self._exclusive():
if self.configured():
raise DatabaseSetupError("数据库已经配置", 409)
try:
expected = self._read_private(self.token_file).decode("ascii").strip()
except FileNotFoundError as exc:
raise DatabaseSetupError("初始化令牌不可用,请重启面板后查看终端输出", 503) from exc
if (not isinstance(setup_token, str)
or not hmac.compare_digest(setup_token, expected)):
raise DatabaseSetupError("初始化令牌无效", 403)
key = self.master_key(create=True)
result = connect(normalized, key)
nonce = secrets.token_bytes(12)
plaintext = json.dumps(normalized, ensure_ascii=False,
separators=(",", ":")).encode("utf-8")
encrypted = AESGCM(key).encrypt(nonce, plaintext, _AAD)
envelope = {
"version": 1,
"nonce": base64.b64encode(nonce).decode("ascii"),
"ciphertext": base64.b64encode(encrypted).decode("ascii"),
}
self._write_private(
self.config_file,
(json.dumps(envelope, separators=(",", ":")) + "\n").encode("ascii"),
)
return result

@ -0,0 +1,109 @@
"""Entry point for the separate virsh-panel-update.service one-shot unit."""
from __future__ import annotations
import argparse
import json
import logging
import subprocess
import time
from urllib.error import URLError
from urllib.request import urlopen
from .config import PROJECT_DIR, Settings
from .database import DatabaseError, DatabaseStore
from .database_bootstrap import DatabaseBootstrap
from .updater import UpdateError, Updater
LOG = logging.getLogger(__name__)
_WEB_UNIT = "virsh-panel.service"
_HEALTH_URL = "http://127.0.0.1:8000/api/v1/health"
def restart_web_service() -> None:
"""Restart the main unit and wait for its local health endpoint."""
try:
result = subprocess.run(
["/usr/bin/systemctl", "restart", _WEB_UNIT],
capture_output=True,
text=True,
timeout=90,
check=False,
)
except (OSError, subprocess.TimeoutExpired) as exc:
raise UpdateError("面板服务重启失败,请检查 systemd 日志", 500) from exc
if result.returncode != 0:
# systemctl output is intentionally not returned: it may contain
# environment details from another unit or configuration.
raise UpdateError("面板服务重启失败,请检查 systemd 日志", 500)
deadline = time.monotonic() + 45
while time.monotonic() < deadline:
try:
with urlopen(_HEALTH_URL, timeout=2) as response:
payload = json.load(response)
if response.status == 200 and isinstance(payload, dict) and payload.get("status") == "ok":
return
except (OSError, URLError, ValueError):
pass
time.sleep(1)
raise UpdateError("新版本服务未通过本机健康检查,请检查面板日志", 500)
def _load_updater() -> tuple[Updater, DatabaseStore]:
settings = Settings.from_env()
bootstrap = DatabaseBootstrap(settings.data_dir)
config = bootstrap.load_config()
if config is None:
raise UpdateError("尚未完成数据库配置,无法运行在线更新", 409)
store = DatabaseStore(config, bootstrap.master_key())
return Updater(PROJECT_DIR, store), store
def finalize_incomplete_job(updater: Updater, store: DatabaseStore) -> bool:
"""Mark an interrupted job failed after the one-shot unit has exited.
This is invoked by systemd ExecStopPost regardless of the main worker's
exit code. Successful/failed jobs are untouched. It is intentionally
idempotent so operators may rerun it while diagnosing a crashed worker.
"""
job_id = store.get_value("update.active_job")
if not job_id:
return False
job = updater.get_job(job_id)
if job is None or job.get("status") not in {"queued", "running"}:
return False
updater.fail_job(
job_id,
"独立更新服务异常退出或超时;请检查更新服务日志和当前 Git 版本,勿直接重复提交",
)
return True
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description="Run or finalize the Virsh Panel update job")
parser.add_argument("--finalize-incomplete", action="store_true")
options = parser.parse_args(argv)
logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
try:
updater, store = _load_updater()
if options.finalize_incomplete:
if finalize_incomplete_job(updater, store):
LOG.warning("interrupted panel update marked failed")
return 0
result = updater.run_pending_job(restart=restart_web_service)
except (UpdateError, DatabaseError, ValueError) as exc:
# Public errors are deliberately credential-free. Never log the DB
# config, Gitea PAT, subprocess output or captured environment.
LOG.error("panel update failed: %s", exc)
return 1
LOG.info(
"panel update finished: job=%s old=%s new=%s updated=%s",
result["job_id"], result.get("old_commit"), result.get("new_commit"), result.get("updated"),
)
return 0
if __name__ == "__main__":
raise SystemExit(main())

@ -0,0 +1,539 @@
"""Conservative Git updater for the panel's own, fixed Gitea repository.
The web process may inspect a checkout and enqueue a job. ``run_pending_job``
must run in a separate, privileged one-shot service: the regular web service
has a read-only code directory, and restarting it from within a request is
unreliable. The caller supplies the restart/health-check callback.
The personal access token is stored by the injected encrypted database store.
It never appears in a Git URL, command argument, temporary file, or returned
API data. A private, short-lived askpass program receives it only in the
child's environment while an HTTPS Git operation is in progress.
"""
from __future__ import annotations
import fcntl
import json
import os
import re
import secrets
import stat
import subprocess
import tempfile
import threading
import time
from contextlib import contextmanager
from pathlib import Path
from typing import Callable, Protocol
REPOSITORY_URL = "https://g.luoli.live/root/virt.git"
BRANCH = "main"
_TOKEN_KEY = "update.gitea_access_token"
_ACTIVE_JOB_KEY = "update.active_job"
_JOB_PREFIX = "update.job."
_HEX_COMMIT = re.compile(r"(?:[0-9a-f]{40}|[0-9a-f]{64})\Z")
_JOB_ID = re.compile(r"[A-Za-z0-9_-]{16,64}\Z")
class UpdateStore(Protocol):
"""Small persistence surface supplied by the encrypted database layer."""
def get_secret(self, name: str) -> str | None: ...
def set_secret(self, name: str, value: str) -> None: ...
def delete_secret(self, name: str) -> None: ...
def get_value(self, name: str) -> str | None: ...
def set_value(self, name: str, value: str) -> None: ...
class UpdateError(Exception):
"""A safe error suitable for returning to the authenticated operator."""
def __init__(self, message: str, status: int = 400) -> None:
super().__init__(message)
self.status = status
class Updater:
"""Read/check/advance only the pinned ``main`` branch of the panel repo."""
def __init__(
self,
repo_dir: Path,
secret_store: UpdateStore,
*,
git_binary: str = "git",
runner: Callable[..., subprocess.CompletedProcess[str]] | None = None,
) -> None:
self.repo_dir = Path(repo_dir).absolute()
self.store = secret_store
self.git_binary = git_binary
self._run = runner or subprocess.run
self._lock = threading.RLock()
def settings(self) -> dict:
"""Return only public configuration, never the stored access token."""
active_id = self.store.get_value(_ACTIVE_JOB_KEY)
active_job = self.get_job(active_id) if active_id else None
result = {
"repository": REPOSITORY_URL,
"branch": BRANCH,
"token_configured": bool(self.store.get_secret(_TOKEN_KEY)),
"checkout_ready": False,
"current_commit": None,
"last_job_id": active_id if active_job is not None else None,
"active_job_id": (
active_id if active_job is not None
and active_job.get("status") in {"queued", "running"} else None
),
}
try:
result["current_commit"] = self._checkout_head(require_clean=False)
result["checkout_ready"] = True
except UpdateError as exc:
result["checkout_error"] = str(exc)
return result
def set_token(self, token: str) -> None:
if (
not isinstance(token, str)
or not 16 <= len(token) <= 4096
or token != token.strip()
or any(ord(char) < 33 or ord(char) > 126 for char in token)
):
raise UpdateError("Gitea 访问令牌格式无效")
self.store.set_secret(_TOKEN_KEY, token)
def clear_token(self) -> None:
self.store.delete_secret(_TOKEN_KEY)
def _environment(self) -> dict[str, str]:
# Do not inherit GIT_TRACE, Git configuration, proxy overrides or
# GIT_SSL_NO_VERIFY from the panel service environment.
return {
"PATH": os.defpath,
"LANG": "C",
"LC_ALL": "C",
"GIT_CONFIG_NOSYSTEM": "1",
"GIT_CONFIG_GLOBAL": os.devnull,
"GIT_TERMINAL_PROMPT": "0",
"GIT_OPTIONAL_LOCKS": "0",
"GIT_ALLOW_PROTOCOL": "https",
}
@contextmanager
def _git_auth(self):
token = self.store.get_secret(_TOKEN_KEY)
if not token:
raise UpdateError("请先在面板中设置 Gitea 访问令牌", 409)
with tempfile.TemporaryDirectory(prefix="virsh-panel-askpass-") as directory:
askpass = Path(directory) / "askpass"
# This script contains no credential. Git passes a prompt as one
# argument; the token is handed to the Git child only in memory.
askpass.write_text(
"#!/bin/sh\n"
"case \"$1\" in\n"
" *sername*|*SERNAM*) printf '%s\\n' \"$VIRSH_PANEL_GIT_USERNAME\" ;;\n"
" *assword*|*ASSWORD*) printf '%s\\n' \"$VIRSH_PANEL_GIT_TOKEN\" ;;\n"
" *) exit 1 ;;\n"
"esac\n",
encoding="ascii",
)
askpass.chmod(0o700)
env = self._environment()
env.update({
"GIT_ASKPASS": str(askpass),
"VIRSH_PANEL_GIT_USERNAME": "root",
"VIRSH_PANEL_GIT_TOKEN": token,
})
yield env
def _git(
self,
*args: str,
timeout: float = 15,
environment: dict[str, str] | None = None,
error: str = "Git 操作失败,请检查面板日志",
allowed_codes: tuple[int, ...] = (0,),
) -> subprocess.CompletedProcess[str]:
argv = [
self.git_binary,
"-c", "core.hooksPath=/dev/null",
"-c", "http.followRedirects=false",
"-c", "http.sslVerify=true",
"-c", "http.extraHeader=",
"-c", "credential.helper=",
"-c", "fetch.recurseSubmodules=false",
*args,
]
try:
result = self._run(
argv,
cwd=self.repo_dir,
env=environment or self._environment(),
capture_output=True,
text=True,
timeout=timeout,
check=False,
)
except (OSError, subprocess.TimeoutExpired) as exc:
# Never include stderr, a URL, or a token in a public exception.
raise UpdateError(error, 502) from exc
if result.returncode not in allowed_codes:
raise UpdateError(error, 502)
return result
def _checkout_head(self, *, require_clean: bool) -> str:
if self.repo_dir.is_symlink() or not self.repo_dir.is_dir():
raise UpdateError("面板目录不是有效的 Git 检出目录", 409)
repo_info = self.repo_dir.lstat()
if repo_info.st_uid != os.geteuid() or repo_info.st_mode & 0o022:
raise UpdateError("面板目录必须由当前服务账号拥有,且不能允许组或其他用户写入", 409)
git_dir = self.repo_dir / ".git"
if git_dir.is_symlink() or not git_dir.is_dir():
raise UpdateError("面板必须从完整 Git 仓库部署,不能使用压缩包或工作树", 409)
try:
info = git_dir.lstat()
except OSError as exc:
raise UpdateError("无法读取面板 Git 仓库", 409) from exc
if not stat.S_ISDIR(info.st_mode):
raise UpdateError("面板 Git 仓库格式无效", 409)
if info.st_uid != os.geteuid() or info.st_mode & 0o022:
raise UpdateError("面板 Git 仓库权限不安全,已拒绝在线更新", 409)
top = self._git("rev-parse", "--show-toplevel", error="无法识别面板 Git 仓库").stdout.strip()
if Path(top).resolve() != self.repo_dir.resolve():
raise UpdateError("Git 仓库根目录与面板程序目录不一致", 409)
branch = self._git(
"symbolic-ref", "--quiet", "--short", "HEAD",
error="面板 Git 仓库当前不是 main 分支",
).stdout.strip()
if branch != BRANCH:
raise UpdateError("面板只允许从 main 分支更新", 409)
configured_urls = self._git(
"config", "--local", "--get-all", "remote.origin.url",
error="面板 Git 仓库缺少 origin 地址",
).stdout.splitlines()
if configured_urls != [REPOSITORY_URL]:
raise UpdateError("Git origin 必须是已指定的 Gitea 私有仓库,且不得包含凭据", 409)
# url.*.insteadOf could silently rewrite our explicit HTTPS URL to a
# different server and disclose the access token. Refuse it outright.
rewrites = self._git(
"config", "--local", "--name-only", "--get-regexp", r"^url\..*\.insteadof$",
allowed_codes=(0, 1),
error="无法检查 Git URL 重写配置",
)
if rewrites.returncode == 0:
raise UpdateError("Git 仓库配置了 URL 重写,无法安全更新", 409)
head = self._git("rev-parse", "HEAD", error="无法读取当前面板版本").stdout.strip()
if not _HEX_COMMIT.fullmatch(head):
raise UpdateError("当前 Git 提交标识无效", 409)
if require_clean:
status = self._git(
"status", "--porcelain=v1", "--untracked-files=all",
error="无法检查面板文件变更",
).stdout
if status.strip():
raise UpdateError("面板目录存在未提交或未跟踪文件;为防止覆盖,请先处理这些文件", 409)
return head
def _remote_head(self) -> str:
with self._git_auth() as env:
output = self._git(
"ls-remote", "--exit-code", "--", REPOSITORY_URL, f"refs/heads/{BRANCH}",
environment=env,
timeout=45,
error="无法读取 Gitea 私有仓库;请检查访问令牌、TLS 证书和网络",
).stdout.strip()
fields = output.split()
if len(fields) != 2 or fields[1] != f"refs/heads/{BRANCH}" or not _HEX_COMMIT.fullmatch(fields[0]):
raise UpdateError("Gitea 返回了无效的分支信息", 502)
return fields[0]
def check(self) -> dict:
"""Inspect the remote head without altering the local checkout."""
with self._lock:
current = self._checkout_head(require_clean=True)
remote = self._remote_head()
return {
"repository": REPOSITORY_URL,
"branch": BRANCH,
"current_commit": current,
"remote_commit": remote,
"status": "current" if current == remote else "update_available",
}
def _fetch_remote(self) -> str:
with self._git_auth() as env:
self._git(
"fetch", "--no-tags", "--no-recurse-submodules", "--",
REPOSITORY_URL, f"refs/heads/{BRANCH}",
environment=env,
timeout=300,
error="无法从 Gitea 拉取更新;请检查访问令牌、TLS 证书和网络",
)
head = self._git("rev-parse", "FETCH_HEAD", error="无法识别已下载的更新版本").stdout.strip()
if not _HEX_COMMIT.fullmatch(head):
raise UpdateError("下载的 Git 提交标识无效", 502)
return head
def _assert_safe_tree(self, target: str) -> None:
listing = self._git(
"ls-tree", "-r", "--name-only", target, "--", "data", ".venv", ".gitmodules",
error="无法检查更新文件清单",
).stdout
if listing:
raise UpdateError("更新包含面板数据目录、虚拟环境或子模块配置,已拒绝覆盖", 409)
def _install_requirements(self, target: str) -> None:
venv = self.repo_dir / ".venv"
python = venv / "bin" / "python"
if venv.is_symlink() or not venv.is_dir() or not python.exists():
raise UpdateError("未找到面板虚拟环境 .venv,不能自动安装更新依赖", 409)
requirements = self._git(
"show", f"{target}:requirements.txt",
error="更新版本缺少 requirements.txt,已取消更新",
).stdout
if not requirements or len(requirements) > 262144:
raise UpdateError("更新版本的依赖清单无效", 409)
with tempfile.TemporaryDirectory(prefix="virsh-panel-requirements-") as directory:
path = Path(directory) / "requirements.txt"
path.write_text(requirements, encoding="utf-8")
path.chmod(0o600)
env = {
"PATH": os.defpath,
"LANG": "C",
"LC_ALL": "C",
"PIP_NO_INPUT": "1",
"PIP_NO_CACHE_DIR": "1",
"PIP_DISABLE_PIP_VERSION_CHECK": "1",
}
try:
result = self._run(
[str(python), "-m", "pip", "install", "--no-input", "-r", str(path)],
cwd=self.repo_dir,
env=env,
capture_output=True,
text=True,
timeout=900,
check=False,
)
except (OSError, subprocess.TimeoutExpired) as exc:
raise UpdateError("更新依赖安装失败;面板代码尚未切换", 502) from exc
if result.returncode != 0:
raise UpdateError("更新依赖安装失败;面板代码尚未切换", 502)
@contextmanager
def _apply_lock(self):
git_dir = self.repo_dir / ".git"
flags = os.O_CREAT | os.O_RDWR | getattr(os, "O_NOFOLLOW", 0)
try:
descriptor = os.open(git_dir / "virsh-panel-update.lock", flags, 0o600)
except OSError as exc:
raise UpdateError("无法获取面板更新锁;请确认独立更新服务有代码目录写权限", 500) from exc
try:
info = os.fstat(descriptor)
if not stat.S_ISREG(info.st_mode) or info.st_mode & 0o077:
raise UpdateError("面板更新锁文件权限不安全", 500)
fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
except BlockingIOError as exc:
os.close(descriptor)
raise UpdateError("另一个更新任务正在运行", 409) from exc
except BaseException:
os.close(descriptor)
raise
try:
yield
finally:
fcntl.flock(descriptor, fcntl.LOCK_UN)
os.close(descriptor)
def apply(
self, *, progress: Callable[[str], None] | None = None,
expected_current_commit: str | None = None,
expected_remote_commit: str | None = None,
) -> dict:
"""Install dependencies, then fast-forward code. No force/reset is used."""
report = progress or (lambda _phase: None)
with self._lock:
# Validate before creating a lock inside .git.
current = self._checkout_head(require_clean=True)
with self._apply_lock():
# Re-check after acquiring the cross-process lock.
current = self._checkout_head(require_clean=True)
if expected_current_commit is not None and current != expected_current_commit:
raise UpdateError("面板本地版本已变化,请重新检查更新后再执行", 409)
report("正在从 Gitea 下载更新")
target = self._fetch_remote()
if expected_remote_commit is not None and target != expected_remote_commit:
raise UpdateError("Gitea main 分支已变化,请重新检查更新后再执行", 409)
self._assert_safe_tree(target)
ancestry = self._git(
"merge-base", "--is-ancestor", current, target,
allowed_codes=(0, 1),
error="无法验证更新提交历史",
)
if ancestry.returncode != 0:
raise UpdateError("远端 main 分支与当前版本已分叉,已拒绝自动覆盖", 409)
if target == current:
return {"updated": False, "old_commit": current, "new_commit": target}
report("正在安装新版本依赖")
self._install_requirements(target)
# Keep an immutable rollback pointer for manual recovery. A
# forced reset is never part of the automatic update path.
rollback_ref = f"refs/virsh-panel/rollback/{int(time.time())}-{secrets.token_hex(4)}"
self._git(
"update-ref", rollback_ref, current,
error="无法保存更新前版本,已取消切换",
)
# Files may have been edited during a long dependency install.
self._checkout_head(require_clean=True)
report("正在切换到新版本")
self._git(
"merge", "--ff-only", "--no-stat", target,
timeout=120,
error="无法快进更新代码;请检查面板目录与 Git 日志",
)
installed = self._checkout_head(require_clean=True)
if installed != target:
raise UpdateError("更新后的 Git 提交与预期不符,请人工核查", 500)
return {
"updated": True,
"old_commit": current,
"new_commit": target,
"rollback_ref": rollback_ref,
}
def _job_key(self, job_id: str) -> str:
if not isinstance(job_id, str) or not _JOB_ID.fullmatch(job_id):
raise UpdateError("更新任务编号无效", 404)
return _JOB_PREFIX + job_id
def get_job(self, job_id: str) -> dict | None:
raw = self.store.get_value(self._job_key(job_id))
if raw is None:
return None
try:
job = json.loads(raw)
except (TypeError, ValueError) as exc:
raise UpdateError("更新任务记录损坏", 500) from exc
if not isinstance(job, dict) or job.get("job_id") != job_id:
raise UpdateError("更新任务记录损坏", 500)
return job
def _save_job(self, job: dict) -> None:
self.store.set_value(self._job_key(job["job_id"]), json.dumps(job, ensure_ascii=False))
def create_job(
self, *, expected_current_commit: str | None = None,
expected_remote_commit: str | None = None,
) -> dict:
"""Enqueue one persisted job; the web layer then starts the worker."""
with self._lock:
current = self._checkout_head(require_clean=True)
if expected_current_commit is not None:
if not _HEX_COMMIT.fullmatch(expected_current_commit):
raise UpdateError("要更新的当前版本标识无效", 422)
if current != expected_current_commit:
raise UpdateError("面板本地版本已变化,请重新检查更新后再执行", 409)
if not self.store.get_secret(_TOKEN_KEY):
raise UpdateError("请先在面板中设置 Gitea 访问令牌", 409)
if expected_remote_commit is not None:
if not _HEX_COMMIT.fullmatch(expected_remote_commit):
raise UpdateError("要更新的远端版本标识无效", 422)
if self._remote_head() != expected_remote_commit:
raise UpdateError("Gitea main 分支已变化,请重新检查更新后再执行", 409)
active_id = self.store.get_value(_ACTIVE_JOB_KEY)
if active_id:
active = self.get_job(active_id)
if active is not None and active.get("status") in {"queued", "running"}:
raise UpdateError("已有更新任务正在执行", 409)
job_id = secrets.token_urlsafe(18)
job = {
"job_id": job_id,
"status": "queued",
"phase": "等待独立更新服务启动",
"created_at": int(time.time()),
}
if expected_current_commit is not None:
job["expected_current_commit"] = expected_current_commit
if expected_remote_commit is not None:
job["expected_remote_commit"] = expected_remote_commit
self._save_job(job)
self.store.set_value(_ACTIVE_JOB_KEY, job_id)
return job.copy()
def fail_job(self, job_id: str, message: str) -> dict:
"""Mark a queued/running job failed if the service could not start."""
with self._lock:
job = self.get_job(job_id)
if job is None:
raise UpdateError("更新任务不存在", 404)
if job["status"] not in {"queued", "running"}:
return job
job.update(status="failed", phase="更新失败", error=str(message)[:300], finished_at=int(time.time()))
self._save_job(job)
return job.copy()
def run_pending_job(self, *, restart: Callable[[], None] | None = None) -> dict:
"""Run the queued job in a separate service and persist every phase.
``restart`` should restart the web unit and, ideally, verify its health.
If it fails, the job records that code may already have changed and
exposes the old commit/rollback ref for operator-led recovery.
"""
with self._lock:
job_id = self.store.get_value(_ACTIVE_JOB_KEY)
if not job_id:
raise UpdateError("没有待执行的更新任务", 404)
job = self.get_job(job_id)
if job is None or job.get("status") != "queued":
raise UpdateError("更新任务未处于等待状态;请人工核查后重新提交", 409)
job.update(status="running", phase="正在检查本地仓库", started_at=int(time.time()))
self._save_job(job)
def progress(phase: str) -> None:
with self._lock:
job["phase"] = str(phase)[:200]
self._save_job(job)
applied: dict | None = None
try:
applied = self.apply(
progress=progress,
expected_current_commit=job.get("expected_current_commit"),
expected_remote_commit=job.get("expected_remote_commit"),
)
job.update(applied)
self._save_job(job)
if applied["updated"] and restart is not None:
progress("正在重启面板并检查服务")
restart()
elif applied["updated"]:
# A worker that cannot restart the web service must not
# report a successful one-click update.
raise UpdateError("代码已更新,但未配置自动重启;请人工重启面板服务", 500)
job.update(status="succeeded", phase="更新完成" if applied["updated"] else "已是最新版本",
finished_at=int(time.time()))
self._save_job(job)
return job.copy()
except Exception as exc:
if isinstance(exc, UpdateError):
error = str(exc)
else:
error = "更新失败,请查看独立更新服务日志"
if applied is not None and applied.get("updated"):
error += ";程序代码可能已切换,请人工核查并重启或按回滚引用恢复"
job.update(status="failed", phase="更新失败", error=error, finished_at=int(time.time()))
self._save_job(job)
if isinstance(exc, UpdateError):
raise
raise UpdateError(error, 500) from exc
__all__ = ["BRANCH", "REPOSITORY_URL", "UpdateError", "UpdateStore", "Updater"]
Loading…
Cancel
Save