docs(运维): 守卫绑定一栏改为已实现,补 role 分布与 uid 同源的取证

This commit is contained in:
2026-09-28 02:31:36 +08:00
parent b3472dbd8a
commit f8e642588d
+22 -7
View File
@@ -34,16 +34,31 @@
两个可分开的动作:
| 动作 | 效果 | 代价 | 建议 |
| 动作 | 效果 | 代价 | 状态 |
|---|---|---|---|
| **A. 绑定**:请求带 JWT 时,校验 `user_id` 参数必须等于令牌身份;管理员令牌可代客查询;匿名请求不参与绑定 | 已登录用户不能再互相冒读,109 处调用点不用逐个改 | 对匿名客户端零影响(它们本来就没令牌) | **可做**,风险最低 |
| **A. 绑定**:请求带 JWT 时,校验 `user_id` 参数必须等于令牌身份;管理员令牌可代客查询;匿名请求不参与绑定 | 已登录用户不能再互相冒读,19 个 controller 文件不用逐个改 | 对匿名与内部令牌调用零影响 | **已实现**(见下"绑定的落地依据") |
| **B. 要求凭据**:把上述前缀纳入兜底鉴权(开关置 true) | 未登录直接 401 | 按上面的取证,约 11/15 个调用文件的现网客户端会整条产品线 401 | **等客户端普遍携带凭据之后再开** |
动作 A 的实现规格已经写好了:另一窗口留下的 490 行 `AdminApiGuardFilterTest`(现存
`数富AI/tmp/AdminApiGuardFilterTest.wip.java`)用 6 个用例定义了行为,包括"非数字 `user_id` 交回
controller 报错""管理员可为他人代查"。它当时跑不起来的原因不是逻辑分歧,是文件本身没写完:
第 472 行调用的 **5 参 `newFilter` 在同文件里没有定义**(对应一个"按前缀分批开启"的白名单字段),
`AdminAuthSupport.currentRole(AdminUserEntity)` 已存在、可直接用。补齐 helper 与该字段即可转绿。
绑定的落地依据(今晚逐条查证,不是推断):
- 角色词汇表只有三态:`DeviceSessionPolicy.resolveRole` 只会返回 `super_admin` / `admin` / `null`,
没有第三种"员工"角色;生产 `users` 表 135 个账号分布为 `normal` 子账号 120、`admin` 子账号 13、
`admin` 1、`super_admin` 1 → 管理员豁免面闭合。
- 网页端 `getCurrentUserId()` 读 `localStorage['uid']`,而 `uid` 由登录响应 `data.userId` 写入;
`AuthService.buildResult` 里 `vo.setUserId(user.getId())` 与 `jwtService.issue(user.getId(), …)` 同源
→ 诚实客户端的参数**恒等于**令牌主体,正常用户不会撞 403。
- `frontend-vue` 各 tab 一律传 `getCurrentUserId()` / `uidForStorage()`;只有 `admin-frontend-vue` 传任意
`user_id`,而它是管理员身份 → 落在豁免里。
- 带凭据的 4 个桌面模块(`price_match_new` / `search_spider` / `tool` / `log_uploader`)用的都是
`X-Internal-Token`,在 `shouldNotFilter` 里由 `isTrustedInternalToken` 提前整体放行,**不参与绑定**。
- 实现范围刻意收窄到 `USER_TOOL_PREFIXES`:`/api/admin`、`/debug`、自助接口仍只做"有没有身份",
不做参数比对,避免误伤后台里合法传他人 id 的流程。
- 代价:每个带 `user_id` 的用户态请求会多走一次 `requireUserOrInternal`。匿名请求在 `resolveToken`
处即抛 `BusinessException`(未登录)返回,**不查库**,但会构造一个带栈异常。按现网这个接口的
轮询频率,量级可忽略,若日后要省掉,可加"仅在带了凭据线索时才解析"的短路。
紧急回退仍是一个:`aiimage.security.admin-guard-enabled=false` 会把绑定与原有兜底一起关掉。
若要单独关绑定,需要另加开关(当前没有,按规格它就是无条件生效的)。
### 2. 主机A MySQL:`innodb_buffer_pool_size=8G` 与容器上限 6 GiB 冲突