Один стартовый URL на входе — весь сайт потоком на выходе

Обход

Yozh Crawler обходит сайт с одного стартового URL и передаёт каждую найденную страницу по SSE. Он берёт на себя обнаружение — фронтир, дедуп, скоуп, извлечение ссылок, повторы, вежливость — а загрузку каждой страницы делегирует Yozh Scraper по HTTP. Обслуживать нужно ровно один стек Playwright, и все возможности скрейпера (прокси, stealth, сессии, правила извлечения) действуют и для обойдённых страниц.

• Предикаты скоупа — same-domain / subdomains / all / regex, с include- & exclude-паттернами и жёсткими лимитами max_depth / max_pages.
• Дедуп по отпечатку — URL канонизируются и хэшируются (SHA1), поэтому переставленные query-параметры и варианты с завершающим слэшем схлопываются в одно посещение.
• Round-robin фронтир по доменам — один медленный или огромный хост не может забрать всех воркеров у остальных.
• Адаптивный ограничитель частоты — глобальный token bucket по доменам (с джиттером), общий для всех задач; 429 вдвое снижает RPS на время остывания.
• Здоровье сессий — скоринг в стиле Crawlee: 401/403/429 выводят сессию из ротации, ошибки повышают её счёт, успех понижает; ротация при счёте ≥ 3 или 50 использованиях.
• Потоковая передача SSE — каждая задача шлёт события stats, page, page_error и финальные done / cancelled. Реагируйте на находки по мере их поступления.

Быстрый старт

Краулер прописан в корневом docker-compose.yml и поднимается вместе со скрейпером:

docker compose up --build
# scraper  → http://localhost:8000
# crawler  → http://localhost:8001

Или запустите его локально без Docker — укажите в SCRAPER_URL адрес работающего скрейпера:

cd yozh-crawler
pip install -r requirements.txt
cp .env.example .env          # edit SCRAPER_URL if needed
python -m uvicorn src.main:app --reload --port 8001

Базовое использование

Отправьте обход с seed_url и scope. Вызов сразу возвращает job_id; далее обход выполняется в фоне на воркер-задачах.

curl -X POST http://localhost:8001/api/v1/crawl 
  -H "Content-Type: application/json" 
  -d '{
    "seed_url": "https://example.com",
    "scope": {"mode": "same-domain", "max_depth": 2, "max_pages": 50,
              "per_domain_rps": 1.0, "per_domain_concurrency": 1},
    "scrape_options": {"proxy_type": "none"},
    "enable_scraping": false
  }'

Ответ — это просто дескриптор задачи:

{ "job_id": "crawl_abc123" }

Дальше вы либо читаете события в реальном времени, либо опрашиваете задачу для получения полной записи.

Обнаружение vs сбор — переключатель enable_scraping

Один и тот же движок обхода работает в обоих режимах. Единственный булев флаг выбирает между дешёвой картой обнаружения и полным сбором данных — и каждый режим использует свою конфигурацию прокси, так что смешения нет.

Скоуп обхода

Скоуп ограничивает обход: где ему разрешено ходить и насколько интенсивно нагружать каждый хост. Это объект scope в запросе.

Потоковая выдача (SSE)

Каждая задача предоставляет поток Server-Sent Events. Читайте его, чтобы реагировать на страницы в момент их обнаружения, не дожидаясь завершения обхода.

curl -N http://localhost:8001/api/v1/crawl/crawl_abc123/events

Поток отправляет пять типов событий:

Событие page в режиме обнаружения выглядит так:

{
  "event": "page",
  "url": "https://example.com/docs/intro",
  "parent_url": "https://example.com/docs",
  "depth": 2,
  "status_code": 200,
  "took_ms": 812,
  "scrape_response": null
}

Статус и результаты

Предпочитаете опрос? Запись задачи доступна в любой момент — в том числе во время обхода, со страницами, найденными к этому моменту. /results — это алиас эндпоинта задачи, оставленный для симметрии со скрейпером.

curl http://localhost:8001/api/v1/crawl/crawl_abc123
curl http://localhost:8001/api/v1/crawl/crawl_abc123/results

{
  "job_id": "crawl_abc123",
  "status": "running",
  "stats": {
    "visited": 47, "queued": 12, "failed": 0,
    "dedup_skipped": 9, "out_of_scope": 31, "retries_total": 2
  },
  "pages": [
    { "url": "https://example.com/", "parent_url": null,
      "depth": 0, "status_code": 200, "took_ms": 640 }
  ]
}

Отмена обхода

Остановите выполняющуюся задачу через DELETE. Мягкая отмена — вариант по умолчанию и безопасный выбор.

# soft — stop scheduling, let in-flight requests drain
curl -X DELETE "http://localhost:8001/api/v1/crawl/crawl_abc123?hard=false"

# hard — abort in-flight asyncio tasks immediately
curl -X DELETE "http://localhost:8001/api/v1/crawl/crawl_abc123?hard=true"

MCP

fastapi-mcp смонтирован по адресу /mcp как Streamable HTTP-эндпоинт. Укажите на него Claude или Cursor — и инструменты появятся автоматически:

• health
• create_crawl
• get_crawl
• get_crawl_results
• cancel_crawl

"open-crawler": {
  "type": "http",
  "url": "http://localhost:8001/mcp"
}

Справочник по конфигурации

Запрос — CrawlRequest

Для каждой страницы — ScrapeOptions (выборочно)

Переменные окружения

Справочник API

Важные детали