Stealth-Scraper

# Stealth-Scraper **适用于 AI 代理的可靠的网页数据层。** 大多数 AI 代理在生产环境中都失败了，因为现代网页不愿意被抓取。Cloudflare、DataDome、PerimeterX、Akamai、Kasada 和 Imperva 现在控制了 **约 40% 的有价值网站**，而您的代理今天导入的开源抓取器都无法绕过它们。 Stealth-Scraper 是一个托管的 API + 可视化选择器，它处理反机器人战斗，因此您的代理不必这样做。一个端点，JSON 输出，模式由它为您处理。 - **托管**: [**stealthscraper.dev**](https://stealthscraper.dev) — 粘贴 URL，指向您要的字段，获取可重新运行的配方 + API 密钥。免费层，无需信用卡。 - **API**: `api.stealthscraper.dev` · MCP 服务器 · Python SDK · TypeScript SDK - **开源**: [`stealth-browser`](https://github.com/Rusheesonu/stealth-browser) — 引擎层，MIT 许可，可单独使用。 - **状态**: [status.stealthscraper.dev](https://status.stealthscraper.dev) --- ## 您实际上得到的是 ```python # pip install stealth-scraper from stealth_scraper import StealthClient client = StealthClient(api_key="ssk_...") # 1. 快照任何 URL — 自动处理反机器人战斗。 snap = client.snapshot("https://www.crunchbase.com/") # 2. 或用自然语言描述您要的内容 — 我们生成模式。 data = client.assist_extract( url="https://news.ycombinator.com/", description="获取前 20 个故事：标题，积分，评论，链接", ) # → data.template = [...], data.fields = {...} # 3. 保存配方（通过仪表板或 `POST /templates`），然后重新运行它。 result = client.run_template(template_id="t_hn_frontpage", url="https://news.ycombinator.com/") ``` TypeScript/JS: ```bash npm install stealth-scraper ``` ```ts import { StealthClient } from 'stealth-scraper'; const client = new StealthClient({ apiKey: 'ssk_...' }); const snap = await client.snapshot('https://news.ycombinator.com/'); ``` 对于需要实时工具使用的 AI 代理： ```bash # MCP 服务器（Anthropic Model Context Protocol） npx @stealth-scraper/mcp # → 添加 `scrape_url`, `extract_structured`, `list_templates`, `run_template` # 工具到 Claude Desktop / Cursor / Cline / 等。 # → 添加 `scrape_url`, `extract_structured`, `list_templates`, `run_template` # 工具到 Claude Desktop / Cursor / Cline / 等。 ``` --- ## 引擎实际工作原理 大多数“隐身抓取器”都附带一个浏览器自动化库，并称之为隐身。它们输给具有 IP 声誉、行为生物识别或 Chromium 特定运行时传感器的供应商。我们的论文是：**没有单一引擎可以在所有地方获胜**，所以我们按目标路由。 ``` ┌─────────────────────────────────────────┐ │ 引擎路由器（能力 + 历史） │ └─────────────────────────────────────────┘ │ │ │ ┌────────▼─┐ ┌───────▼──┐ ┌──────▼───────┐ │ nodriver │ │curl_cffi │ │ camoufox │ │ （Chromium│ │ （TLS-imp-│ │ （Firefox， │ │ via CDP）│ │ ersonate）│ │ patched） │ └──────────┘ └──────────┘ └──────────────┘ JS+screenshot no-JS, beats creepjs, CF Turnstile 50-100x Kasada, faster on PerimeterX static HTML ``` 路由器按以下方式选择： 1. **能力过滤器** — 删除无法满足要求的引擎（例如需要 JS → 删除 `curl_cffi`） 2. **供应商亲和力** — 按反机器人供应商的已知良好引擎顺序 3. **每主机学习** — 在此主机上成功过的引擎会浮动到顶部（持久化磁盘） 4. **成本升序** — 在绑定条件下，选择最便宜的（`curl_cffi` 免费，`camoufox` 约 `nodriver` 的 2 倍） 5. **失败后升级** — 如果引擎 A 返回 `EngineFailedError`，则尝试引擎 B，然后尝试引擎 C。每个请求最多升级 3 次。 每个引擎都有一个记录的诚实能力集（`engines/base.py`）：TLS 伪装、JS 执行、CDP 原生、行为模拟、Firefox 引擎、轻量级等。路由器将它们视为可互换的，除了它们所宣传的内容。 --- ## 基准测试（诚实） 基准测试套件在 `bench/` 中运行三个基准测试，针对真实的生产 URL。数字来自 `bench/results/*.json` — 绝不捏造。 | 基准测试 | 结果 | 目标 | 备注 | |---|---|---|---| | **反机器人绕过** （18 个 URL，7 个供应商） | **83.3%** | ≥95% | 最后 3 次失败是 IP 声誉绑定（g2.com，hyatt.com，crunchbase/discover）— 通过住宅代理计划解锁。 | | **指纹识别** （9 个检测站点） | **0 次失败** / 5 次通过 / 4 次未知 | 在 creepjs + sannysoft + browserleaks + fingerprint.com 上清洁 | 引擎工作已完成； 4 个“未知”是指 LLM 判决文本解析差距，不是引擎失败。 | | **吞吐量** （30 个 URL，混合难度） | **90% at 4,744 pages/\$** | ≥95% / ≥2,000 pages/\$ | pages/\$ 已经 **2.4× 目标** 。 | 供应商特定（反机器人，全生产栈）： | 供应商 | 通过率 | 获胜引擎 | |---|---|---| | Cloudflare（基本） | 2/3 | `nodriver` | | Cloudflare Turnstile | 2/2 | `camoufox` （Firefox 躲避 Chromium 运行时传感器） | | DataDome | 3/3 | `curl_cffi` + `camoufox` （TLS 指纹重） | | Akamai Bot Manager | 3/3 | `curl_cffi` 首先，浏览器回退 | | Kasada | 2/2 | `camoufox` （规范 Kasada 绕过） | | PerimeterX | 1/2 | `camoufox` 用于 glassdoor； zillow 需要 CAPTCHA 求解器 | | Imperva | 1/2 | hyatt 需要住宅代理 | 基准测试平台在记录的 [付费基础设施上限](bench/setup_needed.md) 处达到极限：住宅代理（~$5/次）解锁另外 3 个 URL 至 94.4%，一个 PX CAPTCHA 求解器（$1-2/zillow 抓取）解锁其余部分至 100%。 自己运行： ```bash python -m bench.antibot # 18 个 URL，~4min python -m bench.fingerprint # 9 个检测站点，LLM 判决 python -m bench.throughput # 30 个 URL，pages/$ + 引擎混合 ``` --- ## 包含的内容 | 层 | 内容 | |---|---| | **可视化选择器** | 粘贴 URL → 直播截图 → 点击您要的字段。智能选择器（拖动选择以分割跨度，通过视觉列自动兄弟节点检测，父节点选择退出）。 | | **AI 助手** | 用英语描述您要的内容。Groq Llama-3.3-70b 从渲染的 DOM 中选择选择器。如果不确定，则回退到可视化选择器。 | | **多引擎路由器** | `nodriver` + `curl_cffi` + `camoufox`。按供应商自动路由。失败时升级。按主机学习。 | | **输出格式** | JSON，CSV，Markdown，PDF。行对齐提取（缺少字段 → `null`，列表保持相同长度）。 | | **分页** | 自动跟随下一页链接。可配置的最大页面数。 | | **浏览器操作** | 预快照点击/滚动/填充（关闭横幅，登录，触发延迟内容）。 | | **定时抓取** | 类似 cron 的调度每个模板。完成时 Webhook 交付。 | | **批处理模式** | 新的一行 URL 列表 → JSON/CSV 包。 | | **配方市场** | 发布 + 克隆公共模板。 | | **API + SDK** | REST + Python (`pip install stealth-scraper`) + TypeScript (`npm install stealth-scraper`) + MCP 服务器 (`npx @stealth-scraper/mcp`)。所有发布的 v0.1.0。 | | **使用仪表板** | 每月抓取次数 vs 计划限制，成功率，平均延迟。 | --- ## 技术栈 | 层 | 技术 | |---|---| | 前端 | Next.js 16 · React 19 · Tailwind v4 · framer-motion · Apple-minimal design | | 后端 | FastAPI · Python 3.12 · `nodriver` （Chromium via CDP） · `camoufox` （Firefox） · `curl_cffi` （TLS 伪装） · `lxml` | | 存储 | Supabase Postgres（us-east-1）· S3 兼容的 blob 存储 | | 认证 | Supabase Auth（Google / GitHub / 邮箱） | | 计费 | Lemon Squeezy Webhooks | | LLM | Groq（Llama-3.3-70b 主要，Llama-3.1-8b 备用） | | 主机 | AWS Lightsail Virginia（后端）· Vercel（前端） | | CI | GitHub Actions：pytest 后端，lint+build 前端 | | 代理 | Webshare 数据中心池（默认）· Bright Data / Oxylabs 住宅（env-gated，可选） | --- ## 快速上手自行部署 您不需要我们的托管产品来使用引擎 — [`stealth-browser`](https://github.com/Rusheesonu/stealth-browser) 包（MIT）为您提供完整的 多引擎路由器作为独立库。 ```bash pip install stealth-browser ``` ```python import asyncio from stealth_browser.engines import router, Requirements async def main(): snap, decision = await router.snapshot( "https://news.ycombinator.com/", requirements=Requirements(needs_js=True, vendor_hint="cloudflare"), ) print(f"engine: {snap.engine_name}, elements: {len(snap.elements)}") print(f"router reason: {decision.reason}") asyncio.run(main()) ``` 运行整个产品（可视化选择器，API，AI 助手）： ```bash # 需求：Python 3.12+，Node 20+，安装 Google Chrome， # Supabase 项目（免费层 OK），Groq API 密钥。 git clone https://github.com/Rusheesonu/Stealth-Scraper cd Stealth-Scraper # 后端 cd backend python -m venv venv && source venv/bin/activate pip install -r requirements.txt cp .env.example .env # 填写 Supabase + Groq 密钥 python run.py # http://localhost:8000 # 前端（新终端） cd ../frontend cp .env.local.example .env.local npm install && npm run dev # http://localhost:3000 ``` `camoufox` 将在首次使用时下载补丁 Firefox 二进制文件（~350MB）到用户缓存。`nodriver` 使用您安装的 Chrome。 --- ## 仓库布局 ``` Stealth-Scraper/ ├── backend/ │ ├── app/ │ │ ├── main.py FastAPI 应用 + 30 个路由 │ │ ├── engines/ 多引擎路由器 │ │ │ ├── base.py 引擎协议 + 能力标志 + 需求 │ │ │ ├── router.py 决策逻辑 + 成功跟踪器（每主机学习） │ │ │ ├── nodriver_engine.py Chromium via patched CDP │ │ │ ├── curl_cffi_engine.py TLS-impersonating HTTP │ │ │ └── camoufox_engine.py Patched Firefox │ │ ├── snapshot.py URL → 截图 + bbox 目录 │ │ ├── extract.py 模板 → 结构化数据（行对齐） │ │ ├── assist.py AI 辅助模式生成（Groq） │ │ ├── actions.py 预快照点击/滚动/填充 │ │ ├── proxies.py 数据中心 + 住宅池选择器 │ │ ├── safety.py robots.txt + 每主机速率限制 │ │ └── detect.py 反机器人墙签名库 │ ├── tests/ pytest │ └── Dockerfile │ ├── frontend/ Next.js 16 + Tailwind v4（Apple-minimal） │ ├── bench/ │ ├── antibot.py 每供应商绕过率 │ ├── fingerprint.py 检测站点判决（LLM 判决） │ ├── throughput.py pages/$ 在固定 URL 池上 │ ├── lib.py 共享的 scrape_one 通过路由器 │ ├── llm_judge.py 基于 Groq 的通用判决读取器 │ ├── lists/ 每基准的 URL 池 │ ├── results/ 时间戳 JSON 报告 │ └── setup_needed.md 付费基础设施集成计划 │ ├── oss/stealth-browser/ 单独 git 仓库 — OSS 引擎包 ├── sdks/ │ ├── python/ stealth-scraper PyPI 包（同步 + 异步） │ ├── typescript/ stealth-scraper npm 包（ESM + CJS） │ └── mcp/ @stealth-scraper/mcp — 用于 Claude Desktop 的 MCP 服务器 ├── deploy/aws-lightsail/ Docker + Caddy + 设置/更新脚本 ├── docs/ ARCHITECTURE.md, DEPLOY.md ├── legacy/ 原始 v1 Flask + XPath 应用（保留） ├── AUDIT.md 当前架构 vs SOTA ├── LICENSES.md 依赖许可审计 └── LOOP_LOG.md 迭代日志（阶段 0 → 现在） ``` --- ## API 参考（简短） | 方法 | 路径 | 正文 | 返回 | |---|---|---|---| | `POST` | `/snapshot` | `{ url, viewport_*, actions? }` | `{ screenshot, elements[], viewport, page }` | | `POST` | `/extract` | `{ url, template[] }` | `{ fields, errors }` （行对齐的共享祖先列表） | | `POST` | `/extract/batch` | `{ urls[], template_id }` | `{ count, results[] }` | | `POST` | `/assist/template` | `{ url, description }` | 生成的模板 | | `GET` | `/templates` · `POST` `/templates` · CRUD | — | 模板存储 | | `POST` | `/schedules` | `{ template_id, cron, webhook_url? }` | 调度作业 | | `GET` | `/status` | — | 正常运行时间，引擎状态，LLM 链健康 | 完整的 OpenAPI 见 [`api.stealthscraper.dev/docs`](https://api.stealthscraper.dev/docs)。 --- ## 定价（托管） | 计划 | 抓取次数/月 | 并发 | API 访问 | 价格 | |---|---|---|---|---| | 免费 | 100 | 1 | ✓ | $0 | | Hobby | 5,000 | 3 | ✓ | $19/mo | | Pro | 50,000 | 10 | ✓ + webhook | $79/mo | | Scale | 500,000 | 25 | ✓ + 专用代理 | $299/mo | [比较计划 →](https://stealthscraper.dev/pricing) --- ## 开源 | 仓库 | 内容 | 许可证 | |---|---|---| | [**Rusheesonu/Stealth-Scraper**](https://github.com/Rusheesonu/Stealth-Scraper)（此） | 完整产品：后端 + 前端 + 基准测试。有用的如果你想自行部署整个项目。 | MIT | | [**Rusheesonu/stealth-browser**](https://github.com/Rusheesonu/stealth-browser) | 只是引擎层（路由器 + nodriver + curl_cffi + camoufox）。放入任何 Python 项目。 | MIT | 两个仓库都使用 [`nodriver`](https://github.com/ultrafunkamsterdam/nodriver) （AGPL-3.0 — 见 [LICENSES.md](LICENSES.md) 完整的依赖审计和我们的 AGPL §13 合规性）。 --- ## 路线图 **已发布** ✓ - [x] 可视化选择器（拖动选择器，自动兄弟节点，父节点退出） - [x] AI 辅助模式生成 - [x] 多引擎路由器（nodriver + curl_cffi + camoufox） - [x] 每主机学习 + 升级 - [x] Python + TypeScript SDK - [x] 用于 AI 代理的 MCP 服务器 - [x] 分页自动跟随 - [x] 浏览器操作（点击/滚动/填充） - [x] 定时抓取 + Webhooks - [x] MD/PDF 输出模式 - [x] 配方市场 - [x] 使用仪表板 - [x] 基准测试套件（反机器人 + 指纹识别 + 吞吐量） - [x] 住宅代理钩（env-gated，drop-in） - [x] **接下来** - [ ] Bright Data Web Unlocker集成 → 95%+ 反机器人 - [ ] 验证码求解器（CapSolver/2captcha）用于 PerimeterX 按住并保持 - [ ] 分层 LLM 判别器（8b 优先 + 70b 验证）将 fingerprint benchmark 推向 free-tier TPM 限制之外 - [ ] 团队席位 — 实际的多用户工作区 - [ ] BYOK — 让用户带来自己的 LLM 提供商 + 密钥 - [ ] 白标可嵌入选择器 - [ ] 推送到 master 时自动部署 CI - [ ] 生产切换：通过路由器将 main.py 的抓取端点连接到路由器（目前路由器仅限基准测试，生产环境仍直接调用 `take_snapshot`）