初始化

2026-03-11 19:32:37 +08:00
commit 5708f80091
904 changed files with 68154 additions and 0 deletions
--- a/rdms-framework/rdms-spring-boot-starter-security/README.md
+++ b/rdms-framework/rdms-spring-boot-starter-security/README.md
@@ -0,0 +1,643 @@
+# rdms-spring-boot-starter-security
+
+## 1. 模块定位
+
+`rdms-spring-boot-starter-security` 是项目中的安全基础模块，当前实际包含两块能力：
+
+- 安全认证与权限校验
+- 操作日志记录
+
+这个模块不是单纯引入 Spring Security 依赖，而是已经在项目里落了完整的自动装配链路，包括：
+
+- 基于 Token 的无状态认证
+- 登录用户上下文维护
+- URL 与方法级权限控制
+- 跨服务 `LoginUser` 透传
+- 401 / 403 统一返回
+- 操作日志采集与异步上报
+
+## 2. 设计思路
+
+### 2.1 认证与权限分层
+
+这个模块把安全相关能力拆成了几层：
+
+1. 配置层  
+   通过 `SecurityProperties` 统一管理 token 请求头、token 参数名、白名单、mock 登录、密码加密强度等配置。
+
+2. 过滤器层  
+   通过 `TokenAuthenticationFilter` 解析请求中的登录信息，并把 `LoginUser` 放入 Spring Security 上下文。
+
+3. Spring Security 配置层  
+   通过 `SecurityFilterChain` 统一配置无状态认证、放行规则、异常处理和过滤器顺序。
+
+4. 权限服务层  
+   通过 `SecurityFrameworkService` 对外提供权限、角色、scope 判断能力，供 `@PreAuthorize` 等表达式直接使用。
+
+5. RPC 透传层  
+   通过 Feign `RequestInterceptor` 把当前 `LoginUser` 继续透传给下游服务。
+
+### 2.2 当前认证链路
+
+当前项目的认证链路可以理解为：
+
+1. 请求进入服务
+2. 优先尝试从 `login-user` 请求头恢复登录用户  
+   适用于网关或上游服务已经完成认证并透传用户信息的场景
+3. 如果没有 `login-user`，再尝试从 `Authorization` 或请求参数中获取 token
+4. 通过 `OAuth2TokenCommonApi` 校验 token
+5. 构造 `LoginUser`
+6. 放入 Spring Security 上下文，供后续权限判断、业务代码、日志记录使用
+
+这意味着当前项目跨服务调用时，主要透传的是 `LoginUser`，而不是原始 `Authorization`。
+
+### 2.3 权限判断思路
+
+权限判断没有把权限数据直接塞进本地配置，而是通过远程接口获取：
+
+- 权限校验走 `PermissionCommonApi`
+- token 校验走 `OAuth2TokenCommonApi`
+
+也就是说，这个模块负责“接入和执行安全规则”，权限与 token 数据本身仍然由系统服务提供。
+
+### 2.4 操作日志思路
+
+操作日志能力不是自己从零实现注解解析，而是集成 `bizlog-sdk`：
+
+- 业务代码通过 `@LogRecord` 声明日志
+- 本模块提供 `ILogRecordService` 实现
+- 最终通过 `OperateLogCommonApi` 异步上报操作日志
+
+这样做的特点是：
+
+- 业务代码侧书写简单
+- 日志记录逻辑统一
+- 日志存储仍集中在系统服务
+
+## 3. 自动装配入口
+
+当前自动装配入口在：
+
+- `RdmsSecurityRpcAutoConfiguration`
+- `RdmsSecurityAutoConfiguration`
+- `RdmsWebSecurityConfigurerAdapter`
+- `RdmsOperateLogConfiguration`
+- `RdmsOperateLogRpcAutoConfiguration`
+
+说明这个 starter 当前已经不是占位模块，而是有完整自动配置入口的基础模块。
+
+## 4. 核心功能点
+
+### 4.1 基于 Token 的无状态认证
+
+通过 `SecurityFilterChain` 配置为无状态模式：
+
+- 禁用 Session
+- 禁用表单登录
+- 禁用 httpBasic
+- 通过自定义 `TokenAuthenticationFilter` 完成登录态识别
+
+这意味着服务本身不维护 Session，认证主要依赖 token 或上游透传的 `login-user`。
+
+### 4.2 登录用户上下文维护
+
+模块内定义了 `LoginUser`，当前主要包含这些信息：
+
+- `id`
+- `userType`
+- `info`
+- `tenantId`
+- `scopes`
+- `expiresTime`
+- `visitTenantId`
+
+认证成功后，`LoginUser` 会进入 Spring Security 上下文，后续可以通过 `SecurityFrameworkUtils` 获取，例如：
+
+- 当前用户 ID
+- 当前用户昵称
+- 当前用户部门 ID
+
+### 4.3 支持两种登录信息来源
+
+`TokenAuthenticationFilter` 当前支持两种方式恢复登录用户：
+
+1. 从 `login-user` 请求头恢复  
+   适合网关转发、服务间调用、Feign 透传场景
+
+2. 从 token 恢复  
+   适合直接请求服务、没有上游透传 `login-user` 的场景
+
+这也是为什么当前服务间调用时，即使不继续透传原始 token，下游仍然可以识别当前登录用户。
+
+### 4.4 跨服务 LoginUser 透传
+
+模块内提供了 `LoginUserRequestInterceptor`。
+
+作用是：
+
+- 发起 Feign 请求时，读取当前线程中的 `LoginUser`
+- 将其序列化后放到 `login-user` 请求头
+- 下游服务再通过 `TokenAuthenticationFilter` 还原为登录用户上下文
+
+当前项目跨服务透传的重点是“登录用户信息透传”，不是“原始 token 透传”。
+
+### 4.5 URL 级访问控制
+
+`RdmsWebSecurityConfigurerAdapter` 里统一配置了请求访问规则，当前支持：
+
+- 静态资源默认放行
+- `@PermitAll` 标注的方法或类自动放行
+- `rdms.security.permit-all-urls` 配置的 URL 放行
+- 各业务模块通过 `AuthorizeRequestsCustomizer` 继续追加自定义规则
+- 其余请求默认需要认证
+
+其中 `AuthorizeRequestsCustomizer` 是一个扩展点，适合各模块自己补充 URL 安全规则。
+
+例如 WebSocket 模块就是通过继承这个类，把自己的连接地址加入放行规则。
+
+### 4.6 方法级权限校验
+
+模块开启了 `@EnableMethodSecurity`，并注册了名为 `ss` 的权限服务 Bean。
+
+因此业务代码可以直接写：
+
+```java
+@PreAuthorize("@ss.hasPermission('system:user:create')")
+public Long createUser(UserSaveReqVO reqVO) {
+    ...
+}
+```
+
+当前支持的能力包括：
+
+- `hasPermission`
+- `hasAnyPermissions`
+- `hasRole`
+- `hasAnyRoles`
+- `hasScope`
+- `hasAnyScopes`
+
+### 4.7 权限与角色远程校验
+
+权限、角色判断不是本地硬编码，而是通过 `PermissionCommonApi` 远程校验。
+
+为了减少频繁 RPC 调用，当前还做了本地 Guava 缓存：
+
+- 权限判断缓存 1 分钟
+- 角色判断缓存 1 分钟
+
+`scope` 判断则直接基于当前 `LoginUser.scopes` 完成。
+
+### 4.8 401 / 403 统一处理
+
+模块内提供了统一异常处理器：
+
+- `AuthenticationEntryPointImpl`：未登录访问需要认证的资源时返回 401
+- `AccessDeniedHandlerImpl`：已登录但权限不足时返回 403
+
+这样前端收到的是统一 JSON 结构，而不是默认的 Spring Security 页面或跳转行为。
+
+### 4.9 SecurityContext 跨线程传递
+
+模块把 `SecurityContextHolder` 的策略切换成了 `TransmittableThreadLocalSecurityContextHolderStrategy`。
+
+作用是：
+
+- 在 `@Async` 等异步线程场景下，尽量保留当前安全上下文
+- 减少使用普通 `ThreadLocal` 时上下文丢失的问题
+
+### 4.10 支持开发期 mock 登录
+
+当配置开启后，可以使用 mock token 构造登录用户，便于本地调试。
+
+这块能力由 `SecurityProperties` 中的以下配置控制：
+
+- `mock-enable`
+- `mock-secret`
+
+这类能力只适合开发调试环境，不适合生产环境开启。
+
+### 4.11 操作日志能力
+
+这个模块还同时集成了操作日志能力。
+
+当前实现方式是：
+
+1. 通过 `@EnableLogRecord` 开启日志能力
+2. 业务方法上使用 `@LogRecord`
+3. 本模块的 `LogRecordServiceImpl` 收集日志内容
+4. 自动补充用户信息、请求信息、链路追踪信息
+5. 通过 `OperateLogCommonApi` 异步上报
+
+日志中会补充的典型信息包括：
+
+- 用户 ID
+- 用户类型
+- 请求方法
+- 请求 URL
+- 请求 IP
+- User-Agent
+- TraceId
+
+## 5. 配置项
+
+当前可见的核心配置在 `rdms.security` 下：
+
+```yaml
+rdms:
+  security:
+    token-header: Authorization
+    token-parameter: token
+    mock-enable: false
+    mock-secret: test
+    permit-all-urls:
+      - /admin-api/system/auth/login
+    password-encoder-length: 4
+```
+
+说明：
+
+- `token-header`：请求头里 token 的字段名，默认是 `Authorization`
+- `token-parameter`：请求参数里 token 的字段名，主要兼容不能方便传 header 的场景
+- `mock-enable` / `mock-secret`：开发期 mock 登录控制
+- `permit-all-urls`：额外白名单 URL
+- `password-encoder-length`：BCrypt 加密强度
+
+## 6. 快速上手
+
+如果从“一个开发者接手后该怎么用”来理解，这个模块最常见的上手路径如下。
+
+### 6.1 引入依赖后，会自动得到什么
+
+业务模块引入这个 starter 后，默认会自动得到这些能力：
+
+- Spring Security 过滤链
+- Token 认证过滤器
+- `@EnableMethodSecurity`
+- `@ss` 权限表达式 Bean
+- 401 / 403 统一返回
+- Feign 的 `login-user` 透传
+- `@LogRecord` 操作日志能力
+
+也就是说，通常不需要你再手写一套 Security 配置类，除非业务模块有额外的特殊规则。
+
+### 6.2 最小配置怎么写
+
+最常见的基础配置如下：
+
+```yaml
+rdms:
+  security:
+    token-header: Authorization
+    token-parameter: token
+    mock-enable: false
+    permit-all-urls:
+      - /admin-api/system/auth/login
+      - /admin-api/system/auth/refresh-token
+```
+
+如果没有特殊需求，通常只需要确认：
+
+- 哪些接口要放行
+- token 从哪个 header 取
+
+### 6.3 一个新接口，默认是什么状态
+
+默认情况下：
+
+- 没有显式放行的接口，都会要求登录
+- 已登录后，如果方法上写了 `@PreAuthorize`，还会继续做权限校验
+
+也就是说，一个普通接口最常见的开发方式是：
+
+1. 默认需要登录
+2. 再按需要加权限注解
+
+例如：
+
+```java
+@PreAuthorize("@ss.hasPermission('system:user:query')")
+@GetMapping("/page")
+public CommonResult<PageResult<UserRespVO>> getUserPage(UserPageReqVO reqVO) {
+    ...
+}
+```
+
+### 6.4 哪些接口不需要登录，怎么做
+
+有两种常用方式。
+
+方式一：在接口或类上标 `@PermitAll`
+
+```java
+@PermitAll
+@GetMapping("/public-info")
+public CommonResult<String> getPublicInfo() {
+    ...
+}
+```
+
+方式二：通过配置白名单放行
+
+```yaml
+rdms:
+  security:
+    permit-all-urls:
+      - /admin-api/system/auth/login
+      - /admin-api/system/auth/refresh-token
+```
+
+实践建议：
+
+- 固定的公共接口、登录接口、刷新 token 接口，更适合放配置白名单
+- 个别无需登录的业务接口，更适合直接写 `@PermitAll`
+
+### 6.5 需要权限控制，怎么做
+
+最常用的是在 Controller 或 Service 方法上写 `@PreAuthorize`：
+
+```java
+@PreAuthorize("@ss.hasPermission('system:user:create')")
+@PostMapping("/create")
+public CommonResult<Long> createUser(@Valid @RequestBody UserSaveReqVO reqVO) {
+    ...
+}
+```
+
+当前可直接使用的表达式包括：
+
+- `@ss.hasPermission('xxx')`
+- `@ss.hasAnyPermissions('a', 'b')`
+- `@ss.hasRole('admin')`
+- `@ss.hasAnyRoles('admin', 'manager')`
+- `@ss.hasScope('user.read')`
+- `@ss.hasAnyScopes('a', 'b')`
+
+最常见的是 `hasPermission`。
+
+### 6.5.1 接口可以按三类理解
+
+从实际开发角度，可以把接口简单分成三类：
+
+1. 匿名可访问  
+   这类接口不要求登录。  
+   常见做法：
+   - 使用 `@PermitAll`
+   - 或加入 `rdms.security.permit-all-urls` 白名单
+
+2. 登录即可访问  
+   这类接口要求登录，但不校验具体 permission。  
+   常见做法：
+   - 不加 `@PermitAll`
+   - 不加白名单
+   - 也不加 `@PreAuthorize`
+
+   在当前配置下，这类接口会被默认的 `authenticated()` 规则保护：
+   - 未登录无法访问
+   - 已登录可以访问
+
+3. 登录后还要校验具体权限  
+   这类接口除了要求登录，还要求具备具体权限点。  
+   常见做法：
+   - 使用 `@PreAuthorize("@ss.hasPermission('xxx')")`
+
+一个比较实用的开发策略是：
+
+- 大部分普通接口只要求登录
+- 删除、导出、审批、分配等敏感动作再加具体权限校验
+
+### 6.6 权限校验是怎么触发的
+
+很多时候容易疑惑：`@PreAuthorize("@ss.hasPermission('system:dept:update')")` 这行代码本身没有手动调用 `PermissionCommonApi`，那远程权限校验是什么时候发生的？
+
+当前链路可以直接理解成下面这几步：
+
+```text
+请求进入服务
+-> TokenAuthenticationFilter 完成登录态恢复
+-> 请求到达 Controller / Service 方法前
+-> Spring Security 拦截 @PreAuthorize
+-> 解析表达式 @ss.hasPermission('system:dept:update')
+-> 调用 Spring 容器里的 ss Bean
+-> 进入 SecurityFrameworkServiceImpl.hasPermission(...)
+-> 转到 hasAnyPermissions(...)
+-> 先查本地 1 分钟缓存
+-> 缓存未命中时，调用 PermissionCommonApi 远程判断权限
+-> 返回 true：允许进入方法
+-> 返回 false：拒绝访问，返回 403
+```
+
+可以把它理解为：
+
+- `@PreAuthorize` 负责“触发权限判断”
+- `@ss` 负责“找到权限判断 Bean”
+- `SecurityFrameworkServiceImpl` 负责“执行权限判断逻辑”
+- `PermissionCommonApi` 负责“向权限服务查询结果”
+
+所以真正触发 `PermissionCommonApi` 的，不是 Controller 代码手动调用，而是 Spring Security 在执行 `@PreAuthorize` 表达式时自动触发。
+
+### 6.7 业务代码里怎么拿当前登录用户
+
+最常用的是通过 `SecurityFrameworkUtils` 获取：
+
+```java
+Long userId = SecurityFrameworkUtils.getLoginUserId();
+String nickname = SecurityFrameworkUtils.getLoginUserNickname();
+Long deptId = SecurityFrameworkUtils.getLoginUserDeptId();
+```
+
+如果需要更完整的信息：
+
+```java
+LoginUser loginUser = SecurityFrameworkUtils.getLoginUser();
+```
+
+适用场景：
+
+- 新增、修改数据时记录操作人
+- 查询当前用户自己的数据
+- 记录审计字段
+
+### 6.8 为什么跨服务还能拿到当前用户
+
+当前项目的链路是这样的：
+
+1. 前端把 token 传给网关
+2. 网关校验 token 后，把用户信息转成 `login-user` 请求头
+3. 下游服务读取 `login-user`，恢复 `LoginUser`
+4. 如果下游服务再通过 Feign 调别的服务，`LoginUserRequestInterceptor` 会继续透传 `login-user`
+
+所以开发时可以这样理解：
+
+- Web 入口主要靠 token 建立登录态
+- 服务间调用主要靠 `login-user` 继续传递登录态
+
+### 6.9 什么时候需要自己补 URL 规则
+
+如果某个模块有特殊放行需求，可以继承 `AuthorizeRequestsCustomizer`。
+
+例如：
+
+```java
+public class XxxAuthorizeRequestsCustomizer extends AuthorizeRequestsCustomizer {
+
+    @Override
+    public void customize(AuthorizeHttpRequestsConfigurer<HttpSecurity>.AuthorizationManagerRequestMatcherRegistry registry) {
+        registry.requestMatchers("/xxx/**").permitAll();
+    }
+}
+```
+
+常见场景：
+
+- WebSocket 握手地址
+- 第三方回调接口
+- 某些模块自己的公共入口
+
+### 6.10 需要记录操作日志，怎么做
+
+在业务方法上直接加 `@LogRecord`：
+
+```java
+@LogRecord(type = "SYSTEM_USER", subType = "CREATE", bizNo = "{{#user.id}}",
+        success = "创建用户成功")
+public Long createUser(UserSaveReqVO reqVO) {
+    ...
+}
+```
+
+这个注解更适合加在“有明确业务动作”的方法上，例如：
+
+- 新增用户
+- 修改角色
+- 删除字典
+- 分配权限
+
+### 6.11 开发时最容易混淆的几个点
+
+1. 这个模块负责“认证接入和权限执行”，不负责 token 签发  
+   token 的签发和存储仍在系统服务等其他模块。
+
+2. 当前跨服务透传的是 `login-user`，不是原始 token  
+   所以下游服务能识别当前用户，不等于它一直拿着原始 `Authorization`。
+
+3. 不加 `@PreAuthorize` 不代表匿名可访问  
+   默认仍然需要登录，只是不会进一步做权限点校验。
+
+4. `@PermitAll` 和 `permit-all-urls` 都是放行登录校验  
+   放行后通常也不会再走权限控制。
+
+## 7. 常见使用方式
+
+### 7.1 方法权限控制
+
+```java
+@PreAuthorize("@ss.hasPermission('system:user:query')")
+@GetMapping("/page")
+public CommonResult<PageResult<UserRespVO>> getUserPage(UserPageReqVO reqVO) {
+    ...
+}
+```
+
+适用场景：
+
+- 控制某个接口必须具备某个权限点
+- 细粒度控制新增、修改、删除、导出等操作
+
+### 7.2 放行无需登录的接口
+
+方式一：直接标注 `@PermitAll`
+
+```java
+@PermitAll
+@GetMapping("/public-info")
+public CommonResult<String> getPublicInfo() {
+    ...
+}
+```
+
+方式二：通过配置加入白名单
+
+```yaml
+rdms:
+  security:
+    permit-all-urls:
+      - /admin-api/system/auth/login
+      - /admin-api/system/auth/refresh-token
+```
+
+### 7.3 为某个模块补充 URL 安全规则
+
+如果某个模块有自己的特殊放行需求，可以继承 `AuthorizeRequestsCustomizer`：
+
+```java
+public class XxxAuthorizeRequestsCustomizer extends AuthorizeRequestsCustomizer {
+
+    @Override
+    public void customize(AuthorizeHttpRequestsConfigurer<HttpSecurity>.AuthorizationManagerRequestMatcherRegistry registry) {
+        registry.requestMatchers("/xxx/**").permitAll();
+    }
+}
+```
+
+适用场景：
+
+- WebSocket 握手地址放行
+- 回调接口放行
+- 某些特殊模块追加自己的 URL 规则
+
+### 7.4 记录操作日志
+
+```java
+@LogRecord(type = "SYSTEM_USER", subType = "CREATE", bizNo = "{{#user.id}}",
+        success = "创建用户成功")
+public Long createUser(UserSaveReqVO reqVO) {
+    ...
+}
+```
+
+适用场景：
+
+- 新增、修改、删除等需要审计的核心业务动作
+- 希望把操作人、请求来源、业务对象编号一起记录下来
+
+## 8. 模块边界
+
+阅读这个模块时，需要把“它负责什么”和“它不负责什么”分开看。
+
+当前它负责：
+
+- 接入 Spring Security
+- 解析 token 或 `login-user`
+- 构建登录用户上下文
+- 提供权限判断能力
+- 统一未登录 / 未授权响应
+- 透传 `LoginUser`
+- 集成操作日志记录
+
+当前它不负责：
+
+- token 的签发
+- 权限数据本身的维护
+- 用户、角色、菜单、权限模型的存储
+- 原始 `Authorization` 的 Feign 透传
+
+这些数据来源和业务模型，当前仍由系统服务等其他模块提供。
+
+## 9. 总结
+
+`rdms-spring-boot-starter-security` 当前已经是一个实际落地的基础模块，不是占位模块。
+
+从当前代码看，它的核心价值在于：
+
+- 统一接入认证与权限体系
+- 把登录用户上下文在 Web、Spring Security、Feign 调用之间串起来
+- 给业务层提供简单直接的权限表达式入口
+- 把操作日志能力收进统一基础设施
+
+如果后续继续扩展，这个模块仍然适合承接更多安全通用能力，例如：
+
+- 原始 token 透传
+- 更细的权限表达式
+- 更完整的审计日志字段
+- 更严格的跨租户访问控制