操作步骤见登录与安全和登录会话。本页供管理员查参数、开发者查实现与扩展入口。
配置按什么顺序生效?
Section titled “配置按什么顺序生效?”每组还有一个总开关 <分组>_CONFIG_STATUS,设成 0 时整组不读数据库、回落到 .env 的值。反过来,这些键在 .env 里写了也会被数据库里的值覆盖 —— 常见问题里「.env 关了验证码,登录页还要输」就是这个原因。
在参数配置中修改
Section titled “在参数配置中修改”入口是「系统管理 → 参数配置」,修改后不用重启。会话策略影响之后的登录;关闭验证码立即生效。
| 键 | 默认值 | 说明 |
|---|---|---|
LOGIN_CAPTCHA_ENABLED | true | 图形验证码;关掉立刻对所有人生效 |
LOGIN_MFA_ENFORCE | off | off / superuser / all;没配 MFA_SECRET_KEY 时只能是 off |
| 键 | 默认值 | 说明 |
|---|---|---|
USER_LOCK_THRESHOLD · USER_LOCK_SECONDS | 5 · 300 | 账号连续失败几次、锁多少秒;阈值 0 = 不锁 |
USER_PASSWORD_MIN_LENGTH · USER_PASSWORD_MAX_LENGTH | 6 · 32 | |
USER_PASSWORD_REQUIRE_SPECIAL_CHAR | false | |
USER_PASSWORD_HISTORY_CHECK_COUNT | 3 | 不能和最近几次相同 |
USER_PASSWORD_EXPIRY_DAYS · USER_PASSWORD_REMINDER_DAYS | 365 · 7 | 0 = 永不过期 / 不提醒 |
| 键 | 默认值 | 说明 |
|---|---|---|
SESSION_{WEB,DESKTOP,MOBILE}_IDLE_MINUTES | 120 · 120 · 43200 | 5 分钟到 90 天 |
SESSION_{…}_ABSOLUTE_DAYS | 7 · 7 · 90 | 1–365 |
SESSION_{…}_MAX | 0 · 0 · 1 | 0 = 不限 |
SESSION_{…}_OVERFLOW | evict_idle | 或 deny 拒绝新登录 |
在 .env 中修改
Section titled “在 .env 中修改”修改 apps/api/backend/.env 后需要重启后端。
| 键 | 默认值 | 说明 |
|---|---|---|
MFA_SECRET_KEY | 空 | 加密 TOTP 密钥用;留空 = 不能开二次验证 |
LOGIN_IP_LOCK_THRESHOLD · LOGIN_IP_LOCK_SECONDS | 30 · 900 | 单 IP 跨账号的失败锁定;阈值 0 = 关闭 |
TRUSTED_PROXIES | [] | 反代的地址或网段。空 = 不采信任何转发头;部署在反代后面却不填,后端看到的 IP 全是反代的,IP 锁定、限流、登录日志里的 IP 都跟着错 |
TOKEN_EXPIRE_SECONDS | 1800 | access token 有效期 |
SESSION_REFRESH_GRACE_SECONDS | 30 | 上一枚 refresh token 的宽限期;生产环境不许低于 10 秒 |
LOGIN_CAPTCHA_EXPIRE_SECONDS | 300 | 图形验证码有效期 |
MFA_CHALLENGE_SECONDS · MFA_CHALLENGE_ATTEMPTS | 300 · 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_ROLE | false · —— | 陌生第三方账号是否自动建号、挂哪个角色(角色编码找不到就拒绝登录) |
TLS 在上游终结时,入口代理必须覆盖客户端传入的 X-Forwarded-Proto,web 容器会保留有效的 http / https,缺失或异常值回退到当前连接协议。web 明文端口仅对可信代理开放,并正确配置 Uvicorn 的 --forwarded-allow-ips。
完整的定义在 core/conf.py 的「用户安全」「登录」「登录会话」三段。
验证与限流规则
Section titled “验证与限流规则”短信响应、失败计数与 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「登录会话」一节。
- 登录流程:
auth_service.py· 接口api/v1/auth/auth.py - 二次验证:
mfa_service.py·utils/totp.py - 会话:
common/security/session.py· 在线用户接口monitor/online.py - 密码策略:
user_password_history_service.py· 运行时配置utils/dynamic_config.py - 第三方登录:
plugin/oauth2/ - 前端:登录页
sign-in.tsx· 个人中心pages/profile/· 在线用户pages/log-online/· 会话与刷新auth/session.ts
下面列出已有测试文件和覆盖的行为,可沿链接查看具体断言。
查看已有后端与浏览器测试覆盖
后端连真实的数据库和 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。