From 9ee328f428b71e02c990881562f07ed157009c51 Mon Sep 17 00:00:00 2001 From: admin Date: Sat, 26 Sep 2026 05:27:15 +0800 Subject: [PATCH] Require email login for database users --- README.md | 22 ++++++++++++++++++---- static/app.js | 15 ++++++++------- static/index.html | 12 ++++++------ tests/test_database.py | 1 + tests/test_database_http.py | 20 ++++++++++++++++++-- tests/test_registration_http.py | 30 ++++++++++++++++++++++++------ tests/test_users.py | 13 +++++++++++++ virsh_panel/app.py | 23 +++++++++++++++++------ virsh_panel/users.py | 19 +++++++++++++++++++ 9 files changed, 124 insertions(+), 31 deletions(-) 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 @@ VirtPilot · 虚拟机管理 - - + +
@@ -75,7 +75,7 @@ -

初始用户默认没有管理员权限。创建后请由你在数据库中将该用户 admin 字段设为 1,再重新登录配置 SMTP 和宿主机。面板账号与宿主机 root 账号相互独立。

+

初始用户默认没有管理员权限。创建后请由你在数据库中将该用户 admin 字段设为 1,并手动补充登录邮箱,再用邮箱登录配置 SMTP 和宿主机。面板账号与宿主机 root 账号相互独立。

@@ -101,10 +101,10 @@
VirtPilot
欢迎回来

登录管理面板

-

使用你的面板账号访问虚拟机控制台。

+

使用注册邮箱访问虚拟机控制台。

- - + + diff --git a/tests/test_database.py b/tests/test_database.py index 9ba8125d..eef3de83 100644 --- a/tests/test_database.py +++ b/tests/test_database.py @@ -136,6 +136,7 @@ def test_initial_user_hash_is_database_only_and_bootstrap_token_is_consumed(tmp_ reopened = DatabasePanelState(data_dir, store, MemoryUsers(store)) user = reopened.users.get_by_username("admin") assert user["admin"] is False and user["approved"] is True + assert user["email"] is None assert verify_password("a-valid-very-long-password", user["password_hash"]) assert reopened.initialize_setup_token() is None diff --git a/tests/test_database_http.py b/tests/test_database_http.py index d7b4fb5e..0559295e 100644 --- a/tests/test_database_http.py +++ b/tests/test_database_http.py @@ -26,7 +26,7 @@ from virsh_panel import app as app_module from virsh_panel.auth import hash_password from virsh_panel.config import Settings from virsh_panel.database import DatabasePanelState, DatabaseTemplateStore -from virsh_panel.users import UserError +from virsh_panel.users import UserError, normalize_email class MemoryUsers: @@ -42,6 +42,18 @@ class MemoryUsers: raw = self.store.get("test_user", username) return json.loads(raw) if raw else None + def get_by_email(self, email): + try: + email = normalize_email(email) + except UserError: + return None + for (kind, _key), raw in self.store.records.items(): + if kind == "test_user": + account = json.loads(raw) + if account["email"] == email: + return account + return None + def get_by_id(self, user_id): for (kind, _key), raw in self.store.records.items(): if kind == "test_user": @@ -51,6 +63,7 @@ class MemoryUsers: return None def create_initial_user(self, username, password, email=None): + email = normalize_email(email) if email is not None else None account = { "id": 1, "username": username, "email": email, "password_hash": hash_password(password), "admin": False, @@ -116,7 +129,8 @@ class MemoryUsers: def register_with_code(self, username, email, password, code): if self.store.get("test_code", email) != code: raise UserError("验证码无效或已过期") - if self.get_by_username(username) is not None: + email = normalize_email(email) + if self.get_by_username(username) is not None or self.get_by_email(email) is not None: raise UserError("用户名或邮箱已存在", 409) account = { "id": 1 + sum(kind == "test_user" for kind, _key in self.store.records), @@ -223,6 +237,8 @@ def test_first_run_requires_database_then_admin_and_ignores_old_json(monkeypatch session_cookie = client.cookies.get("virsh_panel_session") assert ("test_user", "admin") in store.records assert store.users.get_by_username("admin")["admin"] is False + assert store.users.get_by_username("admin")["email"] is None + assert store.users.get_by_email("admin@example.test") is None assert not (data_dir / "setup-token").exists() encrypted = (data_dir / "database-config.json").read_bytes() assert b"test-database-password" not in encrypted diff --git a/tests/test_registration_http.py b/tests/test_registration_http.py index c11e0b91..224b02a1 100644 --- a/tests/test_registration_http.py +++ b/tests/test_registration_http.py @@ -99,9 +99,9 @@ class _NoMetrics: pass -def _login(client: TestClient, username: str): +def _login(client: TestClient, email: str): response = client.post("/api/v1/login", json={ - "username": username, "password": PASSWORD, + "email": email, "password": PASSWORD, }) assert response.status_code == 200 return {"X-CSRF-Token": response.json()["csrf_token"]} @@ -151,9 +151,27 @@ def test_registration_smtp_approval_and_per_user_vm_isolation(monkeypatch, tmp_p admin_headers = {"X-CSRF-Token": initial.json()["csrf_token"]} assert admin.get("/api/v1/session").json()["admin"] is False assert admin.get("/api/v1/smtp/settings").status_code == 403 - # The operator promotes the initial account manually in MariaDB. + # The operator promotes the initial account and adds its email in MariaDB. store.users.promote("firstuser") assert admin.get("/api/v1/session").json()["admin"] is True + initial_account = store.users.get_by_username("firstuser") + assert initial_account["email"] is None + with TestClient(app, base_url=ORIGIN) as missing_email: + assert missing_email.post("/api/v1/login", json={ + "email": "first@example.test", "password": PASSWORD, + }).status_code == 401 + store.set("test_user", "firstuser", json.dumps({ + **initial_account, "email": "first@example.test", + })) + with TestClient(app, base_url=ORIGIN) as fresh_admin: + assert fresh_admin.post("/api/v1/login", json={ + "username": "firstuser", "password": PASSWORD, + }).status_code == 422 + assert fresh_admin.post("/api/v1/login", json={ + "email": "firstuser", "password": PASSWORD, + }).status_code == 401 + assert _login(fresh_admin, "FIRST@EXAMPLE.TEST") + assert fresh_admin.get("/api/v1/session").json()["admin"] is True smtp = admin.put("/api/v1/smtp/settings", json={ "host": "smtp.example.test", "port": 587, "tls_mode": "starttls", "from_address": "panel@example.test", "username": "mailer", @@ -190,7 +208,7 @@ def test_registration_smtp_approval_and_per_user_vm_isolation(monkeypatch, tmp_p with TestClient(app, base_url=ORIGIN) as first: _register(first, "one@example.test", "tenantone") assert sent == [("smtp.example.test", "one@example.test", "123456")] - first_headers = _login(first, "tenantone") + first_headers = _login(first, "ONE@EXAMPLE.TEST") assert first.get("/api/v1/session").json()["approved"] is False assert first.post("/api/v1/vms", json=CREATE_VM, headers=first_headers).status_code == 403 @@ -214,7 +232,7 @@ def test_registration_smtp_approval_and_per_user_vm_isolation(monkeypatch, tmp_p with TestClient(app, base_url=ORIGIN) as second: _register(second, "two@example.test", "tenanttwo") - second_headers = _login(second, "tenanttwo") + second_headers = _login(second, "two@example.test") second_id = store.users.get_by_username("tenanttwo")["id"] assert admin.post(f"/api/v1/users/{second_id}/approve", headers=admin_headers).status_code == 200 @@ -281,7 +299,7 @@ def test_registration_smtp_approval_and_per_user_vm_isolation(monkeypatch, tmp_p console.receive_text() assert revoked.value.code == 4403 - first_headers = _login(first, "tenantone") + first_headers = _login(first, "one@example.test") own_cookie = first.cookies.get("virsh_panel_session") with first.websocket_connect(own_console, headers={ "host": "panel.example.test", "origin": ORIGIN, diff --git a/tests/test_users.py b/tests/test_users.py index edaf3da5..8ddf01d4 100644 --- a/tests/test_users.py +++ b/tests/test_users.py @@ -121,11 +121,24 @@ def test_initial_user_is_not_admin_but_is_approved(users): assert repository.has_users() is True assert repository.get_by_username("first") == first assert repository.get_by_id(first["id"]) == first + assert repository.get_by_email("first@example.test") is None + assert repository.get_by_email("first") is None + _database.execute("UPDATE users SET email=? WHERE id=?", ("first@example.test", first["id"])) + _database.commit() + assert repository.get_by_email("FIRST@EXAMPLE.TEST")["id"] == first["id"] with pytest.raises(UserError) as repeated: repository.create_initial_user("second", "another-long-password", now=101) assert repeated.value.status == 409 +def test_initial_user_rejects_invalid_email_when_provided(users): + repository, _database = users + for email in ("", "not-an-email"): + with pytest.raises(UserError): + repository.create_initial_user("first", "initial-long-password", email) + assert repository.has_users() is False + + def test_registration_code_is_keyed_rate_limited_and_one_time(users): repository, database = users assert repository.issue_registration_code("User@Example.COM", "123456", now=100) diff --git a/virsh_panel/app.py b/virsh_panel/app.py index f74816db..af31bc5a 100644 --- a/virsh_panel/app.py +++ b/virsh_panel/app.py @@ -85,7 +85,10 @@ class UpdateApplyBody(BaseModel): class LoginBody(BaseModel): model_config = ConfigDict(extra="forbid") - username: str = Field(min_length=1, max_length=64) + email: str | None = Field(default=None, min_length=3, max_length=254) + # Only the injected, database-free test harness may use the historical + # username login. Production explicitly rejects this field below. + username: str | None = Field(default=None, min_length=1, max_length=64) password: str = Field(min_length=1, max_length=1024) @@ -808,22 +811,30 @@ def create_app( if not login_limiter.allowed(peer): raise HTTPException(status_code=429, detail="登录尝试过多,请稍后再试") if database_mode: + if body.email is None or body.username is not None: + raise HTTPException(status_code=422, detail="请使用邮箱登录") + try: + email = normalize_email(body.email) + except UserError: + login_limiter.failed(peer) + raise HTTPException(status_code=401, detail="邮箱或密码错误") from None if not state.users.has_users(): raise HTTPException(status_code=409, detail="请先完成初始化") - account = state.users.get_by_username(body.username) + account = state.users.get_by_email(email) encoded = account["password_hash"] if account else None - username = account["username"] if account else body.username + username = account["username"] if account else "" + identity_ok = account is not None else: legacy_admin = state.admin() if legacy_admin is None: raise HTTPException(status_code=409, detail="请先完成初始化") username, encoded = legacy_admin account = {"email_verified": True} + identity_ok = hmac.compare_digest(body.username or "", username) password_ok = verify_password(body.password, encoded) if encoded else False - username_ok = hmac.compare_digest(body.username, username) - if not password_ok or not username_ok or not account["email_verified"]: + if not password_ok or not identity_ok or not account["email_verified"]: login_limiter.failed(peer) - raise HTTPException(status_code=401, detail="用户名或密码错误") + raise HTTPException(status_code=401, detail="邮箱或密码错误") login_limiter.succeeded(peer) return session_response(username) diff --git a/virsh_panel/users.py b/virsh_panel/users.py index cd23fa4f..04648e83 100644 --- a/virsh_panel/users.py +++ b/virsh_panel/users.py @@ -144,6 +144,25 @@ class DatabaseUserStore: finally: connection.close() + def get_by_email(self, email: str) -> dict[str, Any] | None: + try: + normalized_email = normalize_email(email) + except UserError: + return None + connection = self._connect() + try: + with connection.cursor() as cursor: + cursor.execute( + "SELECT id, username, email, password_hash, admin, approved, " + "email_verified, created_at " + "FROM users WHERE email=%s", (normalized_email,), + ) + return _user_row(cursor.fetchone()) + except pymysql.MySQLError as exc: + raise DatabaseError("无法读取用户数据") from exc + finally: + connection.close() + def get_by_id(self, user_id: int) -> dict[str, Any] | None: if isinstance(user_id, bool) or not isinstance(user_id, int) or user_id < 1: return None