自托管 Firecrawl

当您需要掌控源代码或基础设施时，可使用 Docker Compose 自托管 Firecrawl。本指南固定使用版本 v2.11.162，在 http://localhost:3002 启动 API，并验证 POST /v2/scrape 成功返回 Markdown 响应。

此面向受信任网络的 Quickstart 会禁用 API 身份验证，并非生产环境架构。它不包含持久化存储、TLS、高可用性，也不具备 Firecrawl Cloud 的全部功能。

选择自托管或使用 Firecrawl Cloud

在以下情况下自托管

您希望掌控源代码或基础设施。 本指南将帮助您在自己的机器上运行 API 及其配套服务。
您熟悉整套技术栈的运维。 您需要负责升级、安全、存储、监控和恢复。
您希望在自身环境中验证 Firecrawl。 请先在此处完成基础配置，然后在生产前准备中设计相应的控制措施。

如果您希望无需自行运行基础设施即可开始抓取，请选择 Firecrawl Cloud。有关功能差异，请参见开源版与 Cloud。 我们的建议： 只有当源代码访问权限或基础设施控制带来的价值值得额外运维工作时，才选择自行托管。如果您希望通过最快的受支持路径投入生产，请从 Firecrawl Cloud 开始。

自托管需要承担的事项

升级、密钥、存储、监控、恢复和事件响应均由你负责。
抓取仍会向目标网站发送出站请求。可选的代理、解析或 AI 提供商会带来额外的数据流。
本指南刻意简化首次运行。先让一次抓取成功，再逐项调整配置。
这些命令固定使用 v2.11.162。其他版本可能采用不同的 Compose 约定。

使用 Docker Compose 自托管 Firecrawl

采用以下默认设置

版本：Firecrawl v2.11.162。 先固定代码和配置。查看目标版本的 docker-compose.yaml 和自托管说明后再升级。
API 身份验证：此次本地运行关闭。 仅在具备完整且受支持的身份验证和数据库设计时启用；仅设置一个环境变量并不够。
队列：PostgreSQL。 除非你有意运维可选的 FoundationDB 后端，否则请保持此设置。
队列管理 UI：关闭。 仅在设置高强度 BULL_AUTH_KEY 并采取网络控制措施后启用。
AI 和高级抓取提供商：未配置。 当所需功能依赖某个提供商时再添加。

首次运行尽量保持简单：先让一次抓取正常运行，再按用例需要添加功能。

前置条件

开始前，请安装：

Git
Docker Engine 或 Docker Desktop
Docker Compose v2 (通过 docker compose 调用)
用于发送验证请求的 curl

请确保端口 3002 可用，并且 Docker 有足够资源来构建和运行多个服务。Firecrawl 尚未公布此技术栈经过验证的最低主机配置。

克隆经验证的版本

本指南已基于 Firecrawl v2.11.162 验证。请检出该特定版本，以确保代码、命令和配置保持同步：

git clone https://github.com/firecrawl/firecrawl.git
cd firecrawl
git checkout v2.11.162

想使用其他版本？复用这些值前，请先查看该版本的 docker-compose.yaml 和自托管说明。

配置评估环境部署

在仓库根目录创建最简可用的 .env 文件：

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

请在启动整套服务前更改 PostgreSQL 密码，并且不要提交 .env。对于 v2.11.162，请保留 POSTGRES_DB=postgres，因为内置的 pg_cron 配置针对该数据库。Compose 会将这些值传递给 API 和 PostgreSQL 服务。

apps/api/.env.example 用于 API 开发，并非可直接用于 Compose 的配置文件。首次运行会禁用数据库身份验证，因此请求无需提供 API 密钥或 Authorization 请求头。

请勿设置 NUQ_BACKEND 和 BULL_AUTH_KEY。你将使用 PostgreSQL 队列，无需运行队列管理 UI——这样首次抓取所需的组件更少。

构建并启动 Firecrawl

构建已检出的源代码，并在后台启动所有组件：

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

此基线中出现未设置可选变量的警告属于预期情况。docker compose ps --all 应显示 API 和支持服务正在运行，而一次性初始化服务已完成。如果服务仍在启动，请稍候片刻。

检查 API 是否可访问

首先，确保 API 能响应 HTTP 请求：

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

预期响应：

{"status":"ok"}

这只是心跳检测，并非端到端测试。它不会检查 Redis、 PostgreSQL、RabbitMQ、Playwright、worker 或出站网络访问。在将该部署视为可用之前，请先运行以下抓取操作。

运行功能冒烟测试

现在测试关键路径：执行一次真实抓取。请求超时以毫秒为单位；curl’s 客户端超时以秒为单位，且略长一些：

curl \
  --fail-with-body \
  --silent \
  --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
  }'

成功的响应如下：

{
  "success": true,
  "data": {
    "markdown": "...",
    "metadata": {
      "statusCode": 200
    }
  }
}

这会同时检查 API、抓取流水线、一条抓取引擎路径以及出站访问。具体元数据可能因目标响应而异。如果返回这些成功字段，说明 Firecrawl 已在您的基础设施上端到端正常运行。保留这一基线，然后选择下一步要添加的内容。

自托管功能支持

首次抓取已成功。只有在确有需求时再添加相应功能，而不是因为它存在就启用：

如果你需要	建议
核心抓取、crawl、map 和 search 路由	保持默认技术栈。已包含 Fetch 和 Playwright 处理。
基于 LLM 的提取或 formats	连接兼容 OpenAI 的提供商或 Ollama，然后单独测试该流程。
Fire-engine 或其高级反爬行为	单独运行并配置该服务；默认技术栈不包含它。
截图或页面 actions	默认技术栈不支持。Fetch 和 Playwright 均报告不支持；两者都需要 Fire-engine。
Agent、Browser、interact、feedback，或专用的产品、菜单、音频和视频 formats	使用 Firecrawl Cloud，或确认特定功能所需的外部服务要求。

如需更全面的产品对比，请参见开源版与 Cloud。如需针对特定版本进行配置，请使用固定版本的 docker-compose.yaml 作为配套参考。

上线前

Compose 可帮助你快速完成首次部署。要将 API 置于受信任网络之外用于生产环境，还需做出几项明确决策：

**如果数据必须在服务替换后保留，**请为 PostgreSQL、Redis 和 RabbitMQ 添加持久化存储，并制定和测试备份与恢复流程。提供的 Compose 文件未添加这些数据卷。
**如果用户或不受信任的网络可以访问 API，**请采用受支持的身份验证方案、网络访问控制，并在反向代理或入口层配置 TLS。请勿将这个未经身份验证的基础配置暴露在公网。
**如果对可用性或容量有要求，**请设定正常运行时间目标、监控、资源规格、扩缩容触发条件，以及升级和回滚流程。Compose 中的限制并非经验证的最低要求。
**如果数据存储位置或合规性至关重要，**请在启用前确认请求会发送至哪些目标网站，以及每个可选的 AI、代理或解析提供商。
**如果必须集中管理密钥，**请将数据库密码从 .env 移至平台的密钥管理系统。

这些都是基础设施层面的决策。没有任何一个 .env 开关能让该技术栈满足生产环境要求。

下一步

仍在评估？ 请将 API 保持在受信任的网络中，并在完成后运行 docker compose down。
要添加开源功能？ 通过自托管功能支持查找所需的提供商或服务，然后单独测试该方案。
要修改 Firecrawl 代码？ 请参阅本地运行，设置贡献者开发环境。
要连接客户端？ 将 Firecrawl CLI 或本地 MCP 服务器配置为使用已验证的 API URL。
要迁移到 Kubernetes？ 请先参考 SELF_HOST.md 中链接的带版本 Kubernetes 或 Helm 文档，然后针对你的平台明确做出上述生产环境决策。
需要托管基础设施或仅限 Cloud 的功能？ 请比较开源版与 Cloud。
要投入生产？ 请在公开 API 前完成生产前准备中的每项决策。

故障排查

你正在绕过身份验证

如果在 USE_DB_AUTHENTICATION=false 时看到此警告，说明这是预期的首次运行流程。请求会使用 self-hosted 身份，无需 API 密钥。如果该 API 可从不受信任的网络访问，请停止操作，并按照生产环境前中的说明添加控制措施。

Docker 容器无法启动

如果任何长期运行的服务退出，请检查容器状态和最新日志：

docker compose ps --all
docker compose logs --tail=200

如果源代码版本不同，请检出 v2.11.162，或使用该版本的配置。
如果构建过程或容器受资源限制，请增加 Docker 的 CPU、内存或磁盘容量。
如果 PostgreSQL 启动失败，请检查 .env 语法，保持 POSTGRES_DB=postgres，并确保用户名和密码一致。

Redis 连接问题

如果容器无法连接到 Redis，请使用 Compose 服务地址 redis://redis:6379。localhost 指向容器自身，而不是 Redis 服务。

docker compose ps redis
docker compose logs --tail=100 redis

如果您设置了 REDIS_URL 或 REDIS_RATE_LIMIT_URL，请移除覆盖配置以恢复默认值，或使用可在 Compose 网络内部解析的地址。

API 端点无响应

如果端口 3002 无响应，请检查 API 容器及其日志：

docker compose ps api
docker compose logs --tail=200 api

如果其他进程占用了端口 3002，请停止该进程，或同步修改发布的端口。初次启动时，只有在 API 容器显示为正在运行后再重试。如果 /v0/health/readiness 请求成功，但 /v2/scrape 失败，请检查 API 和 Playwright 日志，因为可达性端点不会验证这些依赖项：

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

抓取请求超时

如果抓取操作超时，请确认部署环境可以访问 https://example.com，且 API 和 Playwright 服务正在运行。请将 curl 的 --max-time 设置为长于请求正文中的 timeout，以便 API 能返回自身的超时响应。

快速上手

核心端点

更多

快速入门

开发者指南

Webhooks

使用场景

其他

参与贡献

自托管 Firecrawl

选择自托管或使用 Firecrawl Cloud

在以下情况下自托管

自托管需要承担的事项

使用 Docker Compose 自托管 Firecrawl

采用以下默认设置

前置条件

克隆经验证的版本

配置评估环境部署

构建并启动 Firecrawl

检查 API 是否可访问

运行功能冒烟测试

自托管功能支持

上线前

下一步

故障排查

你正在绕过身份验证

Docker 容器无法启动

Redis 连接问题

API 端点无响应

抓取请求超时

​选择自托管或使用 Firecrawl Cloud

​在以下情况下自托管

​自托管需要承担的事项

​使用 Docker Compose 自托管 Firecrawl

​采用以下默认设置

​前置条件

​克隆经验证的版本

​配置评估环境部署

​构建并启动 Firecrawl

​检查 API 是否可访问

​运行功能冒烟测试

​自托管功能支持

​上线前

​下一步

​故障排查

​你正在绕过身份验证

​Docker 容器无法启动

​Redis 连接问题

​API 端点无响应

​抓取请求超时

选择自托管或使用 Firecrawl Cloud

在以下情况下自托管

自托管需要承担的事项

使用 Docker Compose 自托管 Firecrawl

采用以下默认设置

前置条件

克隆经验证的版本

配置评估环境部署

构建并启动 Firecrawl

检查 API 是否可访问

运行功能冒烟测试

自托管功能支持

上线前

下一步

故障排查

你正在绕过身份验证

Docker 容器无法启动

Redis 连接问题

API 端点无响应

抓取请求超时