Cukup masukkan satu URL sumber, seluruh situs pun langsung ditayangkan

Crawling

Yozh Crawler menjelajahi sebuah situs mulai dari satu URL awal dan mengalirkan setiap halaman yang ditemukan melalui SSE. Yozh Crawler bertanggung jawab atas proses penemuan — penjelajahan awal, penghapusan duplikat, cakupan, ekstraksi tautan, upaya ulang, dan etika akses — sementara pengambilan setiap halaman diserahkan kepada Yozh Scraper melalui HTTP. Hanya ada satu stack Playwright yang perlu dioperasikan, dan setiap fitur scraper (proxy, stealth, sesi, aturan ekstraksi) juga berlaku untuk halaman yang di-crawl.

• Predikat cakupan — same-domain / subdomains / all / regex, dengan pola include & exclude serta batas atas dan bawah yang tetap max_depth / max_pages batas atas yang tetap.
• Penghapusan duplikat berdasarkan sidik jari — URL-URL dikanonisasikan lalu di-hash (SHA1) sehingga permintaan yang urutannya diubah dan varian dengan tanda garis miring di akhir digabungkan menjadi satu kunjungan.
• Sistem round-robin per-domain — satu host yang lambat atau berukuran besar tidak dapat menghabiskan kuota pekerja yang seharusnya dialokasikan untuk host lainnya.
• Pembatas laju adaptif — sebuah token bucket global per domain (dengan jitter) yang digunakan bersama oleh semua pekerjaan; 429 mengurangi setengah RPS selama periode pendinginan.
• Kondisi sesi — Sistem penilaian ala Crawlee: 401/403/429 menghentikan sesi, kesalahan meningkatkan skornya, keberhasilan menurunkan skornya; melakukan rotasi saat skor ≥ 3 atau setelah 50 kali penggunaan.
• Streaming SSE — setiap tugas menghasilkan stats, page, page_error, dan acara done / cancelled . Tindaklanjuti temuan segera setelah muncul.

Mulai cepat

Crawler tersebut dihubungkan ke root docker-compose.yml dan muncul bersamaan dengan scraper:

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

Atau jalankan secara lokal tanpa Docker — arahkan SCRAPER_URL ke scraper yang sedang berjalan:

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

Penggunaan dasar

Kirim permintaan perayapan dengan seed_url dan sebuah scope. Panggilan tersebut langsung mengembalikan job_id segera; proses perayapan kemudian berjalan di latar belakang melalui tugas-tugas pekerja.

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
  }'

Responsnya hanyalah handle tugas:

{ "job_id": "crawl_abc123" }

Dari sini, Anda bisa menonton siaran langsung acara atau mengakses data lengkapnya.

Penemuan vs panen — tombol enable_scraping toggle

Mesin perayapan yang sama beroperasi dalam dua arah. Sebuah nilai boolean menentukan pilihan antara pemetaan penemuan yang efisien dan pengumpulan data dengan muatan penuh — dan setiap mode menggunakan konfigurasi proxy-nya sendiri, sehingga tidak terjadi tumpang tindih.

Cakupan perayapan

Cakupan menentukan batasan proses perayapan: di mana proses perayapan diperbolehkan berjalan, dan seberapa intens proses perayapan diperbolehkan mengakses setiap host. Ini adalah scope objek pada permintaan tersebut.

Hasil streaming (SSE)

Setiap tugas menampilkan aliran Server-Sent Events. Bacalah aliran tersebut untuk mengambil tindakan pada halaman-halaman begitu halaman-halaman tersebut terdeteksi, alih-alih menunggu proses perayapan selesai.

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

Aliran tersebut mengeluarkan lima jenis peristiwa:

Sebuah page Acara dalam mode penemuan terlihat seperti ini:

{
  "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
}

Status & hasil

Lebih suka metode polling? Catatan pekerjaan dapat diakses kapan saja — termasuk saat proses crawling sedang berlangsung, dengan halaman-halaman yang telah ditemukan sejauh ini. /results adalah alias dari titik akhir pekerjaan, yang dipertahankan untuk kesesuaian dengan scraper.

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 }
  ]
}

Membatalkan proses perayapan

Hentikan pekerjaan yang sedang berjalan dengan DELETE. Pembatalan lembut adalah pengaturan default dan pilihan yang aman.

# 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 dipasang di /mcp sebagai titik akhir HTTP yang dapat dialirkan. Arahkan Claude atau Cursor ke sana dan alat-alat tersebut akan muncul secara otomatis:

• health
• create_crawl
• get_crawl
• get_crawl_results
• cancel_crawl

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

Panduan Konfigurasi

Permintaan — CrawlRequest

Per halaman — ScrapeOptions (terpilih)

Variabel lingkungan

Referensi API

Rincian penting