跳转到主要内容

​
想要贡献？

欢迎来到 Firecrawl 🔥！以下是一些在本地拉取并运行项目的说明，方便你自行运行并参与贡献。 如果你要贡献代码，请注意流程与其他开源仓库类似：fork Firecrawl、做改动、跑测试、提交 PR。 如果你有任何问题或需要上手帮助，欢迎加入我们的 Discord 社区（链接）获取更多信息，或在 GitHub 提交 issue（链接）！

​
自托管 Firecrawl

有关本地运行的说明，请参阅 SELF_HOST.md。

​
为什么？

对于要求数据必须留在受控环境内、具有严格安全策略的组织而言，自托管 Firecrawl 尤其有益。以下是考虑自托管的主要原因：
  • 更强的安全性与合规性： 通过自托管，您可确保所有数据的处理与处理流程符合内外部合规要求，并将敏感信息留在自有的安全基础设施中。请注意，Firecrawl 是 Mendable 的产品，并通过了 SOC 2 Type II 认证，这意味着该平台在数据安全管理方面遵循严苛的行业标准。
  • 可定制的服务： 自托管使您能够按需定制服务（例如 Playwright 服务），以满足特定需求，或处理标准云服务可能不支持的用例。
  • 学习与社区贡献： 通过搭建并维护自有实例，您将更深入理解 Firecrawl 的工作原理，也更有助于为项目做出更有价值的贡献。

​
注意事项

不过，需要留意一些限制和额外责任：
  1. 对 Fire-engine 的访问受限： 目前，自托管的 Firecrawl 实例无法使用 Fire-engine，其包含处理 IP 封禁、机器人检测等高级功能。这意味着虽然你可以完成基础抓取任务，但更复杂的场景可能需要额外配置，或可能无法支持。
  2. 需要手动配置： 如果你需要使用超出基础 fetch 和 Playwright 选项的抓取方法，则需在 .env 文件中手动配置。这要求对相关技术有更深入的理解，并可能增加设置时间。
自托管 Firecrawl 非常适合需要对抓取与数据处理环境实现完全掌控的用户，但相应地需要投入更多的维护与配置工作。

​
步骤

  1. 首先安装依赖
  1. 设置环境变量
在项目根目录创建一个 .env 文件，你可以复制 apps/api/.env.example 中的模板 起步时，我们不配置身份验证，也不启用任何可选的子服务（PDF 解析、JS 阻止支持、AI 功能） 
# .env

# ===== 必填环境变量 ======
NUM_WORKERS_PER_QUEUE=8 
PORT=3002
HOST=0.0.0.0

# 对于使用 Docker 的自托管，使用 redis://redis:6379；本地运行使用 redis://localhost:6379
REDIS_URL=redis://redis:6379

# 对于使用 Docker 的自托管，使用 redis://redis:6379；本地运行使用 redis://localhost:6379
REDIS_RATE_LIMIT_URL=redis://redis:6379 
PLAYWRIGHT_MICROSERVICE_URL=http://playwright-service:3000/html

## 如需开启数据库身份验证，你需要配置 Supabase。
USE_DB_AUTHENTICATION=false

# ===== 可选环境变量 ======

# Supabase 配置（用于支持数据库身份验证、增强型日志等）
SUPABASE_ANON_TOKEN= 
SUPABASE_URL= 
SUPABASE_SERVICE_TOKEN=

# 其他可选项
# 若已启用身份验证并希望使用真实 API Key 进行测试，请设置此项
TEST_API_KEY=
# 如需测试抓取的速率限制，请设置此项
RATE_LIMIT_TEST_API_KEY_SCRAPE=
# 如需测试爬取的速率限制，请设置此项
RATE_LIMIT_TEST_API_KEY_CRAWL=
# 为依赖 LLM 的功能提供支持（如图片替代文本生成等）
OPENAI_API_KEY=
BULL_AUTH_KEY=@
# 若使用 logtail 配置基础日志，请设置此项
LOGTAIL_KEY=
# 若你有 LlamaParse 的 Key 并希望用于解析 PDF，请设置此项
LLAMAPARSE_API_KEY=
# 如需发送 Slack 服务器健康状态消息，请设置此项
SLACK_WEBHOOK_URL=
# 如需发送 PostHog 事件（如作业日志），请设置此项
POSTHOG_API_KEY=
# 如需发送 PostHog 事件（如作业日志），请设置此项
POSTHOG_HOST=

# 如需使用 Fire Engine 封闭测试版，请设置此项
FIRE_ENGINE_BETA_URL=

# Playwright 的代理设置（或者你也可以使用如 Oxylabs 之类的代理服务，它会在每次请求时为你轮换 IP）
PROXY_SERVER=
PROXY_USERNAME=
PROXY_PASSWORD=
# 如需阻止媒体请求以节省代理带宽，请设置此项
BLOCK_MEDIA=

# 使用 Firecrawl 自托管版本时，将其设置为你的 webhook 的 URL
SELF_HOSTED_WEBHOOK_URL=

# Resend 的事务型邮件 API Key
RESEND_API_KEY=

# LOGGING_LEVEL 用于控制系统输出日志的详细程度。
# 可用级别：
# NONE - 不输出任何日志。
# ERROR - 记录表明某个操作失败的错误消息。
# WARN - 记录可能有风险但不一定是错误的情况。
# INFO - 记录体现应用进度的信息性消息。
# DEBUG - 记录系统流程的详细信息，主要用于调试。
# TRACE - 记录比 DEBUG 更加详细的信息。
# 将 LOGGING_LEVEL 设置为上述选项之一以控制日志输出。
LOGGING_LEVEL=INFO
  1. (可选) 使用 TypeScript Playwright 服务运行
    • 更新 docker-compose.yml 文件以更改 Playwright 服务： 
          build: apps/playwright-service
      改为 
          build: apps/playwright-service-ts
    • 在你的 .env 文件中设置 PLAYWRIGHT_MICROSERVICE_URL： 
      PLAYWRIGHT_MICROSERVICE_URL=http://localhost:3000/scrape
    • 别忘了按需在 .env 文件中设置代理服务器。
  2. 构建并运行 Docker 容器： 
    docker compose build
docker compose up
这将启动一个本地 Firecrawl 实例，可通过 http://localhost:3002 访问。 你应该能够在 http://localhost:3002/admin/@/queues 查看 Bull Queue Manager 界面。
  1. (可选) 测试 API
如果你想测试 /crawl 端点，可以运行以下命令： 
  curl -X POST http://localhost:3002/v2/crawl \
      -H 'Content-Type: application/json' \
      -d '{
        "url": "https://docs.firecrawl.dev"
      }'

​
疑难解答

本节提供在设置或运行自托管版 Firecrawl 实例时可能遇到的常见问题的解决方案。

​
未配置 Supabase 客户端

现象： 
[YYYY-MM-DDTHH:MM:SS.SSSz]ERROR - 在未配置 Supabase 客户端的情况下尝试访问该客户端。
[YYYY-MM-DDTHH:MM:SS.SSSz]ERROR - 插入抓取事件时出错：Error: 未配置 Supabase 客户端。
解释： 出现此错误是因为 Supabase 客户端尚未完成配置。你仍然可以正常进行抓取和爬取。目前，自托管实例不支持配置 Supabase。

​
你正在绕过身份验证

现象： 
[YYYY-MM-DDTHH:MM:SS.SSSz]WARN - 你正在跳过身份验证
解释： 出现此错误是因为尚未完成 Supabase 客户端的设置。你仍然可以正常执行抓取和爬取操作。目前，自托管实例不支持配置 Supabase。

​
Docker 容器无法启动

现象： Docker 容器意外退出或启动失败。 解决方案： 使用以下命令查看 Docker 日志中的错误信息： 
docker logs [容器名称]
  • 确保在 .env 文件中正确设置所有必需的环境变量。
  • 确认 docker-compose.yml 中定义的所有 Docker 服务均已正确配置，且所需镜像已就绪可用。

​
与 Redis 的连接问题

症状： 连接 Redis 时出现错误，如超时或“Connection refused”。 解决方案：
  • 确认 Redis 服务已在 Docker 环境中正常运行。
  • 核对 .env 文件中的 REDIS_URL 和 REDIS_RATE_LIMIT_URL 是否指向正确的 Redis 实例。
  • 检查网络设置和防火墙规则，是否阻止了对 Redis 端口的连接。

​
API 端点无响应

现象： 对 Firecrawl 实例的 API 请求超时或无返回。 解决方案：
  • 检查 Docker 容器状态，确保 Firecrawl 服务正在运行。
  • 核对 .env 文件中的 PORT 和 HOST 配置是否正确，并确认没有其他服务占用同一端口。
  • 检查网络配置，确保发起 API 请求的客户端可访问该主机。
通过排查以上常见问题，可使自托管的 Firecrawl 实例部署与运行更顺畅。

​
在 Kubernetes 集群上安装 Firecrawl（简化版）

请阅读 examples/kubernetes-cluster-install/README.md，了解在 Kubernetes 集群上安装 Firecrawl 的步骤。
⌘I