跳转到内容
GitHub

登录安全配置

操作步骤见登录与安全和登录会话。本页供管理员查参数、开发者查实现与扩展入口。

每组还有一个总开关 <分组>_CONFIG_STATUS,设成 0 时整组不读数据库、回落到 .env 的值。反过来,这些键在 .env 里写了也会被数据库里的值覆盖 —— 常见问题里「.env 关了验证码,登录页还要输」就是这个原因。

入口是「系统管理 → 参数配置」,修改后不用重启。会话策略影响之后的登录;关闭验证码立即生效。

键默认值说明
LOGIN_CAPTCHA_ENABLEDtrue图形验证码;关掉立刻对所有人生效
LOGIN_MFA_ENFORCEoffoff / superuser / all;没配 MFA_SECRET_KEY 时只能是 off
键默认值说明
USER_LOCK_THRESHOLD · USER_LOCK_SECONDS5 · 300账号连续失败几次、锁多少秒;阈值 0 = 不锁
USER_PASSWORD_MIN_LENGTH · USER_PASSWORD_MAX_LENGTH6 · 32
USER_PASSWORD_REQUIRE_SPECIAL_CHARfalse
USER_PASSWORD_HISTORY_CHECK_COUNT3不能和最近几次相同
USER_PASSWORD_EXPIRY_DAYS · USER_PASSWORD_REMINDER_DAYS365 · 70 = 永不过期 / 不提醒
键默认值说明
SESSION_{WEB,DESKTOP,MOBILE}_IDLE_MINUTES120 · 120 · 432005 分钟到 90 天
SESSION_{…}_ABSOLUTE_DAYS7 · 7 · 901–365
SESSION_{…}_MAX0 · 0 · 10 = 不限
SESSION_{…}_OVERFLOWevict_idle或 deny 拒绝新登录

修改 apps/api/backend/.env 后需要重启后端。

键默认值说明
MFA_SECRET_KEY空加密 TOTP 密钥用;留空 = 不能开二次验证
LOGIN_IP_LOCK_THRESHOLD · LOGIN_IP_LOCK_SECONDS30 · 900单 IP 跨账号的失败锁定;阈值 0 = 关闭
TRUSTED_PROXIES[]反代的地址或网段。空 = 不采信任何转发头;部署在反代后面却不填,后端看到的 IP 全是反代的,IP 锁定、限流、登录日志里的 IP 都跟着错
TOKEN_EXPIRE_SECONDS1800access token 有效期
SESSION_REFRESH_GRACE_SECONDS30上一枚 refresh token 的宽限期;生产环境不许低于 10 秒
LOGIN_CAPTCHA_EXPIRE_SECONDS300图形验证码有效期
MFA_CHALLENGE_SECONDS · MFA_CHALLENGE_ATTEMPTS300 · 5登录第二步的时限和次数
COOKIE_SECURE跟着请求走HTTPS 生产站点显式设 true(生产模板已开启),refresh / OAuth2 state cookie 始终带 Secure;生产未设为 true 会告警。本地 HTTP 保持不配置,纯 HTTP 部署可设 false
OAUTH2_GITHUB_* · OAUTH2_GOOGLE_*——第三方登录的 Client ID / Secret
OAUTH2_AUTO_REGISTER · OAUTH2_AUTO_REGISTER_ROLEfalse · ——陌生第三方账号是否自动建号、挂哪个角色(角色编码找不到就拒绝登录)

TLS 在上游终结时,入口代理必须覆盖客户端传入的 X-Forwarded-Proto,web 容器会保留有效的 http / https,缺失或异常值回退到当前连接协议。web 明文端口仅对可信代理开放,并正确配置 Uvicorn 的 --forwarded-allow-ips。

完整的定义在 core/conf.py 的「用户安全」「登录」「登录会话」三段。

短信响应、失败计数与 MFA 校验细节

手机验证码这一路要先过图形验证码;同一个号 60 秒冷却、一天最多 10 条。没注册、没验证过的号也返回「已发送」,只是不真发:状态码、文案、冷却、耗时都和真发的一样,否则这个不用登录就能调的接口就成了一张号码核对表。短信厂商故障时也一样返回成功,失败记在短信发送日志里给管理员看。

错误提示不区分「用户不存在」「密码错」「账号已锁」,耗时也抹平了:bcrypt 校验一次约 190 ms,而查无此人只要约 5 ms,40 倍的差距不用任何统计手段就能看出来。所以用户不存在时也拿一个假哈希跑一遍等价的校验(auth_service.py 顶部的 _DUMMY_PASSWORD_HASH)。

登录接口本身还按「IP + 路径」限流:每分钟 5 次;取图形验证码的接口每 30 秒 5 次。

可改范围是后端卡的,不只是界面上的输入框(dynamic_config.py 的 DYNAMIC_INT_BOUNDS)。曾经实测过:带管理员 token 直接调接口,最小长度能被写成 999,结果是所有人都改不了密码。

TOTP 使用 6 位数字、30 秒时间片、SHA-1,前后各容忍一个时间片的时钟误差,同一个码不能重复使用。恢复码格式为 xxxx-xxxx,不含容易混淆的 0 / O / 1 / I / L,数据库只存哈希。

登录第二步有 5 分钟、最多试 5 次。输错的动态码计入账号的失败次数;密码正确不会清零计数,必须通过第二步才会清零。

加一种登录方式或一个「踢人」入口要注意什么?

Section titled “加一种登录方式或一个「踢人」入口要注意什么?”
  • 新的登录方式要过 mfa_service.gate():身份确认之后调它,决定是直接开会话还是进入第二步。手机验证码登录就是逐条照抄了密码登录的检查(IP 锁定、停用判定、密码过期、成败计数),验证码替代的只是「密码对不对」这一步 —— 只复用「开会话」那一段的话,这些检查全会漏掉。
  • 不用登录就能调的新接口,要加进 TOKEN_REQUEST_PATH_EXCLUDE,写完整路径、不要写成前缀。
  • 新的「让某人下线」的入口,只调 session_store.revoke / revoke_user,不要自己删 fba:session* 的 Redis key:这两个函数会顺带写原因、推实时消息、断开连接。会话改造之前,有 7 个文件各自删 token,其中一处只删了 access token —— 被踢的人刷新一下就回来了。

细节和踩过的坑在 common/security/AGENTS.md「登录会话」一节。

下面列出已有测试文件和覆盖的行为,可沿链接查看具体断言。

查看已有后端与浏览器测试覆盖

后端连真实的数据库和 Redis:

  • test_session.py(29 条):后台轮询不续命、离开超过空闲时长回来点一下也不复活、宽限期内回放同一组令牌、宽限期外作废整个会话、会话 ID 对得上但 secret 对不上不撤销(否则凭日志里看得到的会话 ID 就能把人踢下线)。其中几条做过变异检验:把对应的判断改掉,测试当场红。
  • test_mfa.py(16 条):恢复码只能用一次、密码对了不清零失败计数、试满次数后令牌作废、被强制的人登录时绑定且不能自己关、没配密钥不能强制。
  • test_auth.py:用户不存在和密码错的响应一样、耗时也一样、错密码不暴露账号已锁、强制下线连 refresh token 一起作废。
  • test_phone_login.py:没注册 / 没验证的号看起来也「发了」、厂商故障和陌生号码不可区分、手机登录也要过二次验证。
  • OAuth2 插件的 tests/:陌生账号默认不建号、state 绑定、只认已验证的邮箱。

浏览器端(Playwright):mfa.spec.ts(个人中心开启 → 退出 → 再登录要动态码)、session.spec.ts(被强制下线时页面当场回到登录页并说明原因;一个标签页登出,其它标签页跟着回去;刷新时后端暂时连不上,停在「连不上服务器」而不是踢回登录页)、login-phone.spec.ts。