SearchGal如何稳定搜索25个站点:HTTP超时、HTML解析与容错技巧

原创2026-10-26 19:09:151,373 阅读

SearchGal如何稳定搜索25个站点:HTTP超时、HTML解析与容错技巧

SearchGal 是一款 Galgame 聚合搜索工具:输入一次游戏名,就能同时检索 25 个资源站点并流式返回结果。并行搜索天然放大故障——任何一站变慢、改版或被人机验证拦截,都可能拖垮整个请求。本文拆解 SearchGal 在 HTTP 超时、HTML 解析、容错降级 三个层面的实战技巧,帮你理解聚合搜索服务如何做到"单站故障不影响全局"。

📌 先看效果:一次搜索,全站覆盖

在 PC 端界面中输入关键词后,各站点结果会以流的方式陆续出现,界面左上角还会实时显示当前耗时:

SearchGal Galgame聚合搜索PC端搜索界面,展示游戏关键词搜索结果与耗时统计

所有站点适配器集中在 src/platforms/gal/index.ts 注册,当前启用了 25 个游戏站点;补丁类站点见 src/platforms/patch/index.ts。

⚡ 并行架构:把 25 个请求变成"互不拖累"的任务

核心逻辑在 src/core.ts:每个站点都实现统一的 Platform 接口(定义见 src/types.ts),search 方法接收关键词、返回 { items, count, error }。

请求到达后(入口 src/index.ts),所有平台通过 Promise.all 并行执行,谁先完成谁先推送:

  • 结果以 SSE(Server-Sent Events) 流式输出,每完成一站就发送一条带 completed/total 进度信息的事件;
  • 出错的平台只推送红色错误提示,空结果平台只推送进度,避免前端白等;
  • 流写入交给 ctx.waitUntil 处理,保证 Worker 在流结束前不会提前回收。

这种"适配器 + 流式推送"的模式,是 25 个异构站点能共用一条请求链路的前提。

⏱️ HTTP 超时技巧:15 秒全链路计时

超时策略集中在 src/utils/httpClient.ts,几个关键点:

  1. 超时覆盖整个响应体:AbortController 的 15 秒计时从发起请求开始,直到响应体完整读完才停止,而不是"收到响应头就取消计时"。这避免了慢速站点用超长 body 无限占住连接。
  2. 整体缓冲响应:fetch 拿到流式 body 后先 arrayBuffer() 读满,再重建 Response 对象,后续解析(json() / text())可反复读取,且重定向后的 url 被显式保留,保证站点链接拼出来是正确的。
  3. 统一的 UA 与错误归一化:所有请求默认携带带站点标识的 User-Agent;超时时抛出"资源平台 SearchAPI 请求超时",带错误码的网络问题则归一化为 网络错误 <code>,方便前端统一展示。
  4. 尊重外部取消:调用方的 AbortSignal 与内部超时共用一个 controller,用户取消搜索时所有在途请求同步中断。

🧩 HTML 解析:三种策略对应三类站点

25 个站点没有统一的搜索接口,SearchGal 按站点类型分了三条解析路线:

策略 适用站点 典型实现
JSON API 直接解析 有开放接口的站点 GalTuShuGuan.ts、MaoMaoWangPan.ts
正则提取 HTML 标签 结构固定的列表页 ACGYingYingGuai.ts(命名分组 (?<URL>)(?<NAME>) 兼容单/双引号与属性顺序)
WordPress 通用解析器 大量基于 WordPress 的站点 src/utils/wordpress.ts

通用解析器 src/utils/search.ts 做得很克制,值得借鉴:

  • 只解析标题链接:parsePostHeadings 只匹配 item-heading、entry-title 等文章标题容器内的 <a>,天然跳过侧栏、封面与广告位;
  • 同源校验:解析出的 URL 与页面 origin 不一致直接丢弃,防止跨站链接混入结果;
  • 实体解码 + 去重:decodeHtmlText 处理 &#x...;、&amp; 等 HTML 实体,uniqueItems 按 URL 去重并过滤非 http(s) 链接;
  • 无结果时的"假推荐"过滤:如 FuFuACG.ts 无匹配时会返回随机推荐,代码里用关键词二次过滤,不把推荐当搜索结果。

还有一种"本地索引"思路:VNS.ts 直接拉取整站的 data.json 索引并缓存 10 分钟,搜索变成纯内存过滤,又快又稳定。

🛡️ 容错降级:任何单站故障都不扩散

这是全文最核心的部分——错误被设计成"预期内"的返回值,而不是异常:

  • 适配器内兜底:每个平台的 search 都在 try/catch 内执行,失败时返回 { count: -1, error } 而不是抛异常,Promise.all 因此永远不会 reject;
  • 人机验证识别:src/utils/search.ts 的 assertSearchPage 检测 "Just a moment"、challenge-form 等 Cloudflare 质询特征,主动抛出"要求人机验证"的清晰错误,而不是返回一堆垃圾结果;
  • 预校验减少无谓请求:TouchGal.ts 先校验关键词长度(官方 API 要求 3–100 字符)再发请求;未配置 API token 时静默返回空结果,避免每次搜索都刷红色报错;
  • 站点下线机制:站点宕机、被 WAF 屏蔽或改 SPA 后,在 index.ts 中注释停用并注明原因(如"DNS ENOTFOUND""Cloudflare 人机质询"),源文件保留,随时可恢复——这也是"25 个"这个数字会动态变化的原因。

🚀 本地跑起来

想自己验证这套机制,可以克隆仓库本地体验:

git clone https://gitcode.com/gh_mirrors/sea/SearchGal
cd SearchGal
pnpm install

部署与运行配置参考 Dockerfile、compose.yml 与 wrangler.toml。

✅ 小结

SearchGal 的稳定性来自四条原则:并行隔离(单站 try/catch 兜底)、全链路超时(15 秒读到 body 读完)、分层解析(API / 正则 / 通用解析器 + 结果清洗)、优雅降级(质询识别、预校验、站点停用清单)。如果你也想做聚合搜索或多源数据抓取,这套"把失败当成返回值"的思路可以直接复用。

登录后查看全文
SearchGal