Firecrawl:docker compose up -d

GitHub 趋势页上的 Firecrawl 项目讨论的是搜索、抓取与更广的数据源接入。自托管时,常见误区是先从旧教程抄一份 .env,再用旧接口判断成败。按官方指南使用 v2.11.162 时,更稳妥的路径是:固定代码版本,确认 3002 端口可用,运行 docker compose up -d,最后用 POST /v2/scrape 验证能否返回 Markdown。这就是部署成功的验收标准。

容器显示 Running,不等于 API 已经可用。如果命令执行后连不上或返回 404,应按“构建是否完成 → 容器是否持续存活 → 端口是否映射 → 请求路径是否匹配 → 服务日志 → .env 与外部提供商”的顺序排查。Crawl 是异步任务,Search 还可能依赖额外配置,一条 Scrape 请求成功,并不能证明所有能力都已经准备好。

第一条成功请求的发送与验收

先固定版本,因为官方明确说明,其他版本可能采用不同的 Compose 约定。下面的命令以 v2.11.162 为基线,仓库地址使用当前的 firecrawl/firecrawl,不要继续照抄旧文章里的 mendableai/firecrawl 路径。

git clone https://github.com/firecrawl/firecrawl.git
cd firecrawl
git checkout v2.11.162
docker compose up -d

如果仓库已经克隆过,只需取得标签并切换版本:

git fetch --tags
git checkout v2.11.162

启动后检查服务状态:

docker compose ps
docker compose logs --tail=200

验收请求如下:

curl -X POST http://localhost:3002/v2/scrape \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com"}'

官方指南验证的是 POST /v2/scrape 能成功返回 Markdown。旧资料中的 POST /scrape,以及返回 Hello, world! 的 GET /test,都属于旧版本或旧部署方式的线索,不能替代当前版本的验收请求。

如果刚执行完 docker compose up -d 就立即测试,偶尔会遇到连接尚未建立或 API 进程仍在初始化。先看 docker compose ps 和日志,再重复请求;不要因为第一次 connection refused 就立刻重建所有容器。

docker compose up -d 前的检查项

需要 Docker Engine 或 Docker Desktop,以及通过 docker compose 调用的 Compose v2。旧式的 docker-compose 命令不是这里验证的环境。

docker version
docker compose version
docker compose config --services
docker compose ps

docker compose config --services 用来确认当前版本实际编排了哪些服务。Firecrawl 的本地部署不是单个 API 容器,队列、worker 和浏览器相关服务也可能参与请求处理,因此某一个容器异常时,不能只看主进程。

启动前还要确认宿主机的 3002 端口没有被其他进程占用。Linux、macOS 和 Windows 可以分别选择一种检查方式:

ss -ltnp | grep ':3002 '
lsof -nP -iTCP:3002 -sTCP:LISTEN
netstat -ano | findstr :3002

如果端口已经被占用,应先确定是旧 Firecrawl 容器还是其他应用占用,不要盲目修改多个服务的端口变量。

资源方面,官方尚未公布这套技术栈经过验证的最低主机配置,因此不存在一个可以到处套用的“几核几 GB”答案。先检查 Docker 是否正常、资源是否紧张以及磁盘是否接近上限:

docker info
docker system df

构建阶段还需要容器能够访问基础镜像仓库和依赖下载源;这与后面的 API 端口检查是两件事。

Go 依赖下载失败

社区教程记录过这样的构建日志:

ERROR [api go-base 3/3] RUN cd /app/sharedLibs/go-html-to-md && go mod tidy && go build -o html-to-m 21.6s...

对应案例的问题发生在 go-base 阶段:容器无法访问 proxy.golang.org,导致 Go 模块依赖下载失败。 先确认当前标签里的 Dockerfile 和 Go 命令,不要直接覆盖成旧教程中的整个文件:

git ls-files | grep -E '(^|/)Dockerfile$|(^|/)\.env\.example$'
git show v2.11.162:apps/api/Dockerfile
grep -R "GOPROXY\|go mod tidy\|go build" -n --include='Dockerfile*' .

在受限网络中,社区教程给出的处理方式,是在执行 go mod tidy 和 go build 之前设置代理:

RUN go env -w GOPROXY=https://goproxy.cn,direct

这只能视为当前网络环境下的社区绕行方案,不是所有版本都必须采用的官方配置。应把它放到目标标签实际使用的 Go 构建阶段,并保留原有的下载、编译命令。修改后重新构建:

docker compose build
docker compose up -d

如果错误发生在拉取基础镜像、DNS 解析或 HTTPS 证书阶段,修改 GOPROXY 并不能解决。先看错误发生在哪一步,再决定是否需要配置 Docker 构建代理或内部镜像源。

API 连不上或返回 404

按下面四层检查,不要一开始就反复重建。

docker compose ps -a
docker compose config --services
docker compose config
docker compose logs --tail=200

第一层检查容器状态。docker compose ps -a 中出现 Exited、Restarting 或持续变化的状态,都比单独的 Running 更有排查价值。docker compose config 可以查看 Compose 最终采用的端口和环境配置,但输出可能包含密钥,不要直接贴到公开 issue 或日志平台。

第二层检查端口。确认 API 服务确实把宿主机的 3002 映射到了容器对应端口。如果 docker compose config --services 中的服务名不是 api,后面的定向日志命令也要替换成实际名称:

docker compose logs --tail=200 api
docker compose logs --tail=200 playwright-service

第三层检查请求路径。v2.11.162 官方验证路径是 /v2/scrape。本地测试时改用明确的 IPv4 地址,有助于排除 localhost 解析差异:

curl -i -X POST http://127.0.0.1:3002/v2/scrape \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com"}'

如果得到 404,但连接本身已经建立,通常说明请求到达了某个 HTTP 服务,却没有命中当前版本注册的路由。需要检查是否误用了旧 /scrape、是否经过了会改写路径的反向代理,以及当前容器是否真的来自 v2.11.162。

第四层检查服务日志。连接失败通常要查 API 是否监听、端口是否发布以及进程是否退出;404 优先查路径;401、429、5xx 则继续查认证、限流来源、队列和浏览器服务。不要用一个“关闭所有检查”的开关同时解释这些不同状态。

.env 的放置与认证、队列、UI 配置

旧教程常见的误用,是把整个 .env.example 复制到仓库根目录,再把其中几项当作当前版本的固定配置。v2.11.162 的官方快速指南采用的是最小配置:关闭 API 身份验证,使用 PostgreSQL 队列,关闭队列管理 UI,暂不配置 AI 与高级抓取提供商。

配置项 v2.11.162 官方快速指南 排错重点
API 身份验证 关闭 只适用于受信任网络;生产启用不能只改一个环境变量,还需要完整且受支持的认证与数据库设计。
队列 PostgreSQL 不要直接套用旧文章中的 BullMQ/Redis 架构描述;可选的 FoundationDB 也应有明确运维理由再启用。
队列管理 UI 关闭 启用时需要高强度 BULL_AUTH_KEY 和相应网络控制。
AI/高级抓取提供商 暂不配置 只有功能确实依赖某个提供商时,再按目标版本文档添加。

旧版 Windows 教程曾使用下面的复制方式:

cd apps/api
cp .env.example ../../.env
cd ../..

这只能说明旧版本把 .env.example 放在 apps/api,再复制到仓库根目录。正式使用前应先检查当前标签:

git ls-files | grep -E '(^|/)\.env\.example$|(^|/)SELF_HOST\.md$'

旧资料里的 USE_DB_AUTHENTICATION=false、NUM_WORKERS_PER_QUEUE=8 和 BULL_AUTH_KEY=CHANGEME 也只属于当时的版本与部署示例。特别是 CHANGEME 不能视为生产密钥,不要把它原样用于公网环境。

修改环境变量后,至少需要重新创建容器,让 Compose 重新加载配置:

docker compose up -d --force-recreate

随后再检查实际生效值和服务健康状态:

docker compose config
docker compose ps -a

Scrape、Crawl、Search 的使用边界

这三个 API 解决的是不同阶段的问题。已知一个页面时用 Scrape;已知一个站点、需要遍历站内页面时用 Crawl;连来源都不确定,只有一组搜索需求时用 Search。

API 使用场景 结果与后续动作
Scrape 已知单个网页 POST /v2/scrape,官方明确验证可以返回 Markdown。
Crawl 从入口抓取一个站点 初始请求返回任务 ID,再通过目标版本规定的查询接口获取状态和最终数据。
Search 根据查询发现网络来源 用于搜索并获取相关来源;具体路径、请求字段和响应结构应按固定版本文档核验。

最容易混淆的是 Crawl。它不是“提交后立刻把所有页面一次性返回”,而是把长时间抓取拆成任务。调用方需要保存任务 ID,持续查询任务状态,直到任务完成后再处理结果。

当前官方自托管指南明确给出的可复现请求是 /v2/scrape。Crawl 和 Search 的路径与字段应从官方文档索引核对:

curl -L https://docs.firecrawl.dev/llms.txt

找到 v2.11.162 对应的 Crawl、Search 页面后,再把请求中的服务地址换成本机 http://localhost:3002,其余路径和字段保持官方版本定义。旧教程中的 /crawl/{task_id} 只能作为版本线索,不能直接当作当前版本的通用路径。

另外,“同一套 Compose 提供这些能力”不等于“所有提供商已经配置好”。官方快速指南默认没有配置 AI 与高级抓取提供商;某个接口如果依赖外部提供商,就必须补齐相应配置,否则会出现功能不可用、超时或结果为空。

Crawl 任务状态与结果

Crawl 的调用顺序是:提交抓取请求,保存返回的任务 ID,轮询任务状态,确认完成后读取最终数据。初始请求返回任务 ID,只表示任务已经进入系统,不表示页面已经抓完。

调用方至少要处理三种状态:任务仍在进行、任务完成、任务失败。轮询间隔和客户端超时由接入方控制,不能把一次提交请求的响应误当作 Crawl 的最终结果。旧资料曾给出默认最大抓取页数为 10、最大深度为 2,但这属于旧版本口径,v2.11.162 是否沿用必须核对目标版本参数,不能直接固化到业务代码中。

任务 ID 最好由调用方保存到自己的存储中。当前官方快速指南没有提供持久化存储方案;如果数据库和队列数据只存在于临时容器中,容器重建后不能据此认定任务状态仍然存在。

动态页面为空、401、429 或任务卡住

先把 API 连通性、认证层、目标站点、浏览器服务、队列和任务状态分开。不同状态码可能来自完全不同的层,混在一起看通常会得到错误的“万能修复”。

docker compose ps -a
docker compose logs --tail=300
现象 优先检查
JavaScript 页面只有空壳或缺少正文 固定版本的 Playwright 服务、渲染配置及相关提供商。旧资料对本地动态页支持存在差异,有的强调浏览器服务,有的明确提示本地部署不支持,因此必须用目标标签实测,不能照搬旧开关。
401 Unauthorized 容器是否真正加载了修改后的 .env、Compose 是否重新创建、是否经过额外认证代理。官方快速指南默认关闭认证,所以基线环境突然出现 401,通常说明还有未识别出的认证层。
429 Rate Limited 先看响应正文和日志,确认是目标网站、外部提供商还是其他层返回的限流,再查该版本支持的限制配置,不存在通用的“关闭限流”开关。
Crawl 长时间没有结果 任务 ID、队列状态、worker 与 Playwright 服务日志;同时核对是否因为页数、深度或站点响应速度导致任务仍在运行。

如果 Scrape 对普通静态页面成功,而只有动态页面为空,问题通常不在基础 API 路由,而在渲染链路。如果所有请求都返回 401,则应先处理认证,而不是继续调整 Playwright。429 同样要先定位响应来源;盲目重试可能进一步消耗配额。

本地部署转入生产前需要补齐的能力

官方快速指南面向受信任网络,不包含 API 身份验证、持久化存储、TLS、高可用,也不具备 Firecrawl Cloud 的全部功能。这里的“缺少”指的是快速指南没有替你完成这些生产设计,不代表自托管架构永远无法实现它们。

生产前至少需要逐项处理:

  • API 身份验证、密钥保存与定期轮换,不能只依赖“旧环境变量名能打开”这个假设。
  • 数据库和队列的持久化、备份与恢复演练,并验证容器重建后的任务状态。
  • TLS、访问控制与队列管理 UI 的网络隔离;启用 UI 时使用高强度密钥。
  • 高可用部署,明确哪些服务允许短暂中断,失败任务由谁重试。
  • 监控、日志、告警以及容量趋势,不能只靠人工执行 docker compose ps。
  • 升级、回滚、密钥轮换、故障恢复和事件响应流程。
  • 目标网站的出站请求,以及代理、解析器和 AI 提供商带来的额外数据流与隐私边界。

旧资料特别提醒过默认自托管环境缺少数据库持久化,容器重建后队列状态可能丢失。这与当前快速指南“不包含持久化存储”的边界一致,但具体采用了哪些 volume、数据库和迁移方式,仍应以 v2.11.162 的 Compose 与自托管说明为准。

自托管与 Firecrawl Cloud 的选择

选择标准可以落到运维责任上,而不是只看“免费”或“开源”两个字。

需求 更合适的选择 原因
必须掌控源代码或基础设施 自托管 可以自己管理运行环境,但升级、安全、存储、监控和恢复也由自己负责。
希望尽快获得受支持的生产路径 Firecrawl Cloud 官方建议在需要最快进入生产的受支持路径时选择 Cloud。
只是本地评估、验证抓取流程 自托管 固定 v2.11.162,用 Scrape 完成最小验收即可,不必一开始配置完整生产架构。
需要与 Cloud 完全一致的功能范围 先逐项核对版本差异 开源版自托管并不自动包含 Firecrawl Cloud 的全部功能。

如果选择自托管,升级前必须重新阅读目标版本的 docker-compose.yaml 和自托管说明,不能把旧版 .env、服务名或 API 路径继续带过去。 目前仍有两个明确限制:官方尚未公布经过验证的最低主机配置;GitHub 热点所强调的广泛 provider 接入,也不等于本地 Compose 已经默认配置了全部提供商。

因此,本地验证可以先用固定版本和 /v2/scrape 跑通;真正面向公网时,除非团队已经具备数据库、队列、TLS、监控和恢复能力,否则应优先把 Firecrawl Cloud 作为生产候选,而不是把开发用 Compose 原样暴露出去。

© 版权声明
THE END
喜欢就支持一下吧
点赞0 分享
评论 抢沙发

请登录后发表评论

    暂无评论内容