diff --git a/docs/ops/prod-decisions-2026-09-28.md b/docs/ops/prod-decisions-2026-09-28.md index 808ba13ff..4a725a751 100644 --- a/docs/ops/prod-decisions-2026-09-28.md +++ b/docs/ops/prod-decisions-2026-09-28.md @@ -112,7 +112,8 @@ instanceId `server-110`/`server-121`、ERROR 0 条、绑定 403 0 条、`[admin- - `frontend-vue` 各 tab 一律传 `getCurrentUserId()` / `uidForStorage()`;只有 `admin-frontend-vue` 传任意 `user_id`,而它是管理员身份 → 落在豁免里。 - 带凭据的 4 个桌面模块(`price_match_new` / `search_spider` / `tool` / `log_uploader`)用的都是 - `X-Internal-Token`,在 `shouldNotFilter` 里由 `isTrustedInternalToken` 提前整体放行,**不参与绑定**。 + `X-Internal-Token`,且**不带 JWT、不带 `operatorId`** → `requireUserOrInternal` 解析不出身份 → 绑定不触发, + 行为与收紧前一致。("令牌可信即在 `shouldNotFilter` 整体放行"曾是绕开绑定的洞,17:3x 已收窄,见 §十四。) - 实现范围刻意收窄到 `USER_TOOL_PREFIXES`:`/api/admin`、`/debug`、自助接口仍只做"有没有身份", 不做参数比对,避免误伤后台里合法传他人 id 的流程。 - 代价:每个带 `user_id` 的用户态请求会多走一次 `requireUserOrInternal`。匿名请求在 `resolveToken` @@ -190,6 +191,16 @@ V137 只把它们置为不可见,**观察 1~2 周慢日志无退化后要追 这是口径变化不是掉量;要还原真实工作量应看"检测行数"而不是"调用次数"。花钱的降幅比次数小得多 (约 30–45%),且走的是用户自己的 apiKey 额度。 +可直接粘给运营/客服的口径(客户问"次数怎么突然少了"就用这段): + +> 9 月 28 日起,外观专利检测把多个商品的图片**合并成一次批次请求**,所以后台「LLM 使用」里的 +> **调用次数会下降到大约 1/6.7**(原来 10 行约 20 次,现在约 3 次)。这是统计口径的变化, +> 不代表检测行数变少、也不代表结果变粗——要核对工作量请看「检测行数」,它不受合并影响。 +> 费用确实会降,幅度大约 30–45%,扣的是您自己的模型额度,与平台账单无关。 + +需要人工确认的一件事:这句话要不要同步给**已经在看这个报表的客户**(发版当天就有 6.7 倍的断崖, +事后解释比事前打招呼难做)。 + ### 7. 监控指标:端点根本不存在,告警无从挂起 `backend-java/pom.xml` 只有 `spring-boot-starter-actuator`,没有 `micrometer-registry-prometheus`; @@ -1218,3 +1229,113 @@ RUNNING 行等满 5 分钟阈值"一致,是兜底在正常工作,没有作 B 的启动行在 17:14 那次读是空的,因为取的是 `--since 8m` 窗口而 B 是 17:05 重启的; 17:07 那次单独读 B 已确认两行都在(`enabled=false`)。**这类"空窗口"别当成"没打"**。 +## 十四、内部令牌能绕开刚上线的归属绑定(已修,17:3x) + +§二.1 的"绑定"落地时我只核对到"匿名请求解析不出身份所以不受影响",漏了一类请求:**同时带 JWT 与 +X-Internal-Token** 的。这一类在 `shouldNotFilter` 里就被整体放行了,根本没走到绑定判断。 + +### 14.1 洞在哪、为什么不是理论问题 + +`AdminApiGuardFilter.shouldNotFilter` 原来是: + +```java +if (adminAuthSupport.isTrustedInternalToken(request)) { + return true; // ← 连带把 190-206 行的 user_id 归属绑定一起跳过 +} +``` + +而 `isTrustedInternalToken` 只比对令牌字面量、不要求 `operatorId`。这把钥匙**硬编码在分发出去的桌面客户端里**: +`app_client/amazon/tool.py:20` 与 `app_client/crawler_core/log_uploader.py:38` 各有一份 32 字符常量, +随安装包到每个用户手上。于是"手上有一个桌面端"就等于"有了一把能过 shouldNotFilter 的万能钥匙", +再配上别人的登录令牌,`user_id` 想填谁填谁——刚收紧的绑定对这条组合完全失效。 + +### 14.2 取证:为什么改完对现网零影响 + +| 核对项 | 方法 | 结果 | +| --- | --- | --- | +| 有没有调用方靠"内部令牌 + operatorId"解析出身份来做代客操作 | 全工作区 `grep -ir 'operator_?id' --include=*.py`(含 `app_client`、`backend`) | **0 处**。所以纯令牌请求进 `requireUserOrInternal` 后:无 JWT → `resolveToken` 抛"未登录" → `resolveInternalOperator` 因没有 `operatorId` 返回 null → 外层再抛 → filter 里 identity=null → **绑定不触发** | +| 真实客户端里最像的形状 | `price_match_new.py:1290-1302`:内部令牌 + `params={"user_id": user_id}`、无 JWT,回调 `/api/shop-match/tasks/{id}/stage-finished` | 落在上一行:解析不出身份 → 照旧放行 | +| 多出来的开销 | `AdminAuthSupport.java:40-43` | 无 token 时**第一行即抛**,不查库、不查 redis,只多构造一个异常 | +| 不带 `user_id` 的内部回调(按 task_id 那类) | 新用例 `internalTokenOnTaskScopedCallbackStaysExempt` | `needsOwnershipBinding` 先判 `isUserToolPrefix`、再判参数非空,所以 `/api/admin`、`/debug`、自助前缀与不带 `user_id` 的回调**仍然整体跳过守卫**,连身份解析都不会跑(`verify(never())` 守住) | + +### 14.3 改法:只把"要不要凭据"与"归属归谁"这两件事拆开 + +```java +if (adminAuthSupport.isTrustedInternalToken(request) && !needsOwnershipBinding(request, uri)) { + return true; +} +``` + +- "要不要凭据"这一半**仍由令牌豁免**:`/api/admin/shop-manages/credential` 这类"仅凭令牌即鉴权"的内部端点 + 继续由 controller 自校验,不会被守卫误拦 401。 +- "归属归谁"不再随令牌豁免:管理员/超管的代客操作豁免(`mayActForOtherUsers`)照旧,所以后台按客户查任务不受影响。 + +### 14.4 测试 + +`AdminApiGuardFilterTest`(576 行 / **30 个用例,全绿**)新增 4 个,其中第 1 个在改代码**之前是红的**—— +它就是那个洞的可执行证明: + +| 用例 | 断言 | +| --- | --- | +| `internalTokenDoesNotBypassOwnershipBinding` | 令牌可信 + 能解析出 `user(7)`、`user_id=8` → 链不往下走、响应体 `code=403` | +| `internalTokenWithoutLoginIdentityIsNotBound` | 令牌可信但解析不出身份 → 放行、响应体为空(守住 14.2 那条客户端形状) | +| `internalTokenOnTaskScopedCallbackStaysExempt` | 不带 `user_id` 的回调 → 放行且**一次身份解析都不跑** | +| `adminInternalOperatorIsStillExemptFromBinding` | 解析出的身份 role=admin → 放行 | + +### 14.5 验收判据(发版后读) + +- 两台 md5 一致、health 200、启动异常 0(沿用既有口径)。 +- **基线为 0**:17:4x 取证,两台近 60 分钟 `[admin-guard]` 日志 0 条(401 已降 debug,所以这 0 条本身就是 + "没有非典型拒绝")。上线后若出现 `[admin-guard] … 拒绝:登录身份 id=… 与请求参数 user_id=… 不一致`, + 说明存在"带 JWT 且 user_id≠身份"的真实调用方,按日志里的 uri 与 remoteAddr 定位后再决定要不要收。 +- 回退只有一档:`aiimage.security.admin-guard-enabled=false` 会把守卫连同绑定一起关掉(当前没有单独开关)。 + +## 十五、结果文件写 xlsx 的输出流没有缓冲:一次 8k 图片导出白花 7 秒(已修) + +引出这件事的是全量测试里唯一的红:`ExcelCellImageWriterTest.patchesTenThousandImageCellsWithinLinearTimeBudget` +10 秒墙钟预算超时(3275 个用例里 1 个失败)。**先查了它是不是被我改的东西带红的**——不是:单独跑该类同样失败 +(10.40s),且该类不引用任何本次改动。于是按性能问题查。 + +### 15.1 分阶段实测(本机,10 000 张 1 字节占位图) + +| 阶段 | 耗时 | +| --- | --- | +| 造输入 xlsx(`writeWorkbookWithImageCells`) | 36–110ms | +| `registerImage` × 10k | 21–25ms | +| `patchSheet`(正则逐个替换 10k cell) | 192ms | +| 6 个 richValue/metadata part 的 build+write | 71ms | +| **media loop(写 10k 个 entry)** | **2969ms** | +| **`ZipOutputStream.close()`(写中央目录 10k 条)** | **≈4071ms**(由累计值推导) | +| `Files.move` 替换原文件 | 1484ms(Windows 杀软按关闭时机扫文件,代码侧无解) | +| 合计 `patchXlsxFile` | 7380ms(另两次运行 10.4s / 12.4s,抖动主要来自 FS 缓存) | + +### 15.2 根因与修法(一行,产物字节不变) + +两个写器都是 `new ZipOutputStream(Files.newOutputStream(tmp))`——**没有套缓冲流**。 +`Files.newOutputStream` 返回的是 channel 流,于是每个 entry 的 local header、数据、末尾的中央目录记录 +各发一次小 write,10k 图片 = 三万次 syscall,`close()` 那 4 秒全是在写中央目录。 +修法是包一层 `new BufferedOutputStream(…, 64 * 1024)`:zip 是纯顺序写,缓冲不改变产物内容。 + +改的两处:`WpsCellImageWriter.java:140`(**现网在用的那个**)与 `ExcelCellImageWriter.java:88` +(同一缺陷,顺手对齐;这个类本身见 15.4)。 + +### 15.3 为什么这不是"为凑绿改测试" + +- 测试文件一个字没动:预算仍是 10 秒,`git diff` 对该测试类为空(临时的分阶段打印与放宽预算的量测代码已全部撤销)。 +- 修后同一用例 **1.811s**(另一次 5.394s),相对 10s 预算有 2 倍以上余量;修前 10.4–12.4s 必然贴边。 +- 现网确实吃这段:主机A 近 24h 日志里 `[wps-dispimg]` 的 `images=` 最大到 **8058**(样本 30 / 807 / 1019 / + 1242 / 4018 / 5010),也就是说单次导出真的会写几千个 entry,省下的秒数是真实发生的。 + +### 15.4 顺带查清的一件事:`ExcelCellImageWriter` 已经没人用了 + +`grep` 全 main 目录:该类只在自己文件里出现,**生产调用者为 0**;现网走的是 +`SimilarAsinResultWorkbookAssembler:763/877` → `WpsCellImageWriter`(提交 `b3f7b81b 货源结果图回WPS DISPIMG` +之后 Excel 原生 IMAGE 那条线被回退,类和它的测试留在了树里)。要不要连测试一起删掉,属另一件事,本轮只对齐了缓冲。 + +### 15.5 没做的一件事(留给有人对着真图验) + +JPEG 图片 entry 现在仍走 DEFLATE。JPEG 本身已压过,再 deflate 基本是纯 CPU 浪费(改 STORED 需要给每个 entry +预置 size/CRC/compressedSize)。**没有做**,因为那会改变产物字节,必须先用真图 + WPS/Excel 打开回归验一遍, +而本轮的判据是"不改语义"。 + +