4.11 安全架构设计

概述

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

认证：JWT 双令牌

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 安全加固清单）：

• [ ] 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 扩展性设计