Bastou introduzir um URL de origem para que todo o site fosse transmitido

Rastreio

O Yozh Crawler percorre um site a partir de um único URL inicial e transmite todas as páginas descobertas através do SSE. É responsável pela descoberta — fronteira, deduplicação, âmbito, extração de links, novas tentativas, cortesia —, enquanto a recuperação de cada página é delegada ao Yozh Scraper através de HTTP. Há exatamente uma pilha do Playwright para operar, e todas as funcionalidades do scraper (proxy, modo furtivo, sessões, regras de extração) aplicam-se também às páginas rastreadas.

• Predicados de âmbito — same-domain / subdomains / all / regex, com padrões de inclusão e exclusão e max_depth / max_pages limites rígidos.
• Desduplicação por «impressão digital» — Os URLs são canonizados e, em seguida, submetidos a um algoritmo de hash (SHA1), de modo a que as consultas reordenadas e as variantes com barra final sejam agrupadas numa única visita.
• Método «round-robin» por domínio — um host lento ou de grandes dimensões não pode privar os outros de trabalhadores.
• Limitador de taxa adaptativo — um «token bucket» global por domínio (com jitter) partilhado entre tarefas; um 429 reduz para metade o RPS durante um período de arrefecimento.
• Estado da sessão — Pontuação ao estilo Crawlee: 401/403/429 encerrar uma sessão; os erros aumentam a sua pontuação, enquanto os sucessos a reduzem; alternar quando a pontuação for ≥ 3 ou após 50 utilizações.
• Transmissão SSE — cada tarefa emite stats, page, page_errore eventos de terminal done / cancelled . Reaja às descobertas à medida que estas surgem.

Início rápido

O rastreador está ligado à raiz docker-compose.yml e surge juntamente com o scraper:

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

Ou execute-o localmente sem o Docker — selecione SCRAPER_URL para um scraper em execução:

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

Utilização básica

Enviar um rastreio com um seed_url e um scope. A chamada devolve um job_id imediatamente; o rastreio é então executado em segundo plano através de tarefas de trabalho.

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

A resposta é apenas o identificador da tarefa:

{ "job_id": "crawl_abc123" }

A partir daqui, pode transmitir eventos em direto ou consultar a tarefa para obter o registo completo.

Descoberta vs. colheita — o enable_scraping alternar

O mesmo motor de rastreamento funciona nos dois sentidos. Um valor booleano permite escolher entre um mapa de descoberta com baixo custo e uma recolha com carga útil completa — e cada modo utiliza a sua própria configuração de proxy, pelo que não há interferência entre eles.

Âmbito do rastreio

O âmbito define os limites do rastreio: onde é permitido avançar e até que ponto é permitido sobrecarregar cada anfitrião. É o scope objeto na solicitação.

Resultados de streaming (SSE)

Cada tarefa disponibiliza um fluxo de eventos enviados pelo servidor (Server-Sent Events). Leia-o para agir nas páginas assim que forem detetadas, em vez de esperar que o rastreio termine.

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

O fluxo emite cinco tipos de eventos:

Um page evento no modo de descoberta tem o seguinte aspeto:

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

Situação e resultados

Prefere fazer uma consulta? O registo da tarefa pode ser consultado a qualquer momento — inclusive a meio do rastreio, com as páginas descobertas até ao momento. /results é um alias do endpoint da tarefa, mantido por uma questão de simetria com o 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 }
  ]
}

Cancelar um rastreio

Interromper uma tarefa em execução com um DELETE. O cancelamento suave é a opção predefinida e a escolha mais 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 em /mcp como um ponto final HTTP do Streamable. Basta apontar o Claude ou o Cursor para ele e as ferramentas aparecem automaticamente:

• health
• create_crawl
• get_crawl
• get_crawl_results
• cancel_crawl

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

Referência de configuração

Pedido — CrawlRequest

Por página — ScrapeOptions (selecionado)

Variáveis de ambiente

Referência da API

Detalhes importantes