Require email login for database users

main
admin 2 months ago
parent 92241d1cee
commit 9ee328f428

@ -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,失败不会覆盖现有连接。

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

@ -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=registration-smtp-1" />
<script type="module" src="/static/app.js?v=registration-smtp-1"></script>
<link rel="stylesheet" href="/static/styles.css?v=email-login-1" />
<script type="module" src="/static/app.js?v=email-login-1"></script>
</head>
<body>
<div id="boot-screen" class="boot-screen" role="status" aria-live="polite">
@ -75,7 +75,7 @@
<p id="setup-error" class="form-error" role="alert" hidden></p>
<button id="setup-submit" class="button button-primary setup-submit" type="submit">创建初始用户 <span aria-hidden="true">→</span></button>
</form>
<p class="setup-note">初始用户默认没有管理员权限。创建后请由你在数据库中将该用户 admin 字段设为 1,再重新登录配置 SMTP 和宿主机。面板账号与宿主机 root 账号相互独立。</p>
<p class="setup-note">初始用户默认没有管理员权限。创建后请由你在数据库中将该用户 admin 字段设为 1,并手动补充登录邮箱,再用邮箱登录配置 SMTP 和宿主机。面板账号与宿主机 root 账号相互独立。</p>
</section>
</div>
</main>
@ -101,10 +101,10 @@
<div class="login-mobile-brand"><span class="brand-mark"><span></span></span> VirtPilot</div>
<span class="eyebrow">欢迎回来</span>
<h2>登录管理面板</h2>
<p class="muted">使用你的面板账号访问虚拟机控制台。</p>
<p class="muted">使用注册邮箱访问虚拟机控制台。</p>
<form id="login-form" class="form-stack">
<label for="login-username">用户名</label>
<input id="login-username" name="username" type="text" autocomplete="username" maxlength="64" required autofocus placeholder="输入用户名" />
<label for="login-email">邮箱</label>
<input id="login-email" name="email" type="email" autocomplete="username" maxlength="254" required autofocus placeholder="输入注册邮箱" />
<label for="login-password">密码</label>
<input id="login-password" name="password" type="password" autocomplete="current-password" maxlength="1024" required placeholder="输入密码" />
<p id="login-error" class="form-error" role="alert" hidden></p>

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

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

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

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

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

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

Loading…
Cancel
Save