lesson-07

⏱ Est. reading time: 5 min Updated on 5/14/2026

7.1 为什么要自建 Firecrawl？

虽然 Firecrawl 提供了便捷的云端 API（500次/月免费额度），但在严肃的数据获取场景下，自托管（Self-hosting）是唯一合理的选择：

  1. 突破请求限制：自建版本完全免费，无请求次数限制。
  2. 数据隐私安全：敏感业务数据不会经过第三方服务器。
  3. 更强的控制力：可以自定义底层的 Playwright 设置，或者像本教程一样，将其流量强行路由至你自己的 WARP 代理池。

7.2 Firecrawl 的 Docker 架构

Firecrawl 不是单一的服务，它是一个依赖多个组件的微服务架构。理解它的内部结构有助于我们后续注入代理配置。

graph TD
    User[发起 API 请求] --> API[firecrawl-api (Node.js/Express)]
    API -->|缓存 / 队列任务| Redis[(Redis)]
    API -->|直接抓取 HTML| Target[目标网站]
    
    API -->|遇到 JS 渲染任务
发送到无头浏览器| PW[playwright-service]
    
    PW -->|驱动浏览器实例| Browser((Chromium))
    Browser -->|抓取动态内容| Target
    
    subgraph Docker Compose 网络
        API
        Redis
        PW
    end

如上图所示，当抓取静态页面时，firecrawl-api 直接发出 HTTP 请求；当开启了 formats: ["screenshot"] 或遇到需要 JS 渲染的 SPA 页面时，任务会被移交给 playwright-service。

这意味着，如果我们想让 Firecrawl 完全穿透反爬系统，必须同时为这两个容器配置代理！

7.3 基础安装：拉取与启动

步骤 1：克隆仓库

git clone https://github.com/mendableai/firecrawl.git
cd firecrawl

步骤 2：配置环境变量

复制环境配置文件。默认的配置已经足以让服务在本地跑起来。

cp .env.example .env

注意：默认的自建版本不需要 API Key（在 .env 中 USE_DB_AUTHENTICATION=true 是被注释掉的）。所有发往 localhost:3002 的请求默认放行。

步骤 3：一键启动

由于项目包含多个微服务，官方使用 Docker Compose 进行编排管理：

docker compose up -d

第一次启动需要拉取镜像并编译 Playwright 服务，可能需要 5-10 分钟。

步骤 4：验证服务就绪

等待容器启动完毕后，检查 API 健康状态：

curl http://localhost:3002/v1/crawl

如果返回类似 {"success":false,"error":"Invalid URL"}，说明服务已成功启动并在监听请求。

7.4 常见的启动问题

现象 排查方向 解决方案
docker compose 命令找不到 Docker 未正确安装 安装 Docker Desktop（macOS/Windows）或安装 docker-ce (Linux)
端口冲突：Bind for 0.0.0.0:3002 failed 3002 或 6379(Redis) 被占用 停止占用端口的服务，或修改 docker-compose.yaml 中的外部映射端口
容器不断重启（Exit 1） 可能是 .env 缺失或权限问题 docker compose logs firecrawl-api 查看具体报错

7.5 课后问题

  1. 为什么 Firecrawl 需要一个独立的 playwright-service 容器？它解决了什么问题？
  2. 如果你的电脑上已经跑了一个 Redis，启动 Firecrawl 时会发生什么？如何解决？
  3. 在本地自建环境中，为什么通常不需要配置 FIRECRAWL_API_KEY？