★ 在 GitHub 上已获得 84 个星标，且数量仍在增加。Yozh Crawler + Scraper 是一款免费、开源且公开开发的工具——如果它能成为您技术栈中的一员，请给我们点个星标。
CyberYozh Data / Yozh 刮板
软件 · Yozh Scraper

输入一个网址，输出干净的结构化数据

Yozh Scraper 可在真实的 Playwright 浏览器中渲染任何 URL，并精确返回您所需的内容——无论是提取的字段、原始 HTML 还是整页截图。内置 CyberYozh 代理（默认启用隐身模式）、主流网站的预设配置以及认证会话。非 SaaS 服务，运行于 :8000.

从 GitHub 安装 阅读文档
$curl -X POST :8000/api/v1/scrape/page -d '{"url":"https://site.com", "proxy_type":"res_rotating","extract":{"type":"css","fields":{...}}}'

抓取

Yozh Scraper 会在真实的 Playwright 浏览器中渲染任何 URL，并精确返回您所需的内容——无论是提取的字段、原始 HTML 还是整页截图。 每次抓取都是一项异步任务：提交 URL、轮询任务状态、获取结果。代理、隐身模式、预设以及经过身份验证的会话均被原生支持。

  • 真实的浏览器渲染——Playwright 渲染由 JavaScript 构建的页面；切换 render 以禁用静态 HTML。
  • 结构化提取——CSS 或 XPath 字段规则会返回一个格式规范的 data 对象，这比自己下载并解析原始 HTML 要高效得多。
  • 内置代理——CyberYozh 家庭/移动 LTE/数据中心代理，支持地理定位，且不会被追踪池 ID。
  • 默认启用隐身模式——playwright-stealth 补丁（navigator.webdriver，WebGL/Canvas 指纹、Chrome 运行时），以降低被机器人检测的概率。
  • 预设 — 按名称抓取亚马逊/谷歌/eBay/沃尔玛/YouTube/领英的数据，可选配大语言模型（LLM）自愈功能。
  • 会话——针对已登录目标由服务器管理的经过身份验证的会话，可在多次抓取中重复使用。
基础网址http://localhost:8000
OpenAPI 文档http://localhost:8000/docs
MCP 端点http://localhost:8000/mcp
与 Yozh Crawler 配合使用。该爬虫（:8001）会从一个种子URL开始遍历网站，并通过此抓取工具获取每个页面——渲染、代理和会话功能同样适用于被爬取的页面。

快速开始

抓取器从根节点 docker-compose.yml 启动（与爬虫并行）：

bash 
cp .env.example .env          # set CYBERYOZH_API_KEY if using proxies
docker compose up --build
# scraper → http://localhost:8000
# crawler → http://localhost:8001

确认它已上线：

bash 
curl http://localhost:8000/api/v1/health
# {"status":"ok","workers":2}
代理需要一个 API 密钥——请设置 CYBERYOZH_API_KEY 在 .env (可在 app.cyberyozh.com/api-access处获取一个）。若未设置，仅 proxy_type: none 功能可用。

基本用法

每个抓取端点都会创建一个后台任务，并返回一个 job_id。轮询该任务，然后获取其结果。

cURL 
curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{ "url": "https://example.com", "proxy_type": "none" }'
# → { "job_id": "req_abc123" }

curl http://localhost:8000/api/v1/scrape/req_abc123          # status
curl http://localhost:8000/api/v1/scrape/req_abc123/results  # results

最终结果包含元数据以及您所请求的任何内容（data, raw_html, screenshot_base64):

JSON 
{
  "job_id": "req_abc123",
  "status": "done",
  "total": 1, "done": 1,
  "results": [
    {
      "request_id": "req_abc123",
      "took_ms": 1234,
      "meta": { "url": "https://example.com", "final_url": "https://example.com/",
                "status_code": 200, "device": "desktop", "proxy_type": "none", "retries": 0 },
      "data": null, "raw_html": null, "screenshot_base64": null, "warnings": []
    }
  ]
}
status 动作 queued → running → done (或 failed / cancelled)。结果可查阅 done, failed，以及 cancelled 工作。

提取数据

通过一项 extract 规则，响应中将包含一个 data 以字段名称为键的对象——这比下载 raw_html 并自行解析该数据。规则是 css 或 xpath.

cURL 
curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{
    "url": "https://example.com",
    "extract": {
      "type": "css",
      "fields": {
        "title": { "selector": "h1", "attr": "text", "required": true }
      }
    }
  }'
# result → { "data": { "title": "Example Domain" } }

每个字段都是一条规则：

字段键类型默认值说明
selectorstring必填该字段的 CSS 选择器或 XPath 表达式。
attrstringtext阅读指南 — text 或一个属性名称（例如 href, src).
allboolfalse将所有匹配项作为列表返回，而不是只返回第一个。
requiredboolfalse当缺失时触发警报——驱动预设的LLM自愈机制。

使用 "type": "xpath" 配合 XPath 选择器（例如 //h1) 来表示相同的形状。

屏幕截图和原始 HTML 代码

点击此处 screenshot: true 为全屏 PNG（以 base64 格式 screenshot_base64），或 raw_html: true 获取渲染后的完整文章 HTML 代码 raw_html.

cURL 
curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{ "url": "https://example.com", "screenshot": true, "raw_html": true }'
截图会触发一次滚动操作，以加载延迟加载的图片。如果你还使用了 block_assets，请将其在截图时关闭，以便图片正常渲染。

代理

要实现可靠的网页抓取，代理是必不可少的——大多数现代网站都会屏蔽直接请求。Yozh 与 CyberYozh 代理服务集成；只需 proxy_type 在任何请求中启用。

proxy_type什么是……
res_rotating住宅轮换——推荐的默认设置。
res_static住宅静态IP（专用IP）。
mobile移动网络/LTE，专用。
mobile_shared移动网络/LTE，共享资源池。
dc_static数据中心静态。
none直接连接，不经代理。

使用 proxy_geo (country_code / region / city）。无需费力查找池 ID，即可查看您已购买的内容：

cURL 
curl "http://localhost:8000/api/v1/proxies/available?proxy_type=res_rotating"
curl "http://localhost:8000/api/v1/proxies/countries"
代理服务器需要 CYBERYOZH_API_KEY 在爬虫的 .env。请在 app.cyberyozh.com/api-access，然后重启容器。

预设

一个预设包含请求配置文件、URL 模板和解析规则，因此您可以直接通过网站名称进行抓取，而无需手动组装请求。系统内置了适用于亚马逊、谷歌、eBay、沃尔玛、YouTube 和 LinkedIn 的预设；您也可以自行创建预设（确定性 CSS/XPath 或 AI 生成的）。

cURL 
curl -X POST http://localhost:8000/api/v1/scrape/preset/page 
  -H "Content-Type: application/json" 
  -d '{
    "source": "amazon_product",
    "preset_params": { "asin": "B08N5WRWNW" },
    "locale": "us",
    "llm": { "model": "openai/gpt-5.4-mini" }
  }'
# → { "job_id": "..." }  then GET /api/v1/scrape/<job_id>/results
llm 该参数是可选的。如果不指定该参数，确定性解析器将独立运行；如果指定了该参数，当 required 字段返回为空时，选择器会自动修复。提供程序键（OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY / OPENROUTER_API_KEY）位于服务器端，在 .env.

通过 GET /api/v1/presets, GET /api/v1/presets/{name}，以及 POST /api/v1/presets （用户预设名称必须以 user_).

会话

服务器管理的认证会话：创建一个会话，登录一次，然后将其 session_id 传递给任何抓取任务，从而使用存储的 Cookie 和存储状态来获取页面。对于已登录的目标（例如 linkedin_profile 预设。

  1. POST /api/v1/sessions — 创建。引脚 device / proxy_type / proxy_geo 和一个 TTL。返回 { session_id, expires_at }.
  2. POST /api/v1/sessions/{id}/login — 重放一个声明式登录脚本， creds ，其正文包含： { script, creds }.
  3. POST /api/v1/scrape/page 与 session_id set — 已通过身份验证的抓取。
  4. DELETE /api/v1/sessions/{id} — 清理一下。
cURL 
# 1. create  →  {"session_id":"sess_...","expires_at":...}
curl -X POST http://localhost:8000/api/v1/sessions 
  -H "Content-Type: application/json" 
  -d '{ "device": "desktop", "proxy_type": "res_rotating" }'

# 2. log in (declarative DSL + creds)
curl -X POST http://localhost:8000/api/v1/sessions/sess_.../login 
  -H "Content-Type: application/json" 
  -d '{ "script": { "steps": [ {"op":"goto","url":"https://site/login"} ] },
        "creds": { "username": "...", "password": "..." } }'

# 3. scrape with the session
curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{ "url": "https://site/secure", "session_id": "sess_...", "raw_html": true }'
session_id 和 cookies 组合起来 → 422。抓取结果 device / proxy_type / proxy_pool_id / proxy_geo 必须与会话的固定值相匹配。对于登录 DSL 无法解决的 CAPTCHA / 2FA 情况，请跳过脚本，转而将会话cookie注入到会话中。

批量抓取

使用以下方式在单个任务中提交多页： POST /api/v1/scrape/pages — 每个条目都代表一个完整的抓取请求。通过同一任务端点查询状态并获取结果。

cURL 
curl -X POST http://localhost:8000/api/v1/scrape/pages 
  -H "Content-Type: application/json" 
  -d '{
    "pages": [
      { "url": "https://example.com", "proxy_type": "none" },
      { "url": "https://example.org", "proxy_type": "none" }
    ]
  }'
顶级 session_id 适用于批次中的每一页（如果某页已固定了另一个，则会返回 422 状态码拒绝该请求）。

MCP

该抓取工具在 /mcp (可流式传输的 HTTP) 处部署了一个模型上下文协议（Model Context Protocol）端点。将 Claude 或 Cursor 指向它，相关工具便会自动显示：

  • run_scrape_page
  • run_scrape_pages
  • get_job_status
  • get_job_result
  • cancel_scrape_job
  • health
~/.claude/settings.json 
"yozh-scraper": {
  "type": "http",
  "url": "http://localhost:8000/mcp"
}

然后只需询问：“抓取 https://example.com，并告诉我页面上有什么内容。”无论通过 LangChain 代理还是 n8n MCP 客户端工具节点，该端点均可正常工作。

配置参考

请求 — ScrapeRequest (已选中)

字段类型默认值说明
url字符串 (URL)必填要渲染和抓取的页面。
renderbooltrue使用浏览器渲染（JS构建的页面需要此操作）。
wait_untildomcontentloaded · networkidledomcontentloaded当页面被视为准备就绪时。
wait_for_selector字符串 · nullnull在捕获之前，先等待某个特定元素出现。
devicedesktop · mobiledesktop视口 / 用户代理配置文件。
proxy_type参见“代理”none代理池用于转发请求路由。
proxy_geoProxyGeo · nullnull国家/地区/城市定向投放。
session_id字符串 · nullnull使用经过身份验证的会话——请参阅“会话”。
stealthbooltrue应用反检测加固措施。
block_assetsbool · nullenv为提高速度而屏蔽图片/字体/媒体（回退到 BLOCK_ASSETS).
extractExtractRule · nullnullCSS/XPath 字段规则 → 结构化 data.
raw_htmlboolfalse请包含渲染后的完整 HTML 代码。
screenshotboolfalse截取整页的 PNG 图片（base64 格式）。

API 参考

方法路径用途
POST/api/v1/scrape/page抓取一页。返回 {"job_id":"…"}.
POST/api/v1/scrape/pages在一个任务中批量抓取多个页面。
POST/api/v1/scrape/preset/page按预设名称（Amazon、Google 等）进行抓取。
GET/api/v1/scrape/{id}任务状态（已排队/正在运行/已完成/……）。
GET/api/v1/scrape/{id}/results作业结果（pages + ScrapeResponse）。
DELETE/api/v1/scrape/{id}软取消——机上页面已结束。
POST/api/v1/sessions创建一个经过身份验证的会话。
POST/api/v1/sessions/{id}/login运行一个声明式登录脚本。
DELETE/api/v1/sessions/{id}删除一个会话。
GET/api/v1/proxies/available列出已购买的某类型代理。
GET/api/v1/presets列出内置和用户预设。
GET/api/v1/health健康状况 + 员工人数。

重要细节

代理需要一个 API 密钥。请在 CYBERYOZH_API_KEY 在爬虫的 .env。若未设置，则仅 proxy_type: none (直接) 方式才有效。
异步、内存中的任务。每次抓取都是一个后台任务；数据存储在内存中，并在容器重启时重置。可在结果可用时立即获取，或自行将其持久化。
会话与Cookie是互斥的。同时传递这两个 session_id 和 cookies 都会返回 422 状态码，且抓取内容必须与会话的固定值相匹配 device / proxy_type / proxy_geo.
LLM 自愈功能在服务器端实现。预设自愈功能使用提供商密钥（OPENAI / ANTHROPIC / GEMINI / OPENROUTER）来自 .env ——客户端绝不会发送这些密钥。

深受数据团队和人工智能开发者的喜爱

使用 Yozh 进行开发的用户怎么说

5.0 / 5 · 5 评测
GitHub
仅用一个下午就将我们内部的 Playwright 集群替换为 Yozh。MCP 端点直接接入我们的 Claude 代理——无需任何胶水代码，爬虫和数据提取工具便能正常运行。
Marcus Reinhardt 首席数据工程师 Northwind Analytics
X
预设系统是其杀手级功能。我们传入源名称，就能得到干净的 JSON 数据；其自动修复功能甚至在我们察觉之前就发现了亚马逊的两次布局变更。
Priya Nair 创始人 ScrapeStack
Reddit
终于出现了一个将代理和会话视为第一类对象的开源爬虫工具。我们将其部署在合作伙伴门户网站的登录墙后方——会话能够保持持久性，且跨区域的爬取结果始终保持一致。
Daniel Osei 后端工程师 Loopfeed
X
通过 MCP 将其连接到 Cursor 后，我的代理现在可以在任务进行中实时提取网页数据。通过 SSE 进行的流式爬取，正是代理工作流所缺失的功能。
Elena Kovac 人工智能工程师 Vektor Labs
GitHub
为了节省成本，我们放弃了付费的数据抓取 API，并做好了性能下降的准备——结果却事与愿违。现在采用自托管模式，无需按请求付费，而且输出数据结构比我们以前付费使用的还要简洁。
Sofia Almeida 工程经理 Tabbly
开源 · MIT 许可 · 84 ★

渲染一个 URL。获取干净的数据

Yozh Scraper 是整个技术栈背后的渲染引擎——它 docker compose up ，您便可在自有基础设施上拥有代理、隐身、预设、会话和数据提取功能，并支持 MCP。免费。永久免费。

从 GitHub 安装 在 GitHub 上点赞

Yozh Scraper + Crawler 根据 MIT 许可证发布。请随意使用、分叉和基于它进行开发。