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 原样暴露出去。












暂无评论内容