# 安全总览

> 默认开着的安全防护一页看完：登录防爆破与二次验证、会话管控、后端逐个接口判权限和数据范围、带防篡改签名的审计记录、密钥加密存储、生产环境启动检查。每一条都链接到详细说明和测试。

Source: https://yile2020.github.io/fastapi-react-admin/getting-started/security/

这一页把默认开着的安全防护列在一起，每一条都链接到详细说明。大部分不用额外配置，装好就生效；需要你在部署时做的事单独标了出来。

这些说明来自代码和自动化测试，**不是第三方渗透测试报告**。

## 登录这一关挡了什么？

- **图形验证码**默认开启，按参数走：在「参数配置」里随时开关，生产环境也不强制。
- **输错锁定**：同一账号 5 分钟内失败 5 次，锁 5 分钟；同一 IP 15 分钟内跨账号累计失败 30 次，在这 15 分钟里剩下的时间都被挡住。
- **提示和耗时不区分「用户不存在」和「密码错」**：两者给同一句提示，耗时也抹平了。否则查无此人只要约 5 毫秒，校验密码要约 190 毫秒，一看就知道。
- **登录接口限流**：按「IP + 接口」每分钟 5 次；取验证码每 30 秒 5 次。
- **二次验证**：TOTP 动态码加恢复码，可以要求超级管理员或所有人必须开启。
- **密码策略**：可设长度、复杂度、不能和最近 N 次重复、有效期。改了密码或被管理员重置后，这个账号的所有会话都会结束。

详见[登录与安全](https://yile2020.github.io/fastapi-react-admin/features/login-security/)和[登录安全配置](https://yile2020.github.io/fastapi-react-admin/reference/security-config/)。

## 登录之后，会话怎么管？

- **每次登录都有一个服务端会话**，可以按端设置空闲超时、最长登录时间和设备数上限。比如网页端默认空闲 120 分钟退出，最长 7 天。
- **空闲按「人有没有在操作」算**：后台轮询不算活跃，人走开了会话照样会过期。
- **超级管理员可以强制下线**任一会话。被踢的人下一次请求就回到登录页，并看到原因。
- **access token 30 分钟过期**，refresh token 每用一次换一枚新的。上一枚在 30 秒之后又被拿来用，判定为凭据可能被盗，整个会话立即作废。

详见[登录会话](https://yile2020.github.io/fastapi-react-admin/features/login-sessions/)。

## 能做什么、能看到什么，在哪里判？

- **需要权限的接口在后端判权限码。** 前端隐藏按钮只是为了界面好看，真正的边界在后端。这类接口上的写操作还要求账号有「后台管理权限」。停用一个目录，它下面所有按钮的权限一起失效。只要求登录、没声明权限码的接口（比如「当前用户」）不判权限码。
- **数据范围在查询层自动过滤**：同一张用户表，部门经理只能查到自己部门的人。不用在每个接口里手写过滤条件。
- **没权限读的文件返回 404**，不返回 403，免得等于告诉对方这个 ID 存在。
- **权限码有自动核对**：前端按钮用到的权限码，后端必须有接口守着；后端和前端用到的权限码，菜单数据里必须配了。缺一个，[测试](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/app/admin/tests/security/test_permission_codes.py)就失败。

详见[用户 · 角色 · 部门 · 菜单](https://yile2020.github.io/fastapi-react-admin/features/rbac/)和[数据权限](https://yile2020.github.io/fastapi-react-admin/features/data-permissions/)。

## 出了事，能不能查清楚？

- **登录日志**：登录成功和失败都记（被接口限流直接挡回的请求除外），还有账号被锁、IP 被锁、被强制下线，带 IP、归属地、浏览器和设备。
- **操作日志**：`/api/v1` 下的每个请求都记，包括 GET。密码、令牌、密钥这类字段**先打码、后截断**，嵌套在里层的也打。声明是 JSON、却解析不了的请求体和响应体不记原文；纯文本内容没有字段可打码，原样截断记录。
- **数据变更记录**：改了哪个字段、旧值、新值，和业务数据在同一个事务里写入。每一条都签名并串成一条链：改一行、删一行、插一行，校验时都会对不上。**要配了 `DATA_CHANGE_CHAIN_KEY` 才是真正的 HMAC-SHA256 签名**；留空时谁都能重算签名，只能防手滑直接改库。
- **保留 180 天**，满足《网络安全法》「网络日志留存不少于六个月」的要求，可以改。

详见[日志与审计](https://yile2020.github.io/fastapi-react-admin/features/audit-logs/)。

## 密钥和凭据怎么存？

- **界面上保存的密钥加密落库**，包括 AI 模型的 API Key、对象存储密钥、群机器人地址、参数配置里的 SMTP 授权码等。各用各的加密密钥；没配加密密钥时**拒绝保存**，不会退回成明文存储。
- **读接口不返回明文**：参数配置里的密钥只告诉你「已配置」，模型密钥只显示掩码。
- **数据变更记录里的敏感字段只记「已修改」**，不记内容。

需要你做的：上线前配好各自的加密密钥，以及审计签名用的 `DATA_CHANGE_CHAIN_KEY`，见[上线前检查清单](https://yile2020.github.io/fastapi-react-admin/getting-started/deployment/#上线前检查清单)。

## 部署到生产时有什么兜底？

`ENVIRONMENT='prod'` 时，后端启动前会一次性检查下面这些，有一项不合格就[拒绝启动](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/core/conf.py)：

- 签名密钥和数据库、Redis 口令的长度和随机性。把占位符改成 `123` 这类弱值也过不去。
- 接口限流不能关。
- 演示模式必须关。
- 不能用数据库超级用户（`sa`、`root`、`postgres`）连接。
- 跨域来源里不能有 `*` 或本机地址。

另外：

- 部署脚本 `prod.sh` 发现配置文件里还有 `CHANGE_ME`，或者文件对其他用户可读，就拒绝启动。
- **转发头（`X-Forwarded-For` 等）只采信来自可信代理的**：应用层的 `TRUSTED_PROXIES` 默认空，即谁都不信；生产镜像里的 uvicorn 只信容器网段。否则客户端换个请求头就能绕过限流、伪造日志里的 IP。
- HTTPS 站点给登录 cookie 加 `Secure`（`COOKIE_SECURE`）。

详见[部署到服务器](https://yile2020.github.io/fastapi-react-admin/getting-started/deployment/)。

## 对外开放的接口怎么防？

- 外部系统用 **AK/SK 签名**调用，签名用常量时间比较。
- **防重放**：时间戳 5 分钟窗口，加上 10 分钟内不能重复的随机数。
- 可以限制**来源 IP**、限制能调哪些接口，**按应用限流**。
- 推给对方的 Webhook 按 Standard Webhooks 规范签名。

详见[能力开放](https://yile2020.github.io/fastapi-react-admin/features/open-api/)。

## 上传的文件呢？

- 上传文件名里的路径会被[去掉](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/utils/file_ops.py)，拼不出 `../../` 这样的路径；有[测试](https://github.com/yile2020/fastapi-react-admin/blob/main/apps/api/backend/app/admin/tests/api_v1/test_file.py)守着。
- 私有文件不挂静态目录，只能带登录凭据下载。公开文件要显式声明，而且只收图片。

详见[文件与存储](https://yile2020.github.io/fastapi-react-admin/features/file-storage/)。

## 它不做什么

- 第二因素只有 TOTP 和恢复码，没有通行密钥（WebAuthn）和硬件密钥。
- 没有自助找回密码，忘了密码找管理员重置。
- 会话依赖单实例 Redis，没有在 Redis Cluster 上实测过。
- 同时拿到数据库**和**签名密钥的人，数据变更记录的签名链挡不住。
- 这一页不是第三方安全审计或认证。

## 发现漏洞怎么报？

请不要开公开 issue，用 GitHub 的私密漏洞报告（仓库 → Security → Report a vulnerability）。范围和流程见 [`SECURITY.md`](https://github.com/yile2020/fastapi-react-admin/blob/main/SECURITY.md)。
