第 3 课 — 本地自建 Firecrawl (Self-Hosting)

当你的抓取量巨大或有敏感数据需求时，本地自建是最佳选择。

3.1 方案 A：Docker 部署 (推荐)

这是最简单、最稳定的方式，所有依赖均在容器内运行。

1. 克隆仓库与配置

git clone https://github.com/firecrawl/firecrawl.git
cd firecrawl
cp apps/api/.env.example apps/api/.env

2. 最小化环境变量配置

编辑 apps/api/.env，确保以下项正确：

• USE_DB_AUTHENTICATION=false (本地使用通常关闭认证)
• PORT=3002

3. 启动服务

docker compose up

这会启动 Redis、PostgreSQL、API Server 和 Workers。访问 http://localhost:3002/test 看到 "Hello, world!" 即成功。

---

3.2 方案 B：源码编译部署

如果你需要修改代码或进行深度调试，可以使用此方式。

前置依赖：

• Node.js 18+ & pnpm
• Redis 7+ (任务队列)
• PostgreSQL 15+ (数据存储)

核心步骤：

1. 数据库初始化：使用 apps/nuq-postgres 目录下的 Dockerfile 构建并启动含 Schema 的数据库。
2. 安装依赖：在根目录执行 pnpm install。
3. 环境变量：同 Docker 方式，但需将 REDIS_URL 和 DATABASE_URL 指向本地实例。
4. 启动：在 apps/api 目录下执行 pnpm start。

---

3.3 配置本地 MCP 连接

要在 Claude Code 中使用本地自建的 Firecrawl，需调整配置：

{
  "mcpServers": {
    "firecrawl-local": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_URL": "http://localhost:3002",
        "FIRECRAWL_API_KEY": "" 
      }
    }
  }
}

注意：本地模式下，如果关闭了 USE_DB_AUTHENTICATION，则 FIRECRAWL_API_KEY 可以留空。

---

3.4 常见问题排查

• ECONNREFUSED：通常是 Redis 或 PostgreSQL 未启动。
• NUQ_DATABASE_URL 错误：确保数据库中已初始化正确的 Schema。
• 抓取失败：本地模式默认没有全球代理池，受限于你当前的本地网络环境。