CGYScrapeHub 是一套自架的 web intelligence backend，用來把公開網頁、搜尋結果、社群內容與商品頁整理成 LLM 可直接使用的 Markdown / JSON。專案核心不是「把網頁抓下來」而已，而是處理真實網站常見的麻煩：反爬蟲、SPA、搜尋頁空結果、內容雜訊、長文檢索、慢請求與部分站點失敗。
為什麼做
原本依賴外部爬取服務時，遇到三個問題：
- 成本與速率受制於第三方服務
- 反爬蟲、登入牆、搜尋頁空結果時很難細修
- 給 LLM 使用時，整頁內容太長，仍需要段落級檢索與清理
CGYScrapeHub 的目標是把這些能力收回到自己可部署、可觀測、可調整的服務裡。
系統架構
Client
-> Caddy
TLS termination
Bearer token gate
-> FastAPI
crawl / search / site-search / social-search / price-compare
async jobs
MCP /mcp
-> Core services
Strategy Router
Browser Pool
Hybrid Search
Domain Strategies
-> Dependencies
SearxNG
Valkey
Rust tlsclient sidecar技術亮點
1. 多引擎反爬蟲路由
不同網站失敗的方式不一樣。有些需要 Chromium 渲染，有些會卡在 TLS fingerprint，有些搜尋頁本身就會回空殼。CGYScrapeHub 用 strategy router 把引擎選擇、domain 規則、fallback chain 拆開，讓每個平台可以逐步調整，而不是把所有邏輯塞在單一 crawler 裡。
2. 段落級 Hybrid Search
長頁面不適合整篇丟給 LLM。CGYScrapeHub 會先清掉 boilerplate，再切成段落，用 BM25 做第一層過濾，接著跑 embedding 與 rerank。LLM provider 沒設定或失敗時，服務會降級成 BM25-only，不會直接回 5xx。
3. 社群搜尋與站內搜尋 fallback
Reddit、X/Twitter、PTT、Dcard、YouTube 等平台的搜尋路徑差異很大。CGYScrapeHub 將「平台 scope」、「canonical domain alias」、「SearxNG site: fallback」分開處理，避免使用者只拿到空結果。
4. 比價的 fail-soft fan-out
price-compare 會同時查多個電商站，抓商品、解析價格、做相似商品分組。單一站點 timeout 或解析失敗時，只會標記該站狀態，不影響其他站點結果。
5. 可觀測與可恢復
系統有 trace_id、readiness probe、Prometheus metrics、async job store、Valkey cache 與 stampede guard。重點是讓慢請求、快取命中、搜尋後端失敗可以被定位，而不是只看到「爬不到」。
Tech Stack
| 類別 | 技術 |
|---|---|
| API | FastAPI, Pydantic v2, Uvicorn |
| Browser / Crawling | Playwright/Patchright, DrissionPage, Crawlee |
| Search | SearxNG, BM25, rerank pipeline |
| Cache / Jobs | Valkey |
| Anti-bot | Rust tlsclient sidecar, JA3/TLS impersonation |
| Infra | Docker Compose, Caddy, GHCR |
| Observability | Trace ID, readiness checks, Prometheus metrics |
| Tests | Pytest, pytest-asyncio, fakeredis, pytest-httpx |
結果
- 從單純 crawler 擴展成完整的搜尋、爬取、社群搜尋、比價與 deep crawl API
- Hybrid search embedding batch size 調整到 64，並將 embedding cache TTL 獨立成 3600 秒，降低長文冷路徑成本
- 對 Reddit / X / Amazon 等高失敗率平台加入透明 fallback，空結果時仍能回可用搜尋結果
- QNAP 自架部署使用多映像拆分：API、SearxNG、Caddy、tlsclient，各自可獨立 rebuild 與替換
我會怎麼介紹這個專案
這是一個偏後端系統工程的作品。它展示的不是單一 API endpoint，而是把 crawler、搜尋後端、cache、anti-bot routing、非同步任務與 LLM retrieval 組成一個可以長期調整的服務。