Введіть лише одну URL-адресу, і весь сайт завантажиться

Обхід

Yozh Crawler обходить сайт, починаючи з одного вихідного URL-адреси, і передає кожну виявлену сторінку через SSE. Він відповідає за процес виявлення — визначення меж, дедуплікацію, визначення області пошуку, вилучення посилань, повторні спроби та дотримання правил ввічливості — тоді як завантаження кожної сторінки делегується Yozh Scraper через HTTP. Для роботи використовується лише один стек Playwright, і всі функції скрепера (проксі, прихований режим, сесії, правила вилучення даних) застосовуються також і до проіндексованих сторінок.

• Предикати області дії — same-domain / subdomains / all / regex, з шаблонами включення та виключення та жорсткими max_depth / max_pages обмеженнями.
• Дедуплікація за «відбитками» — URL-адреси канонізуються, а потім хешуються (SHA1), завдяки чому запити з іншою послідовністю та варіанти з кінцевим слешем об’єднуються в одне відвідування.
• Принцип «round-robin» на рівні домену — один повільний або величезний хост не може позбавити інших робочих процесів.
• Адаптивний обмежувач швидкості — глобальний «кошик токенів» (з джиттером) для кожного домену, спільний для всіх завдань; це 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" }

Звідси ви можете або дивитися прямі трансляції подій, або завантажити повний запис.

«Відкриття» проти «збору» — 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

Важливі деталі