diff --git a/README.md b/README.md index 21c8e24..af8d5ec 100644 --- a/README.md +++ b/README.md @@ -73,19 +73,25 @@ docker compose up -d #### 通行证密钥登录(可选) -用户先用密码登录,在个人页面输入当前密码绑定通行证密钥。绑定后,登录页可通过设备解锁使用密钥登录;此流程不依赖 Cloudflare Turnstile,原密码登录保持可用。 +通行证密钥登录不依赖 Cloudflare Turnstile,但必须在验证码可用时**预先绑定**。原密码登录保持可用;未绑定密钥的用户无法借此绕过验证码。 -在面板后端进程的环境中设置可信的、浏览器实际访问的公开源,例如在 Compose 的 `.env` 中添加: +1. 在面板后端进程的环境中设置可信的、浏览器实际访问的公开源。例如在 Compose 的 `.env` 中添加: -```dotenv -FLVX_WEBAUTHN_ORIGIN=https://panel.example.com -``` + ```dotenv + FLVX_WEBAUTHN_ORIGIN=https://panel.example.com + ``` -该值必须是完整的 HTTPS origin(协议、域名和可选端口),不能带路径、查询参数或尾部 `/`。仅本机开发允许 `http://localhost:3000` 或 `http://127.0.0.1:3000`。在反向代理后部署时填浏览器地址栏中的**前端**公开源,而不是容器内部地址、后端监听地址或代理转发头。API 可以位于另一地址;WebAuthn 验证的是发起操作的前端页面 origin。Compose 模板会将变量传给后端容器;自行部署时需传给 `paneld` 进程。 + 该值必须是完整的 HTTPS origin(协议、域名和可选端口),不能带路径、查询参数或尾部 `/`。仅本机开发允许 `http://localhost:3000` 或 `http://127.0.0.1:3000`。在反向代理后部署时填浏览器地址栏中的**前端**公开源,而不是容器内部地址、后端监听地址或代理转发头。API 可以位于另一地址;WebAuthn 验证的是发起操作的前端页面 origin。Compose 模板会将变量传给后端容器;自行部署时需传给 `paneld` 进程。 -未设置或设置错误时,通行证密钥接口拒绝新的绑定和登录,登录页与个人页不显示对应入口;密码登录不受影响。域名变化会改变 RP ID,旧域名下绑定的密钥不能用于新域名,需要在迁移前规划重新绑定。仅更改同一域名的端口也需同步更新此 origin。正在进行的密钥挑战只保存在后端内存中,重启后需重新开始;多副本部署需要共享会话方案。 +2. 使环境变量对后端生效(Compose 部署可运行 `docker compose up -d backend`)。登录页出现“使用通行证密钥登录”按钮时表示浏览器支持该功能且配置有效。 -数据库级备份会保留密钥记录。当前面板的 JSON 导出不包含通行证密钥,使用 JSON 导入迁移后,用户需要重新绑定。 +3. 用户先照常用密码登录,在“个人”页面的“通行证密钥”卡片中输入**当前密码**、可选名称,然后选择“绑定通行证密钥”并完成设备解锁。建议保留至少一种可用的密码恢复途径。绑定或删除密钥均需当前密码;只有该账号能列出和删除自己的密钥。 + +4. 以后在登录页输入用户名,选择“使用通行证密钥登录”,通过设备解锁即可进入面板。账号被停用时密钥登录也会被拒绝。需要撤销设备时,在个人页面输入当前密码并删除对应密钥。 + +**安全配置与恢复:**未设置或设置错误时,通行证密钥接口拒绝新的绑定和登录,登录页与个人页不显示对应入口;密码登录不受影响。不要把不可信的请求 `Host` / `X-Forwarded-Host` 当作可信 origin。域名变化会改变 RP ID,旧域名下绑定的密钥不能用于新域名;迁移时需保留原域名或可用的密码登录途径,再在新域名重新绑定。仅更改同一域名的端口也需同步更新此 origin。正在进行的密钥挑战只保存在后端内存中,重启后需重新开始;多副本部署需要共享会话方案,未实现前请保持单个后端实例。 + +数据库级备份会保留密钥记录。当前面板的 JSON 导出不包含通行证密钥,使用 JSON 导入迁移后,用户需要通过密码登录并重新绑定。 #### 从 SQLite 迁移到 PostgreSQL