debug

2026-04-16 16:14:20 +08:00
parent 327c5f506c
commit af0b09daee
4 changed files with 321 additions and 8 deletions
--- a/docs/2026-04-16-admin2-spider-workbench-production-fix.md
+++ b/docs/2026-04-16-admin2-spider-workbench-production-fix.md
@@ -0,0 +1,286 @@
+# 2026-04-16 Admin2 蜘蛛预览正式服排障记录
+
+## 背景
+
+本次排障发生在正式服管理端 `https://admin2.jpjdxs.info/`。
+
+用户反馈的问题分为三个阶段：
+
+1. 管理端请求蜘蛛工作台接口时报 CORS 错误。
+2. 前端在处理临时产物和缓存后，首页出现运行时异常，页面加载不稳定。
+3. 页面恢复后，点击“蜘蛛预览”接口返回 `500`。
+
+本次工作定位为正式服辅助分析、止血、优化与修复，开发主线仍由主 Codex 继续维护。
+
+## 最终结论
+
+这次问题不是单点故障，而是三层问题叠加：
+
+1. 前端生产环境接口地址指向了跨域域名，导致浏览器先出现 CORS 报错。
+2. 排障过程中过的脏 `dist` 与浏览器 `Service Worker` 缓存叠加，导致首页运行时异常。
+3. 蜘蛛工作台接口在 24 小时窗口下同步聚合过多抓取摘要文件，触发 PHP 128MB 内存上限，最终返回 `500`。
+
+## 线上现象
+
+### 1. CORS 阶段
+
+浏览器最初报错：
+
+- 管理端来源：`https://admin2.jpjdxs.info`
+- 被请求接口：`https://adapi.ra12.shop/site/domain/spider-crawl/workbench/summary?...`
+- 浏览器错误：`No 'Access-Control-Allow-Origin' header is present on the requested resource`
+
+### 2. 前端运行时阶段
+
+首页曾出现运行时异常：
+
+- `TypeError: Cannot read properties of null (reading 'nextSibling')`
+
+这个阶段和手工改动过的前端产物以及旧缓存有关，不是蜘蛛工作台业务逻辑本身的问题。
+
+### 3. 蜘蛛预览 500 阶段
+
+页面恢复后，点击蜘蛛预览再次报错：
+
+- 请求地址：
+  - `/api/site/domain/spider-crawl/workbench/summary?run_limit=10&anomaly_limit=80&window_hours=24&bot_scope=all&selected_bots=baiduspider,sogou`
+- 浏览器错误：
+  - `AxiosError: Request failed with status code 500`
+
+## 根因定位
+
+### 根因一：前端生产环境接口配置为跨域域名
+
+正式服前端原先在生产环境里直接请求外部域名，浏览器因此走了跨域模式。
+
+关联文件：
+
+- `VideoAdminV2/.env.production`
+
+修复思路：
+
+- 将前端生产环境接口基址改为同源 `/api`
+- 由管理端 nginx 反向代理到后端服务
+
+### 根因二：旧 `Service Worker` 与临时修改产物污染
+
+在排障期间，浏览器端同时受到以下因素影响：
+
+- 旧 `Service Worker` 缓存
+- 旧静态资源哈希
+- 临时手工调整过的 `dist`
+
+这会导致首页有机会出现和真实源码不一致的运行时行为。
+
+修复思路：
+
+- 用 `nvm` 环境重新构建干净前端产物
+- 关闭 PWA，避免继续注册新的 `Service Worker`
+- 首页增加旧缓存清理逻辑
+- 首页增加 `localStorage` 解析容错
+
+### 根因三：蜘蛛工作台同步聚合过多摘要文件导致 PHP 内存耗尽
+
+这是点击“蜘蛛预览”时 `500` 的真实根因。
+
+日志证据来自：
+
+- `/www/wwwlogs/source.video2.com.error.log`
+
+关键错误：
+
+- `Allowed memory size of 134217728 bytes exhausted`
+- 涉及文件：
+  - `/www/wwwroot/VideoSource2/code/app/common/helper/DomainSpiderCrawlWorkbenchHelper.php`
+  - `/www/wwwroot/VideoSource2/code/app/common/helper/DomainSpiderCrawlLogHelper.php`
+
+当时请求示例：
+
+- `GET /site/domain/spider-crawl/workbench/summary?run_limit=10&anomaly_limit=80&window_hours=24&bot_scope=all&selected_bots=baiduspider,sogou`
+
+触发原因：
+
+- `window_hours=24` 时会扫描大量 `crawl-logs.summary.json`
+- 旧实现会把多份 summary 读入内存后进行聚合
+- 正式服数据量明显大于开发环境
+
+排障时观察到的数据规模：
+
+- `storage/domain-spider-crawl/runs` 目录约 `47M`
+- `crawl-logs.summary.json` 数量约 `154` 份
+- 单个摘要文件最大接近 `958507` bytes
+
+## 已执行的修复
+
+### 一、管理端同源代理与 CORS 调整
+
+#### 1. 管理端 nginx 增加 `/api/` 反向代理
+
+文件：
+
+- `/www/server/panel/vhost/nginx/admin2.jpjdxs.info.conf`
+
+处理效果：
+
+- 管理端改为访问同源 `/api/...`
+- 管理端不再直接跨域请求 `adapi.ra12.shop`
+
+#### 2. 后端 CORS 头调整
+
+文件：
+
+- `/www/wwwroot/VideoSource2/code/app/admin/middleware/AdminCors.php`
+
+处理效果：
+
+- 补齐允许方法
+- 补齐允许头
+- 增加 `Vary: Origin`
+
+## 二、前端正式服止血
+
+### 1. 前端生产环境改为同源接口
+
+文件：
+
+- `/www/wwwroot/VideoAdminV2/.env.production`
+
+关键配置：
+
+- `VITE_API_URL=/api`
+- `VITE_PWA=false`
+
+### 2. 首页增加容错和旧缓存清理
+
+文件：
+
+- `/www/wwwroot/VideoAdminV2/index.html`
+
+处理内容：
+
+- `IOMS-global` 的 `localStorage` 读取加 `try/catch`
+- 启动时注销旧 `serviceWorker`
+- 清理旧缓存
+
+### 3. 清理不再需要的启动期缓存逻辑
+
+文件：
+
+- `/www/wwwroot/VideoAdminV2/src/main.ts`
+
+处理内容：
+
+- 去掉启动时全量清理缓存的临时逻辑，避免继续引入不确定性
+
+### 4. 使用 `nvm` 环境重新构建前端
+
+确认到正式服 `nvm` 环境为：
+
+- Node: `v20.19.6`
+- npm: `10.8.2`
+
+实际使用命令：
+
+```bash
+export HOME=/home/www
+export NVM_DIR="$HOME/.nvm"
+. "$NVM_DIR/nvm.sh"
+cd /www/wwwroot/VideoAdminV2
+nvm use 20
+npm run build:pro
+```
+
+构建后线上主包为：
+
+- `assets/js/index-23f333c2.js`
+
+## 三、蜘蛛工作台 500 修复
+
+核心修复文件：
+
+- `/www/wwwroot/VideoSource2/code/app/common/helper/DomainSpiderCrawlWorkbenchHelper.php`
+
+处理内容：
+
+1. 增加聚合 run 上限：
+   - `MAX_AGGREGATE_RUNS = 12`
+2. `collectRunEntries()` 不再保存整份 summary 内容，只保存：
+   - `summary_path`
+   - `normalized`
+   - `generated_at_ts`
+3. `aggregateRunSummaries()` 改为按需读取文件，而不是提前把所有 summary 常驻内存
+4. `buildSummary()` 在窗口聚合前先裁剪最近 run
+5. `buildWindowComparison()` 也在聚合前先裁剪最近 run
+
+这次修复的目标是正式服止血，不是最终态架构优化。
+
+## 验证结果
+
+### 1. 前端接口基址
+
+已确认前端主包中接口基址为：
+
+- `baseURL:"/api"`
+
+### 2. CORS 头
+
+已确认响应头包含：
+
+- `Access-Control-Allow-Origin: https://admin2.jpjdxs.info`
+- `Vary: Origin`
+
+### 3. helper 在 128MB 内存下可跑通
+
+排障时在本机使用命令验证：
+
+```bash
+php -d memory_limit=128M -r '... DomainSpiderCrawlWorkbenchHelper::buildSummary(...) ...'
+```
+
+修复后返回正常，说明核心内存问题已被压住。
+
+### 4. PHP-FPM 已重载
+
+执行：
+
+```bash
+service php-fpm-83 reload
+```
+
+用于确保线上 PHP 进程加载到修复后的 helper 代码。
+
+### 5. 用户回归验证
+
+用户最终反馈：
+
+- “好了终于跑通了”
+
+说明这次正式服问题已经完成闭环。
+
+## 对主 Codex 的交接建议
+
+这次修复属于正式服止血方案，主 Codex 后续建议继续做结构化优化：
+
+1. 不要在在线接口里同步扫描过多 run 文件。
+2. 将蜘蛛工作台改造成预聚合模型，而不是请求时全量聚合。
+3. 将 `1h / 6h / 24h / 72h` 窗口统计结果提前固化为摘要文件或缓存。
+4. 为大窗口查询增加更清晰的降级策略与上限说明。
+5. 如果后续还要放大统计维度，应考虑异步任务或离线聚合，不要继续依赖同步 `json_decode(file_get_contents(...))` 全量加载。
+
+## 本次涉及文件
+
+前端相关：
+
+- `/www/wwwroot/VideoAdminV2/.env.production`
+- `/www/wwwroot/VideoAdminV2/index.html`
+- `/www/wwwroot/VideoAdminV2/src/main.ts`
+- `/www/server/panel/vhost/nginx/admin2.jpjdxs.info.conf`
+
+后端相关：
+
+- `/www/wwwroot/VideoSource2/code/app/admin/middleware/AdminCors.php`
+- `/www/wwwroot/VideoSource2/code/app/common/helper/DomainSpiderCrawlWorkbenchHelper.php`
+
+文档落点：
+
+- `/www/wwwroot/VideoSource2/docs/2026-04-16-admin2-spider-workbench-production-fix.md`