# 登录与安全

> 选择登录方式、绑定二次验证、修改密码和设置口令规则；会话管理与完整配置另有专页。

Source: https://yile2020.github.io/fastapi-react-admin/features/login-security/

本页介绍怎么登录、给账号绑定验证器，以及修改密码时需要遵守的规则。账号启用二次验证，或管理员要求强制开启后，登录时才需要额外验证。

查看设备、空闲退出和强制下线，请读[登录会话](https://yile2020.github.io/fastapi-react-admin/features/login-sessions/)；查配置键和默认值，请读[登录安全配置](https://yile2020.github.io/fastapi-react-admin/reference/security-config/)。

<details>
<summary>查看登录页截图</summary>

</details>

## 在界面上哪里找？

- **登录页**（`/sign-in`）：所有人都能访问。
- **个人中心**（`/profile`）：修改自己的密码、绑定手机号和验证器、关联第三方账号、查看最近登录记录。
- **系统管理 → 用户管理**（`/system/user`）：超级管理员为他人重置密码或二次验证。
- **系统管理 → 参数配置**（`/plugins/config`）：调整策略，需要 `sys:config:edit`。
- **日志管理 → 登录日志**（`/log/login`）：查看登录记录，需要 `log:login:list`。

重置密码和二次验证按**超级管理员**判定，只授予菜单权限还不能操作。

## 有几种登录方式？

| 方式 | 使用前需要做什么 |
|---|---|
| 账号密码 | 输入账号、密码，以及默认开启的图形验证码 |
| 手机验证码 | 系统已安装短信插件；本人先在个人中心验证并绑定手机号 |
| GitHub / Google | 系统已配置 OAuth2 插件；先用账号密码登录，在个人中心关联第三方账号 |

管理员录入或导入的手机号，需要本人验证后才能用于登录。陌生第三方账号默认不能登录；开放自动注册需另行[配置](https://yile2020.github.io/fastapi-react-admin/reference/security-config/#在-env-中修改)。

没有「忘记密码」的自助找回：登录页上写的是「忘记密码找管理员重置」。

## 二次验证（MFA）怎么用？

### 1. 管理员准备密钥

先在 `apps/api/backend/.env` 设置 `MFA_SECRET_KEY`，然后重启后端。它必须是 64 位十六进制，可以这样生成：

```bash
python -c "import os;print(os.urandom(32).hex())"
```

密钥留空时，不能开启或强制二次验证。这是服务端密钥，请妥善保存，不要放进共享文档或截图。

### 2. 在个人中心绑定验证器

1. 打开「个人中心 → 二次验证」，开始绑定。
2. 用 Google Authenticator、Microsoft Authenticator、1Password 等验证器扫描二维码。
3. 输入当前动态码确认，并保存随后显示的 **10 个恢复码**。

绑定后，可以凭当前动态码在个人中心关闭二次验证或重新生成恢复码；被强制开启时不能关闭。

**看到什么算成功：** 退出后重新登录，会进入输入动态码的第二步。启用二次验证后，手机验证码和第三方登录也需要这一步。

:::caution[绑定时保存恢复码]
恢复码只显示一次，每个只能用一次；重新生成后，旧的一批全部失效。验证器丢失时，用未使用的恢复码登录，或请超级管理员在「用户管理」中重置二次验证。
:::

### 3. 按需要求团队开启

在「系统管理 → 参数配置 → 登录策略」中设置「二次验证强制」：

| 值 | 效果 |
|---|---|
| `off` | 由用户自愿开启 |
| `superuser` | 超级管理员必须开启 |
| `all` | 所有人必须开启 |

尚未绑定的用户，下次在网页登录时需要先完成绑定才能进入系统。被强制的用户不能自己关闭。手机 App 支持输入动态码，但首次绑定需要在网页端完成。

## 密码有哪些规则？

| 规则 | 默认 | 可改范围 |
|---|---|---|
| 长度 | 6–32 位 | 1–128 |
| 必须包含特殊字符 | 否 | —— |
| 不能和最近几次相同 | 3 次 | 0–24 |
| 有效期 | 365 天（0 = 永不过期） | 0–3650 |
| 到期提醒提前量 | 7 天（0 = 不提醒） | 0–365 |

在「个人中心」修改自己的密码；管理员在「系统管理 → 参数配置 → 口令与锁定」调整规则。后端同样会校验这些范围。

改自己的密码、或者被管理员重置密码之后，这个账号的**所有**会话都会结束（原因是「密码已修改」），包括当前这一个。

:::caution[密码过期的两处现状]
- 剩余天数进入提醒期后，登录接口会返回 `password_expire_days_remaining`，但**网页端目前没有把它显示出来**。
- 过期后，账号密码和手机验证码两种登录都会被拒绝（第三方登录不检查密码有效期）。提示写的是「请修改密码后重新登录」，但本人这时已经登不进去，只能由超级管理员在「用户管理」里重置密码。
:::

## 密码输错几次会被锁？

默认情况下，**同一账号连续失败 5 次，锁定 5 分钟**；**同一 IP 累计失败 30 次，锁定 15 分钟**，跨账号也累计。错误提示不会透露账号是否存在或已被锁定。

账号阈值在「系统管理 → 参数配置 → 口令与锁定」中调整；IP 阈值在 `.env` 中调整。经过反向代理部署时，还需配置 `TRUSTED_PROXIES`，让 IP 防护使用真实地址。键名和接口限流见[登录安全配置](https://yile2020.github.io/fastapi-react-admin/reference/security-config/)。

<span id="一个账号能同时登几台多久不操作会退出"></span>

<span id="被踢下线时本人看到什么"></span>

## 查看设备与处理下线

超级管理员在「系统监控 → 在线用户」查看并结束会话。[登录会话](https://yile2020.github.io/fastapi-react-admin/features/login-sessions/)说明了多端上限、空闲退出和各种下线提示。

## 它不做什么

- 第二因素只有 TOTP 和恢复码，没有通行密钥（WebAuthn）、硬件密钥，也没有用短信当第二因素。
- 没有自助找回密码和自助注册（第三方登录显式打开自动建号的除外）。
- 密码到期提醒在网页端还没显示出来；过期后本人不能自助改密码，见[上文](#密码有哪些规则)。
- 会话依赖单实例 Redis 的 Lua 脚本，尚未在 Redis Cluster 上实测，见[登录会话](https://yile2020.github.io/fastapi-react-admin/features/login-sessions/)。

<span id="有哪些开关"></span>

<span id="加一种登录方式或一个踢人入口要注意什么"></span>

<span id="代码在哪"></span>

<span id="怎么测的"></span>

<span id="在演示站里试试"></span>

## 配置与开发参考

- [登录安全配置](https://yile2020.github.io/fastapi-react-admin/reference/security-config/)：完整参数、扩展注意事项、源码和已有测试覆盖。
- [试用会话管理](https://yile2020.github.io/fastapi-react-admin/features/login-sessions/#在演示站里试试)：在演示站观察两个会话。二次验证建议本地体验，演示站不保证配有密钥。
