SearchGal如何稳定搜索25个站点:HTTP超时、HTML解析与容错技巧
SearchGal如何稳定搜索25个站点:HTTP超时、HTML解析与容错技巧
SearchGal 是一款 Galgame 聚合搜索工具:输入一次游戏名,就能同时检索 25 个资源站点并流式返回结果。并行搜索天然放大故障——任何一站变慢、改版或被人机验证拦截,都可能拖垮整个请求。本文拆解 SearchGal 在 HTTP 超时、HTML 解析、容错降级 三个层面的实战技巧,帮你理解聚合搜索服务如何做到"单站故障不影响全局"。
📌 先看效果:一次搜索,全站覆盖
在 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,几个关键点:
- 超时覆盖整个响应体:
AbortController的 15 秒计时从发起请求开始,直到响应体完整读完才停止,而不是"收到响应头就取消计时"。这避免了慢速站点用超长 body 无限占住连接。 - 整体缓冲响应:fetch 拿到流式 body 后先
arrayBuffer()读满,再重建Response对象,后续解析(json()/text())可反复读取,且重定向后的url被显式保留,保证站点链接拼出来是正确的。 - 统一的 UA 与错误归一化:所有请求默认携带带站点标识的 User-Agent;超时时抛出"资源平台 SearchAPI 请求超时",带错误码的网络问题则归一化为
网络错误 <code>,方便前端统一展示。 - 尊重外部取消:调用方的
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...;、&等 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 / 正则 / 通用解析器 + 结果清洗)、优雅降级(质询识别、预校验、站点停用清单)。如果你也想做聚合搜索或多源数据抓取,这套"把失败当成返回值"的思路可以直接复用。
