登录与会话

验证码登录

/signin 使用邮箱和六位数字验证码，不使用密码。发送请求返回 challengeId、expiresInSeconds: 600 和 resendAfterSeconds: 60。验证需要同一组邮箱、challengeId 和验证码；换邮箱或重新发码后按当前页面的新挑战继续。

服务端按 UTC 小时统计发送请求，每邮箱上限 5 次、每 IP 上限 20 次，并有邮箱 60 秒冷却。共用出口的多个人可能碰到同一个 IP 上限。返回 429 时应等待，不要更换网络或循环重试。每个挑战最多允许 5 次错误验证码尝试；有效验证码成功后只能消费一次。

| 响应 | 含义与处理 | | --- | --- | | 请求返回 202 | 已接受投递；还需检查实际收信 | | 验证返回 400 | 邮箱、挑战或六位数字格式不正确 | | 验证返回 401 | 挑战无效、过期或已消费；回到页面重新申请 | | 返回 429 | 发送限流或验证次数耗尽；按限制等待 | | 返回 503 | 身份、数据库、Redis 或邮件依赖不可用；稍后重试并联系运营者 |

注册、角色与访问范围

首次成功验证时创建账户；已有用户继续使用自己的账户。/signup、/register、/reset-password 等兼容入口不代表仍支持密码注册、密码恢复或邀请码流程。

普通用户进入 /account，管理员进入 /admin/overview。管理权限由服务端检查；隐藏按钮或修改浏览器里的角色不会授予权限。管理接口返回 403 表示当前身份缺少管理员权限，不应反复请求。

会话会怎样失效

登录返回的 access token 有效期为 900 秒。浏览器通过 HttpOnly refresh cookie 刷新，会话空闲期限为 30 天、绝对期限为 90 天；刷新会轮换 refresh token，旧 token 重用触发会话防护。客户端会协调刷新，但这不保证永远保持登录。

生产 refresh cookie 使用 Secure、SameSite=Lax，路径为 /api/v1/auth。应从正确的 HTTPS 同源入口访问；不要在几个不同域名间混用登录页面和 API。access token、Cookie、验证码都不要放入 URL、截图或公开问题报告。

安全退出与常见误解

“退出登录”调用服务端撤销当前 refresh session 并清除 cookie，然后回到登录页。退出不删除文件，也不是所有设备同时退出的承诺；已签发 access token 有自己的有效期。当前指南没有账户自助删除或全设备会话管理操作。

邮件已发送却无法验证时，先核对当前邮箱和最新挑战，保留错误状态与发生时间即可；不要把验证码发给文档 AI。更多步骤见排错。