F2-6: 验收报告 + 迁移手册 64KB 缓解条目标记已回收

- docs/P1/F2-6JWT瘦身报告.md:token 长度对比、缓存策略、单测/集成/e2e 终验、提交哈希
- docs/迁移手册.md §8.8:F1-7 64KB 缓解条目标记「已回收 F2-6 2026-06-12」,记录根治方案与验收数据
This commit is contained in:
2026-06-12 03:11:33 +08:00
parent 7a5a84460c
commit 237c51bda1
2 changed files with 148 additions and 0 deletions

View File

@@ -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 限制在任意角色数下均不触碰。

View File

@@ -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 <module>` 的嵌套 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` 参数