用途:当需要一个长期运行的 HTTP 服务来执行 scrape/crawl/map,而不是一次性 CLI 调用或 MCP 服务时使用;crawlberg serve 会把抓取引擎以 REST API 形式暴露,接口兼容 Firecrawl v1,现有 Firecrawl 客户端与 SDK 可指向本地 crawlberg 实例。
构建要求:该子命令需要以可选 api feature 构建(非默认)。Homebrew 版本包含全部特性,直接可用;源码构建需执行 cargo install crawlberg-cli --features api(或 --features all)。
启动与参数:crawlberg serve --host 127.0.0.1 --port 3000 会在 stderr 输出 Starting REST API server on <host>:<port> 并阻塞运行,直至被终止。--host 默认 0.0.0.0,--port 默认 3000。serve 不接受逐次抓取参数,启动时使用默认 CrawlConfig,逐请求选项放在各 HTTP 请求体中。可用 GET /health 确认存活。
接口:POST /v1/scrape(同步抓取单个 URL)、POST /v1/crawl(异步爬取,返回 job id)、GET/DELETE /v1/crawl/{id}(轮询状态与结果、取消任务)、POST /v1/map(同步发现站点 URL)、POST /v1/batch/scrape 与 GET /v1/batch/scrape/{id}(异步批量抓取)、POST /v1/download(下载文档);运维接口有 GET /health、GET /version、GET /openapi.json。请求体使用 camelCase 字段,抓取/爬取/地图参数与 CLI 对应,响应包装为 { success, data | error },异步任务返回 { success, id },轮询返回 { status, total, completed, data, error }。
限制与安全:服务接受任意来源 CORS 且无内置认证,不要暴露在公网;本地使用绑定 127.0.0.1,如需更广泛暴露应置于反向代理或网关之后并强制认证与限流。请求体上限 10 MB,单请求超时 5 分钟。crawl 与 batch/scrape 为异步,需轮询至 completed、failed 或 cancelled。CLI 适合一次性任务与脚本,MCP 适合在 AI 智能体内驱动爬虫,serve 适合多调用方通过网络访问爬虫或需要 Firecrawl v1 兼容的场景。