Firecrawl 自托管部署：3 步启动抓取服务并验证

Firecrawl 是面向 AI 应用的网页抓取服务，可把网页、文档和动态页面转换成 Markdown 或结构化数据。

Firecrawl 的自托管指南在 2026 年 10 月 30 日更新，并固定使用 v2.11.162；现在值得先跑通本地实例，是因为只有通过真实抓取，才能同时确认 API、任务队列、浏览器抓取链路和外部网络都可用。

开始前：准备 3 项条件

1. 安装 Docker Compose v2，在终端运行 docker compose version，确认命令能正常输出版本。
2. 预留足够 CPU、内存和磁盘空间；官方指南明确指出，完整运行需要构建多个服务，3002 端口也要可用。
3. 准备 curl 和支持 Bash 的终端。Windows 可在 Git Bash 或 WSL 中执行后面的命令。

这次采用自托管方式。官方 Quickstart 面向受信任网络，v2.11.162 首次运行会禁用 API 身份验证，因此验证请求不需要 API 密钥或 Authorization 请求头。它适合第一次跑通，不等于已经具备生产环境所需的认证和数据库设计。

第 1 步：创建最小环境配置

进入 Firecrawl 源代码仓库根目录，创建 .env 文件：

cat > .env <<'EOF'
USE_DB_AUTHENTICATION=false
POSTGRES_USER=postgres
POSTGRES_PASSWORD=replace-with-at-least-32-random-characters
POSTGRES_DB=postgres
EOF

这里的密码必须替换为至少 32 个随机字符。POSTGRES_DB=postgres 也要保留，因为该版本内置的 pg_cron 配置针对这个数据库名。

不要直接使用 apps/api/.env.example 作为 Docker Compose 配置：官方指南明确说明，该文件面向 API 开发，并非可直接用于 Compose 的配置文件。首次运行使用 PostgreSQL 队列，不必额外启动队列管理界面。

第 2 步：构建并启动全部服务

在仓库根目录执行：

docker compose up --build -d
docker compose ps --all

第一条命令会构建检出代码并启动全部组件，耗时取决于机器性能和镜像下载情况。第二条命令用于检查容器状态。

成功时，docker compose ps --all 应显示 API 和支持服务正在运行，而一次性初始化服务已经完成。此时端口监听和容器存在只代表“服务启动了”，还不能证明网页抓取链路已经打通。

官方文档提到，首次构建时出现未设置可选变量的警告属于预期情况。这里的处理方式不是逐项补齐所有生产变量，而是先完成一次真实抓取；否则很容易在核心链路尚未验证时，把时间耗在暂时用不到的队列、认证或监控配置上。

第 3 步：依次做健康检查和真实抓取

先检查 API 是否能够响应 HTTP 请求：

curl 
  --fail 
  --silent 
  --show-error 
  --max-time 5 
  http://localhost:3002/v0/health/readiness

预期响应：

{"status":"ok"}

但这个结果只是心跳检查，不检查 Redis、PostgreSQL、RabbitMQ、Playwright、worker 或外部网络访问。因此，看到 {"status":"ok"} 后不能直接宣布部署完成，还要执行下面的功能冒烟测试：

curl 
  --fail-with-body 
  --show-error 
  --max-time 75 
  -X POST 
  http://localhost:3002/v2/scrape 
  -H 'Content-Type: application/json' 
  -d '{
    "url": "https://example.com",
    "formats": ["markdown"],
    "timeout": 60000
  }'

这里的 timeout 单位是毫秒，所以设为 60000；curl 的 --max-time 单位是秒，因此设为 75，比服务端超时略长。

成功响应应包含以下关键字段：

{
  "success": true,
  "data": {
    "markdown": "..."
  }
}

目标网页的具体元数据可能变化，不必逐字固定。只要 success 为 true，并且 data.markdown 中出现 example.com 页面的正文内容，就说明 API、抓取管线、至少一条抓取引擎路径和外部网络访问已经一起工作。

选对验证入口：不要把能启动当成能使用

自托管文档和 Firecrawl 验证参考都强调：不要停在“代码能编译”或“健康检查通过”。官方验证文档建议，用最小真实请求覆盖认证、网络和 SDK 连接，再确认结果确实进入应用路径。

检查位置	能证明什么	不能证明什么
docker compose ps --all	容器已经创建并处于运行或退出状态	API 能抓取外部网页
/v0/health/readiness	本地 API 能响应请求	Redis、PostgreSQL、RabbitMQ、Playwright、worker 和外网正常
POST /v2/scrape	真实抓取链路能够返回 Markdown	后续业务代码已正确处理返回结果

这也是采用“心跳检查 + 功能冒烟测试”两步的原因。前者排查本地服务是否在线，后者验证用户真正依赖的能力。两者不能互相替代。

常见卡点：看到什么就改什么

健康检查不是 {"status":"ok"}

官方给出的预期响应就是 {"status":"ok"}。如果请求失败，先用 docker compose ps --all 确认 API 与支持服务是否仍在运行，再执行：

docker compose ps --all

如果容器异常退出，再查看服务日志：

docker compose logs

不要因为健康接口异常就直接重装浏览器或数据库；先从日志确认具体服务是否启动失败。若健康检查通过但真实抓取失败，则故障范围已经缩小到认证配置、环境变量加载、基础 URL、任务队列、浏览器依赖或外部网络中的至少一项。

抓到页面，但没有 Markdown

检查请求体中是否同时包含目标地址和输出格式：

{
  "url": "https://example.com",
  "formats": ["markdown"],
  "timeout": 60000
}

如果使用 SDK，还要确认项目确实加载了凭据，并指向当前部署的 http://localhost:3002。官方验证参考把“认证或基础 URL 配错”列为首次验证时需要排除的问题。

重复读取同一个网页，选错工具

官方 Firecrawl MCP Server 将不同场景拆成不同工具：已知 URL 要正文时用 firecrawl_scrape；只知道网站、尚未知道具体页面时先用 firecrawl_map 发现 URL；已知站点范围并要批量抓取时才用 firecrawl_crawl。

以关键词开始、没有目标 URL 时，才用 firecrawl_search。官方仓库特别提醒：搜索结果默认带摘要；若在搜索调用中加入 scrapeOptions，系统会抓取每个结果页，而且每个页面都按 scrape 计费。因此只想看少量搜索结果时，不要顺手打开全文抓取。

接入 MCP 客户端：让 AI 调用抓取能力

本地 API 跑通后，再把官方 MCP Server 接入支持 Model Context Protocol 的客户端。MCP 是一种让 AI 客户端调用外部工具的协议；Firecrawl 官方服务器可提供搜索、抓取、站点映射、批量爬取、文档解析、浏览器交互和页面监控等能力。

选择工具时按任务边界来：

当前任务	首选工具	关键限制
已知一个 URL，要正文或 JSON	firecrawl_scrape	可指定 Markdown 或自定义结构
不知道网站有哪些 URL	firecrawl_map	只发现 URL，不负责批量读取正文
要抓同一站点多个页面	firecrawl_crawl	用 limit、includePaths、excludePaths 或 maxDiscoveryDepth 限定范围
关键词起手的资料检索	firecrawl_search	全文抓取会按页面增加 scrape 消耗
页面必须先点击、输入或填写	firecrawl_interact	可从新 URL 开始，也可沿用已有 scrapeId

首次接入时仍建议只请求一个已知 URL。先确认客户端收到 Markdown，再逐步加入搜索、爬取或交互；否则一旦结果为空，很难判断是 MCP 客户端、凭据、基础 URL，还是目标网站的问题。

怎么算真正成功

满足下面四项，才算完成第一次跑通：

1. docker compose ps --all 显示 API 和支持服务已启动。
2. 健康检查返回 {"status":"ok"}。
3. POST /v2/scrape 返回 "success": true。
4. data.markdown 中出现目标网页的实际正文。

只满足前两项，说明本地 API 在线；只满足第三项但没有正文，仍需检查返回结构；第四项成立，才代表官方文档所说的端到端抓取已经跑通。

官方文档与仓库入口

• Firecrawl 官方自托管指南：包含 v2.11.162 的环境配置、启动、健康检查和真实抓取命令。
• Firecrawl 自托管指南中文版：提供中文操作说明和首次运行限制。
• Firecrawl MCP Server 官方仓库：包含工具选择、计费边界、MCP 客户端接入和自托管说明。
• Firecrawl 验证参考：强调用真实请求验证认证、网络和 SDK 连接，而不是只看代码能否编译。