SuperAPI AI 工具集

serving-the-api

通用与其它

查看项目

更新于 10-16 07:18

技能介绍

用途:crawlberg serve 启动长期运行的 REST API 服务,通过 HTTP 暴露抓取引擎,端点兼容 Firecrawl v1,便于现有 Firecrawl 客户端与 SDK 指向本地实例。

前提:需以可选 api 特性构建二进制(非默认)。Homebrew 版本含全部特性可用;源码构建需 cargo install crawlberg-cli --features api(或 --features all)。

启动:crawlberg serve --host 127.0.0.1 --port 3000。日志输出 Starting REST API server on <host>:<port> 到 stderr 并阻塞直至终止,可用 GET /health 确认。

参数:--host 默认 0.0.0.0(绑定地址);--port 默认 3000(监听端口)。serve 不接受按请求的抓取参数,以默认 CrawlConfig 启动,按请求选项在各 HTTP 请求体中传入。

端点:POST /v1/scrape(同步单页抓取)、POST /v1/crawl(异步抓取任务,返回 id)、GET /v1/crawl/{id}(轮询状态与结果)、DELETE /v1/crawl/{id}(取消任务)、POST /v1/map(同步发现 URL)、POST /v1/batch/scrape(异步批量抓取,返回 id)、GET /v1/batch/scrape/{id}(轮询)、POST /v1/download(下载文档)。运维端点:GET /health、GET /version、GET /openapi.json。

请求体使用 camelCase 字段,scrape/crawl/map 与 CLI 对应:scrape 有 url、formats、onlyMainContent、includeTags/excludeTags、timeout;crawl 有 url、maxDepth、maxPages、includePaths/excludePaths;map 有 url、limit、search。响应包装为 { success, data | error };异步任务返回 { success, id },轮询得到 { status, total, completed, data, error }。

使用示例:curl -s http://127.0.0.1:3000/v1/scrape -H 'content-type: application/json' -d '{"url":"https://example.com","formats":["markdown"]}' | jq '.data'。异步抓取先 POST /v1/crawl 取 .id,再轮询 /v1/crawl/$id。

限制:接受任意来源 CORS,且无内置认证,不要暴露在公网;本地用应绑定 127.0.0.1,或置于强制认证与限流的反向代理/网关之后。请求体上限 10 MB,单请求超时 5 分钟。crawl 与 batch-scrape 为异步,POST 立即返回任务 id,需轮询至 completed、failed 或 cancelled。

选用时机:CLI 适合一次性任务、shell 管道与脚本,无需长期进程;MCP(crawlberg mcp)适合在 AI 智能体环境中驱动爬虫;serve 适合其他应用或非智能体客户端以 REST 访问,或需要 Firecrawl v1 兼容、多个调用方通过网络共用爬虫的场景。