diff --git a/docs/P1/F2-6JWT瘦身报告.md b/docs/P1/F2-6JWT瘦身报告.md new file mode 100644 index 0000000..e79faa1 --- /dev/null +++ b/docs/P1/F2-6JWT瘦身报告.md @@ -0,0 +1,135 @@ +# F2-6 JWT 瘦身报告 + +**日期**:2026-06-12 +**状态**:已完成,所有验收项通过 + +--- + +## 一、问题根因(F1-7 实锤) + +| 用户 | 角色数 | 旧 token 长度 | 症状 | +|------|--------|--------------|------| +| admin | ~10 | 6,413 字符 | 接近 8KB 上限 | +| ceshi | 236 | 16,924 字符 | 超 Tomcat 默认 8KB → 直接 400 | + +临时缓解:两服务 yml 均设 `max-http-request-header-size: 64KB`(注释标记「根治后回收」)。 + +下游二次膨胀:flow-gateway 把全部 roles 作 `candidateGroup` 拼入 GET URL,ceshi 236 角色 × 36 字符 ≈ 8.5KB,flowable-service 同样触发 `Request header is too large`。 + +--- + +## 二、方案 + +### 2.1 JWT 不携带 roles + +**`JwtService.issue()`**:移除 `CLAIM_ROLES`,token payload 仅含 `userId/account/name/depart/org/iat/exp/iss`。 + +**`JwtService.parse()`**:roles 固定返回 `List.of()`,由调用方填充。 + +### 2.2 服务端 RoleResolver(Caffeine 缓存) + +新建 `platform-auth/.../RoleResolver`: + +``` +SQL:sys_usergrouprole ⋈ sys_usergroupuser WHERE ugu.userid = ? +缓存:Caffeine,expireAfterWrite=5min,maximumSize=5000 +降级:DB 不可达时返回空列表,不阻断请求 +``` + +`JwtAuthFilter` 在 parse 后调 `RoleResolver.resolve(userId)` 填充 roles,`AuthPrincipal` 接口对下游零变动。 + +### 2.3 缓存失效钩子 + +`AdminWriteController`(platform-metadata): + +| 端点 | 失效操作 | +|------|---------| +| `add-user` / `remove-user` | `roleResolver.evict(userId)` | +| `add-role` / `remove-role` / `delete-usergroup` | `roleResolver.evictAll()` | + +变更低频,`evictAll` 兜底 + TTL 5 分钟自然过期双重保障。 + +### 2.4 candidateGroup URL 膨胀修复 + +- flowable-service 新增 `POST /api/flow/tasks/todo`,`candidateGroups` 放 body +- `FlowableClient.todo()` 改用 POST body,新增 `post(ParameterizedTypeReference)` 重载 +- 旧 GET 接口保留不删(向下兼容) + +### 2.5 64KB 缓解配置回收 + +- `platform-app/src/main/resources/application-dev.yml`:删除 `max-http-request-header-size: 64KB` +- `flowable-service/src/main/resources/application.yml`:删除 `max-http-request-header-size: 64KB` + +--- + +## 三、单测覆盖 + +| 测试类 | 覆盖点 | 结果 | +|--------|--------|------| +| `RoleResolverTest` | 首次查库、缓存命中(第二次不查库)、evict 后重查、evictAll、DB 异常降级、null/空白 userId | 6/6 | +| `JwtServiceTest` | roles 不入 token(parse 返 `[]`)、token <1KB | 10/10 | +| `EngineContextIsolationTest` | bind/clear、过滤器收尾清空、无令牌不污染、16线程×200次并发不串号 | 4/4 | +| `SecurityProfileTest` | prod 链 401、非 prod 放行、登录端点放行 | 3/3 | +| `AdminWriteControllerTest` | 适配 RoleResolver mock | 14/14 | +| platform-auth 合计 | | **23/23** | +| platform-metadata 合计 | | **153/153** | + +--- + +## 四、集成验证(默认 8KB 头限制下) + +``` +admin token:316 字符 (旧 6,413) ✓ <1KB +ceshi token:344 字符 (旧 16,924) ✓ <1KB + +GET /api/todo(ceshi,默认 8KB 限制) + → 2 条「接收交底(项目部)」待办,未 complete ✓ + +GET /api/menu(admin) + → 13 个根菜单 ✓ + +POST /api/admin/usergroups/{id}/add-role → 200,evictAll 触发 ✓ +``` + +--- + +## 五、缓存策略说明 + +| 维度 | 设计 | +|------|------| +| 存储 | Caffeine 进程内本地缓存,无外部依赖 | +| TTL | 5 分钟 `expireAfterWrite`(无写操作自然过期) | +| 容量 | 5,000 条(单客户用户规模上限) | +| 主动失效 | 成员加减 → `evict(userId)`;组角色变更/删组 → `evictAll()` | +| 降级 | DB 不可达 → 返回 `List.of()`,不抛异常,请求继续(角色维度过滤降级为不过滤) | +| 线程安全 | Caffeine 内置,无额外同步 | + +--- + +## 六、e2e 终验 + +``` +npx playwright test(50 tests) +→ 50 passed (51.9s) ✓ +``` + +--- + +## 七、提交记录 + +| commit | 内容 | +|--------|------| +| `2f1f00a` | F2-6: JWT 瘦身——roles 不入 claims,RoleResolver 服务端缓存解析 | +| `2dcc0c6` | F2-6: candidateGroup URL 膨胀修复 + 角色缓存失效钩子 | +| `7a5a844` | F2-6: 回收 F1-7 64KB 请求头缓解配置(根治完成) | + +--- + +## 八、token 长度前后对比 + +| 用户 | 根治前 | 根治后 | 压缩率 | +|------|--------|--------|--------| +| admin | 6,413 字符 | 316 字符 | -95% | +| ceshi | 16,924 字符 | 344 字符 | -98% | + +两用户 token 均降至 400 字节以下,远低于 HTTP/1.1 典型头部预算。Tomcat 默认 8KB 限制在任意角色数下均不触碰。 diff --git a/docs/迁移手册.md b/docs/迁移手册.md index 732a44a..d6003e2 100644 --- a/docs/迁移手册.md +++ b/docs/迁移手册.md @@ -837,3 +837,16 @@ com.dsasp.* com.eip4.* - **根因**:某次 `mvn install` 把当时的模块 SNAPSHOT 装进 ~/.m2;此后 spring-boot repackage 解析依赖时优先取 ~/.m2 安装版而非 reactor 产物(离线模式尤甚),新代码永远进不了 fat jar。 - **对策**:**标准重启口径升级为 `mvn -o -pl platform-app -am clean install -DskipTests`**(install 刷新 ~/.m2 同步);怀疑时核 `unzip -l fat.jar | grep ` 的嵌套 jar 字节数/时间戳与模块 target 比对。 - **教训**:任何「代码在但运行时 404」先核 fat jar 内嵌套 jar 的新鲜度,再查注解/扫描。 + +### 8.8 F1-7 缓解条目 [已回收 F2-6 2026-06-12] + +- **原缓解**(F1-7):JWT 把全部角色塞进 claims,ceshi 用户 16,924 字符超 Tomcat 默认 8KB 请求头限制直接 400。 + 临时将 `platform-app application-dev.yml` 和 `flowable-service application.yml` 均设置 `max-http-request-header-size: 64KB`。 +- **根治方案**(F2-6): + 1. `JwtService.issue()` 移除 `CLAIM_ROLES`,token 仅携带 userId/account/name/depart/org + 2. 新增 `RoleResolver`(Caffeine 缓存 TTL 5 分钟,容量 5000),`JwtAuthFilter` 每次请求按 userId 查角色 + 3. `AdminWriteController` 用户组/角色变更端点调 `evict/evictAll` 主动失效缓存 + 4. `FlowableClient.todo()` 改用 POST body 传 `candidateGroups`(避免 236 角色 URL 膨胀) + 5. flowable-service 新增 `POST /api/flow/tasks/todo` 端点接收 body +- **验收数据**:admin token 316B / ceshi token 344B(原 6413 / 16924);默认 8KB 限制下 ceshi /api/todo 返回 2 条待办,admin /api/menu 13 roots;e2e 50/50 +- **状态**:两 yml 的 64KB 配置已删除,标准重启口令不再含 `--server.max-http-request-header-size` 参数