# 4.11 安全架构设计

:::tip 概述
安全能力分布在四个层面：**传输层**（CORS、受信代理）、**认证层**（JWT 双令牌、验证码、限流）、**授权层**（RBAC + 数据权限 + 租户隔离）、**工程层**（fail-fast 校验、演示模式、生产模式红线）。
:::

## 认证：JWT 双令牌

```text
access_token   短时效（默认 2 小时）——常规请求凭证
refresh_token  长时效（默认 7 天）——经 /api/oauth2/token 兑换新令牌
登出/撤销      → Token 黑名单缓存（TTL = 剩余有效期），在线列表同步移除
```

密钥经 `jwt.secret` 配置；**生产模式拒绝默认或过短密钥**。

## 授权：三层收敛

| 层 | 机制 | 粒度 |
|---|---|---|
| 接口 | Authz 按 RouteSpec.Permission 校验 | 动作级（sys:user:add） |
| 按钮 | 前端 v-permission 比对下发权限码 | 组件级 |
| 数据 | DataScope 按 dept_id 收敛 + 租户 Scope | 行级 |

三层同源于菜单-角色授权链，改一处即全局生效。

## 防护

| 防护 | 实现 |
|---|---|
| 暴力破解 | RateLimit：普通接口 120 次/分钟/IP，认证接口 10 次/分钟（更严） |
| 超大请求体 | api.maxBodyMB 上限（默认 10MB） |
| IP 伪造 | 仅受信代理列表（api.proxyIps，支持 CIDR）内的来源才信任 X-Forwarded-For |
| 路径穿越 | 上传文件访问经 SafeJoin 断言物理路径在上传根内；temp 目录封禁 |
| 敏感端点暴露 | api.docs / api.metrics 生产可关闭 |
| 暴力枚举 temp 文件 | temp 临时目录始终 404 |

## 密码与加密

密码哈希经 `utility/crypto` 处理（bcrypt 系），数据库不存明文；前后端传输经 HTTPS（生产由 Nginx 终止 TLS）。

## 生产模式红线（app.prod=true）

启动校验直接拒绝：

1. 默认或过短的 JWT 密钥
2. 非空的验证码万能码（captcha.bypassCode）
3. 未关闭的代码生成器（generator.enable，其具备写服务器源码能力）

## 演示模式（app.demo=true）

写操作一律拒绝、读与登录放行——用于对外演示环境保护数据。

## 审计能力

- 操作日志：谁在何时调了什么接口、入参摘要、结果
- 登录日志：登录行为专项留痕（含 IP 归属地，ip2region 离线库）
- 全链路 trace_id 关联运行日志

## 安全检查清单

生产上线前逐项核对（完整清单见 [11.8 安全加固清单](/zh/deploy/security.html)）：

- [ ] app.prod=true 且 JWT 密钥已换
- [ ] generator.enable=false、captcha.bypassCode 为空
- [ ] api.docs=false（或网关封锁）
- [ ] MySQL/Redis 端口仅内网可达（compose 默认仅绑回环）
- [ ] HTTPS 已启用，cors.allowOrigin 收敛到实际域名
- [ ] file.domainUrl 走 https 且 nginx 封禁 temp

## 下一步

→ [4.12 扩展性设计](/zh/architecture/extensibility.html)