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:
135
docs/P1/F2-6JWT瘦身报告.md
Normal file
135
docs/P1/F2-6JWT瘦身报告.md
Normal 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 限制在任意角色数下均不触碰。
|
||||
Reference in New Issue
Block a user