Con una sola URL de origen, se transmitió todo el sitio web

Rastreo

Yozh Crawler recorre un sitio web a partir de una única URL inicial y transmite todas las páginas descubiertas a través de SSE. Se encarga de todo el proceso de descubrimiento —frontera, deduplicación, alcance, extracción de enlaces, reintentos y cortesía—, mientras que la obtención de cada página se delega a Yozh Scraper a través de HTTP. Solo hay que gestionar una única pila de Playwright, y todas las funciones del scraper (proxy, modo sigiloso, sesiones, reglas de extracción) se aplican también a las páginas rastreadas.

• Predicados de ámbito — same-domain / subdomains / all / regex, con patrones de inclusión y exclusión y max_depth / max_pages límites máximos.
• Deduplicación por «huella digital»: las URL se canonicizan y, a continuación, se someten a un algoritmo hash (SHA1), de modo que las consultas reordenadas y las variantes con barra al final se agrupan en una sola visita.
• Método «round-robin» por dominio: un servidor lento o de gran tamaño no puede privar a los demás de trabajadores.
• Limitador de velocidad adaptativo: un «token bucket» global por dominio (con fluctuación) compartido entre los distintos trabajos; un 429 reduce a la mitad el RPS durante un periodo de espera.
• Estado de la sesión — Puntuación al estilo Crawlee: 401/403/429 cerrar una sesión; los errores aumentan su puntuación, mientras que el éxito la reduce; rotar cuando la puntuación sea ≥ 3 o tras 50 usos.
• Transmisión SSE: cada trabajo emite stats, page, page_errory eventos de terminal done / cancelled . Actúa ante los resultados a medida que se van recibiendo.

Inicio rápido

El rastreador está conectado a la raíz docker-compose.yml y se ejecuta junto con el scraper:

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

O bien, ejecútalo localmente sin Docker: dirígete SCRAPER_URL a un scraper en ejecución:

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

Uso básico

Enviar un rastreo con un seed_url y un scope. La llamada devuelve un job_id de inmediato; a continuación, el rastreo se ejecuta en segundo plano a través de tareas de trabajo.

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

La respuesta es simplemente el identificador de la tarea:

{ "job_id": "crawl_abc123" }

Desde aquí puedes ver eventos en directo o consultar el trabajo para obtener el registro completo.

Descubrimiento frente a recolección: el enable_scraping alternar

El mismo motor de rastreo funciona en ambos sentidos. Un valor booleano permite elegir entre un mapa de descubrimiento ligero y una recopilación con carga completa, y cada modo utiliza su propia configuración de proxy, por lo que no hay interferencias entre ellos.

Ámbito del rastreo

El ámbito delimita el rastreo: dónde se permite que se desplace y hasta qué punto se permite que ejerza presión sobre cada host. Es el scope objeto de la solicitud.

Resultados de streaming (SSE)

Cada tarea expone un flujo de eventos enviados por el servidor. Léalos para actuar sobre las páginas en el momento en que se detecten, en lugar de esperar a que finalice el rastreo.

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

El flujo emite cinco tipos de eventos:

Un page evento en modo de descubrimiento tiene este aspecto:

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

Situación y resultados

¿Prefieres realizar consultas? El registro del trabajo se puede consultar en cualquier momento —incluso durante el rastreo—, con las páginas descubiertas hasta ese momento. /results es un alias del punto final del trabajo, que se mantiene por simetría con el rastreador.

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

Cancelación de un rastreo

Detén un trabajo en ejecución con un DELETE. La cancelación suave es la opción predeterminada y la más segura.

# 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 está montado en /mcp como un punto final HTTP de Streamable. Apunta Claude o Cursor hacia él y las herramientas aparecerán automáticamente:

• health
• create_crawl
• get_crawl
• get_crawl_results
• cancel_crawl

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

Referencia de configuración

Solicitud — CrawlRequest

Por página — ScrapeOptions (seleccionado)

Variables de entorno

Referencia de la API

Detalles importantes