Files
eip4-platform/docs/P1/F2-6JWT瘦身报告.md
zhengwr 237c51bda1 F2-6: 验收报告 + 迁移手册 64KB 缓解条目标记已回收
- docs/P1/F2-6JWT瘦身报告.md:token 长度对比、缓存策略、单测/集成/e2e 终验、提交哈希
- docs/迁移手册.md §8.8:F1-7 64KB 缓解条目标记「已回收 F2-6 2026-06-12」,记录根治方案与验收数据
2026-06-12 03:11:33 +08:00

136 lines
4.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 限制在任意角色数下均不触碰。