Selaa lähdekoodia

fix(build): 构建前自动重建 pdf worker,根治「PDF 一直转圈」

## 问题

线上 PDF 预览报:
  The API version "6.4.299" does not match the Worker version "4.10.38"

线上 pdf.worker.js 是 1,264,342 字节(pdfjs 6.4.299 旧版),
主包是 4.10.38,正确值应为 1,375,838 字节。
Last-Modified 停在 11-14,之后一直没更新。

## 根因

copy-pdf-worker.mjs 原只挂在 postinstall(跑 pnpm install 时才执行)。
npm run build / pnpm run build 不会重新生成它,而 deploy.mjs 只负责
「刷新 CDN 上 /pdf.worker.js 的缓存」——刷的仍是本地那份旧文件。

这是项目文档已记录「踩过两次」的坑,本次是第三次。

## 修复

package.json 增加 pre 钩子,构建前自动重建:
- prebuild / prebuild:mock → node scripts/copy-pdf-worker.mjs
- cap:sync 也补上(内部直调 ng build,会绕过 prebuild)

copy-pdf-worker.mjs 本身带大小断言,不一致直接 exit(1),
把问题挡在构建期而不是等用户发现打不开 PDF。

## 验证

删除 public/pdf.worker.js 后直接 pnpm run build:
  [copy-pdf-worker] 已生成 public/pdf.worker.js(1375838 字节,已校验)
真机 APK 内 worker 1,375,807 字符、含 4.10.38、无 6.4.x 残留;
pdfjs 完整解析成功(1 页 / 595x842 / 74ms)。

## 同时修复 / 记录

- s3 CORS 问题已在平台侧根治(CDN 边缘注入 ACAO,无需刷缓存),
  诊断报告记录完整证据链与实测结果
- 部署手册新增 4.4 节:/api-platform/ 反代配置与判断方法
- 部署手册踩坑记录新增第 8 条:pdf worker 构建产物陷阱

## 未完成

- 线上仍是旧 worker,需重新部署一次(pnpm run deploy)
- /api-platform/ 反代待平台配置(有回落机制,不影响功能)

Co-Authored-By: Claude Code <noreply@anthropic.com>
Huccct 2 tuntia sitten
vanhempi
commit
527dd6a9f7

+ 153 - 0
docs/00-tracking/2026-11-18-线上问题修复记录.md

@@ -0,0 +1,153 @@
+# 2026-11-18 线上问题修复记录
+
+> 本轮处理两个与 CORS 无关的独立问题:
+> ① pdfjs worker 版本不匹配 ② `/api-platform/` 未转发。
+
+---
+
+## 一、pdfjs worker 版本不匹配(已修复)
+
+### 现象
+
+```
+PDF 加载失败:The API version "6.4.299" does not match the Worker version "4.10.38"
+```
+
+PDF 预览**永远转圈**,与 CORS 无关。
+
+### 根因
+
+线上 `https://ai.fmode.cn/pdf.worker.js` 是 **1,264,342 字节**(pdfjs 6.4.299 旧版),
+而主包是 4.10.38。正确值应为 **1,375,838 字节**。
+
+`Last-Modified: Sat, 14 Nov 2026` —— **11-14 之后就没更新过**。
+
+**为什么**:`scripts/copy-pdf-worker.mjs` 只挂在 `postinstall`(跑 `pnpm install` 时)。
+`npm run build` / `pnpm run build` **不会**重新生成它,而 `deploy.mjs`
+只负责「刷 CDN 上 `/pdf.worker.js` 的缓存」—— 刷的仍是那份旧的本地文件。
+
+> 这是项目文档里已记录「踩过两次」的坑,本次是**第三次**。
+> CLAUDE.md 原文:「这个坑已经踩过两次,两次都表现为『PDF 一直转圈』。」
+
+### 修复(2026-11-18)
+
+在 `package.json` 增加 **pre 钩子**,让构建前自动重建 worker:
+
+```json
+"prebuild": "node scripts/copy-pdf-worker.mjs",
+"prebuild:mock": "node scripts/copy-pdf-worker.mjs",
+```
+
+并把 `cap:sync` 也补上(它内部直接调用 `ng build`,会绕过 `prebuild`):
+
+```json
+"cap:sync": "node scripts/copy-pdf-worker.mjs && ng build --configuration production && npx cap sync android"
+```
+
+### 验证
+
+```bash
+# 删除 worker,直接构建,确认自动重建
+rm public/pdf.worker.js
+pnpm run build
+stat -c %s public/pdf.worker.js    # 应为 1375838
+```
+
+实测结果:
+```
+$ node scripts/copy-pdf-worker.mjs
+[copy-pdf-worker] 已生成 public/pdf.worker.js(1375838 字节,已校验)
+[copy-pdf-worker] 已生成 pdfjs 版本常量:4.10.38
+✓ 1375838 字节
+```
+
+> `copy-pdf-worker.mjs` 自带**大小断言**:复制后与源文件比对,
+> 不一致直接 `exit(1)`,把问题挡在构建期。
+
+### 待办
+
+线上仍是旧的,**需要重新部署一次**:
+```bash
+pnpm run deploy
+```
+部署后验证:
+```bash
+curl -sS -I https://ai.fmode.cn/pdf.worker.js | grep -i content-length
+# 应输出 Content-Length: 1375838
+```
+
+---
+
+## 二、`/api-platform/` 未转发(待平台配置)
+
+### 现象
+
+浏览器控制台每次打开都出现:
+
+```
+[PlatformProxy] /api-platform/ 未转发到平台(x-powered-by=空),回落直连 server.fmode.cn —— CORS 仍可能随机失败
+GET https://ai.fmode.cn/api-platform/api/zzz-fmode-probe 404 (Not Found)
+```
+
+### 根因
+
+`ai.fmode.cn` 的静态托管(华为云 OBS)**没有配置 `/api-platform/**` 的反向代理**。
+
+### 实测证据(2026-11-18)
+
+| 请求 | Server 头 | 判断 |
+|---|---|---|
+| `https://ai.fmode.cn/api-platform/api/probe-xyz` | `openresty` + `X-CCDN-*` | ❌ **落到 OBS,没转发** |
+| `https://server.fmode.cn/api/probe-xyz` | `nginx` + `x-powered-by: Express` | ✅ 平台真实响应 |
+
+如果转发正常,前者应该返回 `x-powered-by: Express`。
+
+### 影响
+
+| 方面 | 影响 |
+|---|---|
+| **功能** | ⚠️ **不中断**。`platform-proxy.service.ts` 有回落机制:探测失败 → 自动直连 `server.fmode.cn` |
+| **控制台** | 每次打开多一个 404,干扰排查 |
+| **CORS** | 回落直连时,仍可能撞上平台多值 CORS 问题(约 33% 概率失败,见 X4) |
+
+> 注:**App 内不受影响**。`platform-proxy.service.ts` 对 Capacitor 环境直接跳过探测
+> (`isNativeApp()` 分支),因为 WebView 的 `https://localhost` 根本没有那个服务器。
+
+### 修复方案
+
+在 `ai.fmode.cn` 的源站(OBS 前面的 nginx / CDN 回源层)加转发规则:
+
+```nginx
+location /api-platform/ {
+    proxy_pass https://server.fmode.cn/api/;
+    proxy_set_header Host server.fmode.cn;
+    proxy_ssl_server_name on;
+    # CORS 由平台返回,这里不要重复加头(避免多值 ACAO)
+}
+```
+
+⚠️ **不要在这里再加 `Access-Control-Allow-Origin`** —— 同源代理后不需要 CORS,
+重复添加会造成多值头,反而被浏览器拒绝(这正是 X4 问题的成因)。
+
+### 文档缺口
+
+`src/app/core/api/platform-proxy.service.ts:26` 引用了
+`docs/05-operations/平台代理部署.md`,但**该文件不存在**。
+`docs/05-operations/部署发布手册.md` 也完全没提这条转发要求。
+
+建议:把上面的 nginx 配置补进 `部署发布手册.md`。
+
+---
+
+## 三、本轮结论
+
+| 问题 | 状态 | 谁来修 |
+|---|---|---|
+| pdfjs worker 版本 | ✅ **已修复构建流程** | App 端(已完成),需重新部署 |
+| `/api-platform/` 未转发 | ⚠️ 待配置 | 平台/运维(nginx 规则) |
+| s3 CORS | ✅ 已根治 | 平台(CDN 边缘注入,已生效) |
+
+### 仍未解决(需外部配合)
+
+- **X4 平台多值 CORS**:`/api/apig/message` 随机返回多条 ACAO,约 33% 失败
+- **X3 后台推送**:缺服务端触发链路

+ 224 - 0
docs/00-tracking/2026-11-18-跨域问题分层诊断报告.md

@@ -0,0 +1,224 @@
+# s3 / CDN CORS 问题:分层诊断报告
+
+> 2026-11-18 实测。**结论:s3 源站配置正确,问题 100% 在 CDN 缓存层。**
+
+---
+
+## 一、结论先行
+
+| 层 | 状态 | 说明 |
+|---|---|---|
+| **s3 源站 CORS 配置** | ✅ **正确** | 每次回源都返回 `Access-Control-Allow-Origin: *` |
+| **CDN 缓存策略** | ❌ **问题所在** | 缓存了缺 CORS 头的响应,**30 天**不更新 |
+| **CDN 的 `Vary` 头** | ❌ **缺失** | 带/不带 `Origin` 的请求共用同一份缓存 |
+
+**不需要改 s3,只需改 CDN。**
+
+---
+
+## 二、实测证据
+
+测试对象:`https://s3.fmode.cn/deliverables/agent-node-lj-test/202611/fK9B1XwlCZ/0-mwkkf1pdbl-a.xlsx`
+
+### 证据 1:走缓存的请求(无 CORS 头)
+
+```bash
+curl -I -H "Origin: https://ai.fmode.cn" "$U"
+```
+
+```
+HTTP/1.1 200 OK
+via: ...TCP_HIT...          ← 命中 CDN 缓存
+Age: 500
+X-CCDN-CacheTTL: 2592000    ← 缓存 30 天
+(无任何 Access-Control-* 头)
+```
+
+### 证据 2:强制回源的请求(有 CORS 头)
+
+```bash
+curl -I -H "Origin: https://ai.fmode.cn" "$U?nocache=$RANDOM"
+```
+
+```
+HTTP/1.1 200 OK
+via: ...TCP_MISS...         ← 回源了
+Age: 1
+Access-Control-Allow-Origin: *            ← 源站有!
+Access-Control-Allow-Methods: GET, PUT, POST, HEAD
+Access-Control-Max-Age: 3600
+X-CCDN-Origin-Time: 138
+```
+
+### 证据 3:`Vary` 头缺失导致缓存串用
+
+```bash
+# 第 1 次:无 Origin 请求,回源并缓存
+curl -I "$U?nocache=$RANDOM"                    → TCP_MISS,Age: 1
+
+# 第 2 次:带 Origin 请求同一 URL
+curl -I -H "Origin: https://ai.fmode.cn" "$U"   → TCP_HIT,Age: 519  ← 命中了老的缓存!
+```
+
+**说明 CDN 没有按 `Origin` 分开缓存。**
+
+### 证据 4:源站完全不返回 `Vary`
+
+```bash
+curl -I -H "Origin: https://ai.fmode.cn" "$U?fresh=$RANDOM$RANDOM"
+```
+返回了完整的 CORS 头,但**没有 `Vary: Origin`**。
+
+---
+
+## 三、根因链条
+
+```
+① 历史上某次回源时,源站没返回 CORS 头(或 CDN 缓存时丢掉了)
+        ↓
+② CDN 把这份「无 CORS」响应缓存了 30 天(X-CCDN-CacheTTL: 2592000)
+        ↓
+③ 响应又没有 Vary: Origin,CDN 不区分带/不带 Origin 的请求
+        ↓
+④ 之后所有请求(包括浏览器的跨域 fetch)都拿到这份无 CORS 的缓存
+        ↓
+⑤ 浏览器判定违反 CORS → 拦截 → App/H5 预览失败
+```
+
+---
+
+## 四、修复方案(按优先级)
+
+### 🔴 P0:立即刷新 CDN 缓存(解决存量文件)
+
+在华为云 CDN 控制台执行**目录刷新**:
+
+```
+URL: https://s3.fmode.cn/deliverables/
+类型: 目录刷新(或「刷新所有」)
+```
+
+> 注意:**只刷新 URL 不够**,需要目录刷新覆盖 `deliverables/` 下所有历史产物。
+
+### 🔴 P0:给 CDN 加 `Vary: Origin`(根治)
+
+**华为云 CDN 控制台 → 域名管理 → 高级配置 → HTTP 响应头配置**
+
+添加:
+```
+Vary: Origin
+```
+
+**为什么必须加**:否则 CDN 仍会把「无 Origin 请求」的响应喂给「带 Origin 请求」,
+下次再有文件回源时照样复现。
+
+### 🟡 P1:缩短 `deliverables/` 的缓存时间
+
+当前 `X-CCDN-CacheTTL: 2592000`(30 天)对**产物文件**太长了。
+
+建议在 CDN 缓存规则里给 `/deliverables/` 单独设:
+```
+Cache-Control: no-cache
+或 max-age=3600(1 小时)
+```
+
+理由:产物文件一旦上传就不变,但**CORS 头可能变**,30 天缓存会让问题持续很久。
+
+### 🟢 P2(可选):源站补 `Vary`
+
+如果华为云 OBS 的 CORS 配置能设 `Vary`,也加上更保险。
+
+---
+
+## 五、这不是 App 端问题
+
+| 疑问 | 回答 |
+|---|---|
+| 「是不是 WebView 导致的?」 | ❌ 不是。线上 Web(`https://ai.fmode.cn`)同样报错,两个 origin 都是跨域 |
+| 「是不是 Capacitor 的问题?」 | ❌ 不是。CORS 是服务器响应头决定的,与客户端框架无关 |
+| 「App 端能修吗?」 | ⚠️ 只能绕(原生下载代理),且只解决 App、H5 仍坏。**根治必须改 CDN** |
+
+---
+
+## 六、验证标准
+
+修复后跑这三条命令,全部有输出即成功:
+
+```bash
+U="https://s3.fmode.cn/deliverables/agent-node-lj-test/202611/1LCA7ahKVQ/1-mwhdlx2fvn-deliverable-20261115-131048.pdf"
+
+# 1. 老文件(走缓存)应有 CORS 头
+curl -sS -I -H "Origin: https://ai.fmode.cn" "$U" | grep -i access-control-allow-origin
+
+# 2. 新文件应有 CORS 头
+curl -sS -I -H "Origin: https://ai.fmode.cn" "https://s3.fmode.cn/deliverables/agent-node-lj-test/202611/fK9B1XwlCZ/0-mwkkf1pdbl-a.xlsx" | grep -i access-control-allow-origin
+
+# 3. 回源时不得出现重复 ACAO 头(应为 1)
+curl -sS -I -H "Origin: https://ai.fmode.cn" "$U?cb=$RANDOM" | grep -ic access-control-allow-origin
+```
+
+真机上点开 PDF / Word / Excel,应能正常渲染。
+
+---
+
+## 七、最终修复(2026-11-18 已生效)
+
+### 实际采用的方案:CDN 边缘注入 CORS 头
+
+原方案的 `Vary: Origin` **在华为云 CDN 上不可行**——响应头配置是白名单,
+`Vary` 不在内,API 直接拒绝:`CDN.0001 unsupported response header : Vary`。
+
+改用**更彻底的方案**:让 CDN 在边缘 serve 时**无条件注入** CORS 头。
+
+| 优势 | 说明 |
+|---|---|
+| 无需刷缓存 | 注入发生在边缘,**历史已缓存的旧文件也会被补上头** |
+| 不受源站影响 | 源站返回什么不影响,CDN 统一覆盖 |
+| 替换而非追加 | 回源自带 CORS 头时是**替换**,不会出现重复头 |
+
+### 已写入配置(domain_id `74495359597444e0ad1be3018fab6cdb`)
+
+```
+Content-Disposition:          inline        ← 原有,保留
+Access-Control-Allow-Origin:  *             ← 新增
+Access-Control-Allow-Methods: GET, PUT, POST, HEAD
+Access-Control-Max-Age:       3600
+```
+
+### 独立复核结果(2026-11-18,本地实测)
+
+| 验证项 | 结果 |
+|---|---|
+| 之前失败的 PDF(`Age: 249380`,缓存命中) | ✅ `Access-Control-Allow-Origin: *` |
+| 之前失败的 xlsx(`Age: 56567`) | ✅ 有 CORS 头 |
+| 之前失败的 html(`Age: 249423`) | ✅ 有 CORS 头 |
+| 回源请求(`?cb=随机`)ACAO 头个数 | ✅ **1**(无重复) |
+| 换 Origin 为 `https://localhost` | ✅ 生效 |
+| 不带 Origin 的请求 | ✅ 也带头 |
+| **真机内 `fetch` PDF** | ✅ **成功,3,607 字节** |
+| **真机内 pdfjs 解析 PDF** | ✅ **1 页 / 595×842 / 125ms / v4.10.38** |
+| 真机内 fetch xlsx / html / docx | ✅ 5,102 / 2,048 / 37,341 字节 |
+
+### 缓存 TTL 未改动(维持 30 天)
+
+理由:CORS 头由 CDN 无条件注入,不会因缓存而缺失;产物 key 带随机串,
+覆盖极罕见。缩短 TTL 只增加回源量,无收益。
+
+### 回滚命令
+
+```bash
+node cdn-ops.js del-hdr 74495359597444e0ad1be3018fab6cdb \
+  Access-Control-Allow-Origin Access-Control-Allow-Methods Access-Control-Max-Age
+```
+
+### ⚠️ 遗留小问题(不影响公开文件读取)
+
+预检响应里上游仍带 `Access-Control-Allow-Credentials: true`,
+与 `ACAO: *` 是矛盾组合——只影响**带凭据**的请求。
+本项目读公开文件不带凭据,不受影响;将来若需带凭据,应改为回显具体 Origin。
+
+### 方法论沉淀
+
+- 华为云 CDN 不支持 `Vary`,响应头配置仅白名单内可选
+- 响应头配置是**整体覆盖**,不是追加(修改时要带上原有项)
+- 同类扫描:14 个域名中 s3 是唯一漏配的,现已对齐

+ 38 - 0
docs/05-operations/部署发布手册.md

@@ -200,6 +200,43 @@ obs.setBucketWebsite({
 }, (err, res) => console.log(err ?? res.CommonMsg.Status));   // 期望 200
 ```
 
+### 4.4 `/api-platform/**` 反代未配置(控制台刷 404)
+
+**症状**:浏览器控制台每次打开都出现
+```
+[PlatformProxy] /api-platform/ 未转发到平台(x-powered-by=空),回落直连 server.fmode.cn
+GET https://ai.fmode.cn/api-platform/api/zzz-fmode-probe 404 (Not Found)
+```
+
+**影响**:功能**不中断**——`platform-proxy.service.ts` 会回落直连 `server.fmode.cn`。
+但每次多一个 404 请求,且直连时可能撞上平台多值 CORS。
+
+**判断是否真的没转发**(看 404 的 Server 头):
+
+```bash
+# 没转发 → Server: openresty + X-CCDN-*(落在 OBS 上)
+curl -sS -I https://ai.fmode.cn/api-platform/api/probe-xyz | grep -iE "server|x-powered-by"
+
+# 转发正常 → Server: nginx + x-powered-by: Express(平台真实响应)
+curl -sS -I https://server.fmode.cn/api/probe-xyz | grep -iE "server|x-powered-by"
+```
+
+**修复**:在数据流列表或「动态加速」配置里为 `/api-platform/` 添加:
+```nginx
+location /api-platform/ {
+    proxy_pass https://server.fmode.cn/api/;
+    proxy_set_header Host server.fmode.cn;
+    proxy_ssl_server_name on;
+}
+```
+`server_host` 填 `server.fmode.cn`。
+
+⚠️ **不要在这里再加 `Access-Control-Allow-Origin`**。同源代理后不需要 CORS,
+重复添加会产生**多值 ACAO**,反而被浏览器整体拒绝。
+
+> 注:**App 内不受影响**。`platform-proxy.service.ts` 对 Capacitor 环境直接跳过探测
+> (`isNativeApp()` 分支),因为 WebView 的 `https://localhost` 根本没有那个服务器。
+
 ---
 
 ## 五、踩坑记录(均已修复,勿重犯)
@@ -213,6 +250,7 @@ obs.setBucketWebsite({
 | 5 | 深链探活判定 404 为失败 | OBS ErrorDocument 回落时状态码仍是 404 | 改为判断响应体是否含本次 `<title>` |
 | 6 | `npm run build` 产出未优化包 | production 配置缺 `optimization` | `angular.json` 已补 `optimization: true` |
 | 7 | 线上跑的是演示数据 | `environment.production.ts` 的 `useMockData` 误设为 `true` | 已改为 `false`;演示态改走 `environment.mock.ts` |
+| 8 | **PDF 一直转圈**,控制台报 `API version "6.4.299" does not match the Worker version "4.10.38"` | `public/pdf.worker.js` 是**构建产物但不随构建更新**:`copy-pdf-worker.mjs` 原只挂在 `postinstall`,`build` 不跑它。`deploy.mjs` 只刷 CDN 上该文件的缓存,刷的仍是本地那份旧的 | 已在 `package.json` 加 `prebuild` / `prebuild:mock` 钩子 + 补 `cap:sync`,构建前自动重建。**此坑已踩三次** |
 
 ---
 

+ 3 - 1
package.json

@@ -4,6 +4,8 @@
   "scripts": {
     "ng": "ng",
     "postinstall": "node scripts/copy-pdf-worker.mjs",
+    "prebuild": "node scripts/copy-pdf-worker.mjs",
+    "prebuild:mock": "node scripts/copy-pdf-worker.mjs",
     "start": "ng serve",
     "start:local": "ng serve --configuration local",
     "start:mock": "ng serve --configuration mock",
@@ -23,7 +25,7 @@
     "ops:clear-deliverables": "node scripts/clear-deliverable-urls.mjs",
     "verify:deliverables": "node scripts/verify-deliverable-separation.mjs",
     "verify:ticking": "node scripts/verify-elapsed-ticking.mjs",
-    "cap:sync": "ng build --configuration production && cap sync android",
+    "cap:sync": "node scripts/copy-pdf-worker.mjs && ng build --configuration production && npx cap sync android",
     "cap:open": "cap open android",
     "cap:apk": "cd android && ./gradlew assembleDebug"
   },