diff --git a/README.md b/README.md index 96a5801e..7e9ed205 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ 项目提供面板程序、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**。首次打开网页会先配置数据库连接、创建初始账户;该账户的 `admin` 字段初始为 `0`,需由你手工在数据库升为管理员,之后才能在网页配置宿主机和 SMTP。数据库及有建表权限的专用账号需要你事先准备;面板不会安装 MariaDB 或自动创建数据库。旧版 `data/state.json`、`data/templates.json` 和本地宿主机配置**不会自动迁移**。虚拟机定义和虚拟磁盘仍由远端 libvirt/宿主机持有,数据库保存用户、邮箱验证码、虚拟机归属、登录会话、SMTP 设置、模板目录、宿主机连接资料、更新设置、更新任务及虚拟机性能历史等面板数据。 +这一版的持久化面板数据使用 **MariaDB**。首次打开网页会先配置数据库连接、创建初始账户;初始账户可不填写邮箱,由你随后在 MariaDB 手动补齐。之后所有用户**只能使用邮箱和密码登录**,用户名仅用于显示、注册和数据库管理,不能作为登录凭据。初始账户的 `admin` 字段初始为 `0`,需由你手工在数据库升为管理员,之后才能在网页配置宿主机和 SMTP。数据库及有建表权限的专用账号需要你事先准备;面板不会安装 MariaDB 或自动创建数据库。旧版 `data/state.json`、`data/templates.json` 和本地宿主机配置**不会自动迁移**。虚拟机定义和虚拟磁盘仍由远端 libvirt/宿主机持有,数据库保存用户、邮箱验证码、虚拟机归属、登录会话、SMTP 设置、模板目录、宿主机连接资料、更新设置、更新任务及虚拟机性能历史等面板数据。 如果是在旧测试目录上替换代码,旧 `data/generations/` 中的明文 SSH 私钥不会被新版使用,也**不会自动删除**。为避免遗留敏感文件,建议先备份并核对后,在首次运行新版前使用全新的 `data/` 目录;不要未经核对直接删除仍需使用的资料。 @@ -30,6 +30,17 @@ PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -m uvicorn virsh_panel.app:create_app 手工更新版本时请同时替换 `static/index.html`、`static/app.js`、`static/styles.css` 和后端代码,不要只上传页面 HTML;保留原有 `data/` 和数据库。浏览器若出现“已选公网云镜像却仍要求 ISO”,先确认这三个静态文件均为同一版本,再重新打开页面。网页一键更新另有 Git 仓库和更新服务的要求,见下文。 +从仍允许用户名登录的版本升级时,**先检查初始账户的邮箱再替换代码并重启**。旧版可能创建了 `email=NULL` 的初始账户;新版首次创建的账户也可以不填邮箱。这种账户创建后会建立当前浏览器会话,但一旦退出、会话过期或清除 Cookie,在数据库补齐邮箱前就无法再次登录。请先备份数据库,在 MariaDB 中查询并确认准确的账户 ID 与用户名,再将示例邮箱换成你自己的、尚未被其他用户占用的真实邮箱: + +```sql +SELECT id, username, email FROM users; +UPDATE users SET email = LOWER('你的邮箱@example.com'), email_verified = 1 + WHERE id = 1 AND username = '你的初始用户名' AND email IS NULL; +SELECT id, username, email FROM users WHERE id = 1; +``` + +请确认 `UPDATE` 实际影响一行,且查询结果是预期邮箱;否则不要继续升级、退出当前会话或重启,应核对 ID、用户名及已有邮箱。初始账户的邮箱由持有初始化令牌的你设置,不通过公开注册验证码流程。已设置邮箱的现有账户无需再改,升级后直接用其邮箱登录;邮箱不区分大小写。 + 若初始化令牌意外公开、且尚未创建初始账户,请先停止面板,只删除 `/home/virsh-panel/data/setup-token`,再启动面板生成新令牌。不要删除整个 `data/`;新令牌不要再次公开。 按当前需求从 A 的 root 终端运行面板;程序自动将 `data/` 目录及本地加密主密钥限制为 `0700`、`0600`。数据库中的敏感资料采用应用层认证加密,但运行中的 root 面板仍能解密 B 的 root SSH 私钥;只在可信网络和 HTTPS 反代后使用,妥善限制谁能访问 A。A 若启用 SELinux enforcing,还需在真实系统上验证 `/home/virsh-panel` 的访问标签。仓库保留可选 service 文件,但以上启动方式不依赖它。 @@ -41,14 +52,17 @@ PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -m uvicorn virsh_panel.app:create_app ## 首次网页操作 1. 通过你的 HTTPS 域名打开面板,使用启动终端输出中的一次性令牌填写 MariaDB 的地址、端口、已有数据库名、专用账号和密码。数据库账号至少需要在该数据库中建表及读写权限;连接失败时不会保存配置。当前数据库连接尚未提供 TLS 参数,数据库请放在面板本机或可信内网,不要将其端口暴露公网。 -2. 使用同一个令牌创建初始账户。密码只保存为密码哈希;此时 `users.admin=0`,账户虽可登录,但还不能管理宿主机。按照你的要求,面板**不会自动赋予管理员权限**。用有权访问该数据库的账号在 MariaDB 中核对用户名及 ID 后,手工执行下面 SQL;将示例 ID 和用户名换成查询到的初始账户: +2. 使用同一个令牌填写用户名和密码,创建初始账户;此处不要求填写邮箱。密码只保存为密码哈希。此时 `users.admin=0`,账户已建立当前浏览器会话,但还不能管理宿主机。按照你的要求,面板**不会自动赋予管理员权限**。用有权访问该数据库的账号在 MariaDB 中核对用户名及 ID 后,手工执行下面 SQL;将示例 ID、用户名和邮箱换成实际值。**必须在退出当前会话前补齐邮箱**,否则无法再次登录: ```sql - SELECT id, username, admin, approved FROM users; + SELECT id, username, email, admin, approved FROM users; + UPDATE users SET email = LOWER('你的邮箱@example.com'), email_verified = 1 + WHERE id = 1 AND username = '你的初始用户名' AND email IS NULL; UPDATE users SET admin = 1 WHERE id = 1 AND username = '你的初始用户名'; + SELECT id, username, email, admin, approved FROM users WHERE id = 1; ``` - 再刷新面板,权限会从数据库即时读取,不必重启。不要把 `admin=1` 给公开注册用户。 + 核对查询结果中的邮箱和管理员标志后,再刷新面板;权限会从数据库即时读取,不必重启。此后用邮箱登录,不能用用户名登录。不要把 `admin=1` 给公开注册用户。 3. 管理员在网页配置 SMTP 地址、端口、SSL/STARTTLS、发件邮箱及需要时的 SMTP 账号密码;设置加密保存在 MariaDB,页面不回显密码。完成后,访客可用邮箱验证码注册(10 分钟有效,重复发送与输错次数受限);邮箱验证成功即可登录,但须由管理员在“用户审核”批准后才能创建虚拟机。普通用户不能添加宿主机、导入云镜像模板、配置 SMTP 或更新面板,也看不到其他人的虚拟机和初始密码。面板外创建或管理员创建的未归属虚拟机仅管理员可见;当前没有从网页将旧 VM 分配给用户的功能。 4. 在网页填写 B 的 IP/DNS、SSH 端口、虚拟机地区、现有的 **root 客户端 SSH 私钥**、磁盘目录、ISO 目录和网络名称。地区是这台宿主机上虚拟机共用的展示标签,可留空;它不影响 SSH 连接或已导入的模板。私钥必须与 B 的 root 账号**已经授权的公钥**匹配;仅有 root 密码或 B 的 SSH 主机密钥不能代替它。加密私钥还需填写其口令。保存宿主机设置时,面板会将口令与私钥加密写入 MariaDB,以便面板重启后自动连接和无人登录时继续采样;设置 API 不回显口令,面板代码也不将其写入浏览器存储。**旧版本中只在内存解锁过的口令无法自动恢复**:升级后进入“宿主机设置”,不必重新粘贴原私钥,填写原口令并重新保存一次。只在“解锁宿主机 SSH 私钥”页面输入不会持久保存。 5. 点击“扫描主机指纹”,再通过 B 的可信控制台运行 `ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub` 独立核对;确认后在网页测试、保存。保存前会重扫并测试 SSH 与 libvirt API,失败不会覆盖现有连接。 diff --git a/static/app.js b/static/app.js index bee358fc..674bd960 100644 --- a/static/app.js +++ b/static/app.js @@ -2033,7 +2033,7 @@ byId("setup-form").addEventListener("submit", async (event) => { showError("setup-error", ""); const password = byId("setup-password").value; if (password !== byId("setup-password-confirm").value) { - showError("setup-error", "两次输入的管理员密码不一致。"); + showError("setup-error", "两次输入的初始用户密码不一致。"); return; } const button = byId("setup-submit"); @@ -2048,7 +2048,7 @@ byId("setup-form").addEventListener("submit", async (event) => { password, }, }); - if (!session?.authenticated || !session?.csrf_token) throw new Error("管理员已创建,但未能登录。请刷新页面后登录。"); + if (!session?.authenticated || !session?.csrf_token) throw new Error("初始用户已创建,但未能登录。请刷新页面后使用邮箱登录。"); byId("setup-token").value = ""; byId("setup-password").value = ""; byId("setup-password-confirm").value = ""; @@ -2070,9 +2070,9 @@ byId("login-form").addEventListener("submit", async (event) => { requireSecureCredentialTransport(); const session = await api("/api/v1/login", { method: "POST", csrf: false, - body: { username: byId("login-username").value.trim(), password: byId("login-password").value }, + body: { email: byId("login-email").value.trim(), password: byId("login-password").value }, }); - if (!session?.authenticated) throw new Error("登录失败,请检查用户名和密码。"); + if (!session?.authenticated) throw new Error("登录失败,请检查邮箱和密码。"); byId("login-password").value = ""; await continueAfterLogin(session); } catch (error) { @@ -2085,7 +2085,7 @@ byId("login-form").addEventListener("submit", async (event) => { byId("show-register-button").addEventListener("click", showRegister); byId("show-login-button").addEventListener("click", () => { showLogin(); - byId("login-username").focus(); + byId("login-email").focus(); }); byId("register-code-send").addEventListener("click", async () => { @@ -2124,16 +2124,17 @@ byId("register-form").addEventListener("submit", async (event) => { try { requireSecureCredentialTransport(); const username = byId("register-username").value.trim(); + const email = byId("register-email").value.trim(); const result = await api("/api/v1/register", { method: "POST", csrf: false, body: { username, - email: byId("register-email").value.trim(), + email, password, code: byId("register-code").value.trim(), } }); if (result?.registered !== true) throw new Error("面板未确认注册结果,请勿重复提交,稍后尝试登录。"); byId("register-form").reset(); showLogin(); - byId("login-username").value = username; + byId("login-email").value = email; text("login-success", "邮箱已验证,注册成功。账号需等待管理员审核通过后才能创建虚拟机;你可以先登录查看审核状态。"); byId("login-success").hidden = false; } catch (error) { diff --git a/static/index.html b/static/index.html index f64e3454..d5957c5c 100644 --- a/static/index.html +++ b/static/index.html @@ -5,8 +5,8 @@
初始用户默认没有管理员权限。创建后请由你在数据库中将该用户 admin 字段设为 1,再重新登录配置 SMTP 和宿主机。面板账号与宿主机 root 账号相互独立。
+初始用户默认没有管理员权限。创建后请由你在数据库中将该用户 admin 字段设为 1,并手动补充登录邮箱,再用邮箱登录配置 SMTP 和宿主机。面板账号与宿主机 root 账号相互独立。
使用你的面板账号访问虚拟机控制台。
+使用注册邮箱访问虚拟机控制台。