用途:将自有管线无法访问的抓取源切换到外部 Firecrawl 后端。Firecrawl 按计划抓取页面(代理可绕过反爬挑战),对每次检查做差分,运行 AI 有意义性判断,并向本系统 POST webhook,该回调成为一个 release。它不是新的源类型,而是现有抓取源上的按源开关,配置存放在 source.metadata.firecrawl,source.url 仍是人类可读页面。仅限生产环境;staging 不与 prod 共享绑定,切勿把绑定加入 [env.staging]。
适用时机:页面处于自有浏览器渲染无法清除的 Cloudflare Managed Challenge 等挑战之后;或客户端渲染页面持续失败且没有 feed、.md 视图、GitHub 源可用。不适用:可正常工作的 feed/GitHub/普通抓取源(Firecrawl 每次检查消耗额度,仓库内管线免费);渲染偶发问题应先跑 releases source fetch <source> --dry-run 确认;staging 或无生产绑定的环境。
启用方式:对 scrape 监控(默认,监视一个多条目索引页)执行 curl -sS -X POST "$RELEASES_API_URL/v1/sources/<src_…>/firecrawl/sync" -H "Authorization: Bearer $RELEASES_API_KEY" -H "Content-Type: application/json" -d '{ "enabled": true }';crawl 监控(索引链接到每个条目单独页面)在 body 中加 "target": "crawl"。Body 支持 enabled、schedule?、proxy?(auto|basic|stealth|enhanced)、goal?、target?(scrape|crawl)。默认每 6 小时、proxy auto、通用 release 检测目标。启用会创建监控并把 monitorId 写入 metadata.firecrawl;enabled: false 会删除监控。
陷阱:创建后以 Firecrawl 仪表盘为准,后续 sync 只同步应用自有 webhook,仪表盘调的 schedule/proxy/goal/target 不会被回退;重指向所有监控 webhook 无批量路由,需列出带 monitorId 的源并逐个 POST 空 {};scrape↔crawl 切换需先禁用再启用;crawl 监控每次检查是完整爬取,节奏应慢(默认 24h);crawl 选项通过 PATCH /v1/sources/:id/metadata 存在 metadata.firecrawl.crawl,是 Firecrawl 路径正则而非仓库内爬取适配器的 URL glob;firecrawl.enabled 源会自动从 cron 拉取中排除,不要对其手动抓取。启用后应记入组织 playbook。
排障:firecrawl-staleness 会标记 lastFetchedAt 超过 max(48h 下限, 2×监控实时节奏) 的源。检查监控是否存活(GET /v2/monitor/{monitorId}/checks,JSON 可能含原始控制字符,需宽松解析);查看 Axiom 日志中 firecrawl-webhook 与 firecrawl-ingest-workflow 事件;credits-exhausted(402) 表示额度用尽,auth-failed(401/403) 表示密钥漂移;无 webhook 事件可重跑 sync { enabled: true } 自愈。内容错误:webhook 是无 hunk 的整文档差分,只能用 addedContentFromDiff 解析新增内容;crawl 目标用 CRAWL_PAGE_SYSTEM_PROMPT,scrape 索引用摘要提示词;残留压缩可用 POST /v1/workflows/refetch-release 修复。上线后旧历史缺失属预期,基线只覆盖最新约 10K token,需用回填机制恢复。相关文档:finding-changelogs、managing-sources、backfilling-sources、docs/architecture/firecrawl-monitoring.md。