代码收藏家技术教程 20小时前

Docker本地部署Firecrawl服务及Python客户端交互教程：安装步骤与使用策略示例

好的，这是一份关于如何使用 Docker 本地部署 Firecrawl 服务，并通过 Python 客户端 (firecrawl-py) 与之交互的教程，包含安装步骤和使用策略示例。

简介与目标
前提条件
本地 Docker 部署步骤
3.1 克隆 Firecrawl 仓库
3.2 检查 Docker 配置
3.3 配置环境变量 (重要!)
3.4 构建并启动服务
3.5 验证运行状态
配置 Python 客户端 (firecrawl-py) 连接本地服务
4.1 安装/更新 firecrawl-py
4.2 初始化 FirecrawlApp 指向本地服务
Python 使用示例 (连接本地服务)
5.1 示例：基本抓取 (本地)
5.2 示例：爬取网站 (本地)
5.3 示例：LLM 提取 (本地 – 注意事项)
本地部署策略与注意事项

1. 简介与目标

本教程旨在指导你完成以下目标：

本地部署 Firecrawl 后端服务: 使用 Docker 和 Docker Compose 在你自己的机器上运行 Firecrawl 的核心爬虫和 API 服务。
配置 Python 客户端: 让你的 Python 脚本通过 firecrawl-py 库与本地部署的 Firecrawl 服务进行通信，而不是官方的云 API (api.firecrawl.dev)。
提供使用示例: 展示如何在本地部署环境中使用 Python 进行抓取和爬取。

这使你能够：

在没有互联网连接的情况下（如果目标网站在本地网络）进行开发测试。

更好地控制数据隐私（数据不离开你的机器）。

可能绕过云服务的某些限制（但要注意资源消耗和维护成本）。

2. 前提条件

在开始之前，请确保你的系统满足以下条件：

Docker 和 Docker Compose: 已正确安装并正在运行。这是部署 Firecrawl 服务的基础。(Docker 安装文档, Docker Compose 安装文档)
Git: 用于从 GitHub 克隆 Firecrawl 的源代码仓库。
Python: 已安装 Python 3.x。
pip: Python 包管理器，通常随 Python 一起安装。
命令行/终端: 熟悉基本的操作，如 cd, git clone, docker-compose 等。
足够的系统资源: 运行 Docker 容器，特别是执行网页渲染和爬取的容器，会消耗较多的 CPU 和内存。建议至少有 8GB 内存和多核 CPU。
(可选但推荐) OpenAI API 密钥: 如果你想在本地部署中使用 LLM 提取 (llm-extraction) 功能，你必须提供自己的 OpenAI API 密钥 (或其他支持的 LLM 提供商密钥)。自托管版本通常不包含免费的 LLM 调用。

3. 本地 Docker 部署步骤

3.1 克隆 Firecrawl 仓库

首先，需要从 GitHub 获取 Firecrawl 的源代码。请务必查找 Firecrawl 的官方 GitHub 仓库，以下命令使用一个假设的地址，请替换为实际地址。

# 访问 Firecrawl 的 GitHub 页面找到正确的仓库 URL
# 例如：https://github.com/mendableai/firecrawl (请核实!)
git clone https://github.com/mendableai/firecrawl.git
cd firecrawl # 进入克隆下来的目录

3.2 检查 Docker 配置

在仓库的根目录或特定子目录（如 docker/）下，通常会有一个名为 docker-compose.yml 的文件。这个文件定义了运行 Firecrawl 所需的 Docker 服务（例如 API 服务、可能的后台工作进程等）。打开并大致浏览一下这个文件，了解它会启动哪些容器。

3.3 配置环境变量 (重要!)

许多 Docker 应用使用 .env 文件来管理配置。检查仓库的 README.md 或部署文档，看是否需要创建 .env 文件。

常见的配置项可能包括：

PORT: API 服务监听的端口号。如果未指定，可能默认为 3000 或 3002。你需要知道这个端口号才能连接。

OPENAI_API_KEY: 如果你要使用 LLM 提取功能，这个通常是必需的。 将你的 OpenAI 密钥或其他 LLM 提供商的密钥放在这里。

# 示例 .env 文件内容
PORT=3002
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# 可能还有其他数据库、缓存或日志配置...

仔细阅读官方文档，了解所有必需和可选的环境变量。

3.4 构建并启动服务

在包含 docker-compose.yml 文件的目录下，运行以下命令：

docker-compose up -d

docker-compose up: 根据 docker-compose.yml 拉取镜像、构建（如果需要）并启动服务。

-d: 让服务在后台（detached mode）运行。

首次运行时，Docker 可能需要下载基础镜像并构建 Firecrawl 的镜像，这可能需要一些时间。

3.5 验证运行状态

等待一段时间后，检查服务是否成功启动：

检查容器状态:
```
docker-compose ps
```
你应该能看到类似 firecrawl_api_1 或其他相关服务的状态显示为 Up 或 Running。
查看日志 (排错时非常有用):
```
docker-compose logs -f
```
或者只看 API 服务的日志 (假设服务名为 api):
```
docker-compose logs -f api
```
查看日志可以帮助你发现启动过程中的错误。

一旦服务状态正常，并且你在日志中没有看到明显的错误，本地 Firecrawl API 应该就在 http://localhost:PORT (将 PORT 替换为实际配置或默认的端口号，例如 http://localhost:3002) 上运行了。

4. 配置 Python 客户端 (`firecrawl-py`) 连接本地服务

现在你的 Firecrawl 服务已经在本地运行，你需要告诉 firecrawl-py 库不要去访问云 API，而是访问你的本地实例。

4.1 安装/更新 `firecrawl-py`

确保你安装了 firecrawl-py 库，或者更新到最新版本：

pip install -U firecrawl-py

4.2 初始化 `FirecrawlApp` 指向本地服务

在你的 Python 代码中，初始化 FirecrawlApp 时，需要指定 api_url 参数。

import os
from firecrawl import FirecrawlApp

# --- 配置本地 API 地址 ---
# 将 3002 替换为你 Docker 服务实际监听的端口号
# 确保包含 API 的基础路径，通常是 /v0
LOCAL_FIRECRAWL_API_URL = "http://localhost:3002/v0"

# --- 初始化 App 指向本地 ---
# 对于自托管版本，API Key 的处理方式可能不同：
# 1. 如果你的本地部署配置了需要认证 (例如通过 .env 设置了特定密钥)，请传入 api_key。
# 2. 如果本地部署不需要认证，可以将 api_key 设置为 None 或省略。
# 请查阅 Firecrawl 自托管文档了解确切的认证方式。
# 这里假设本地不需要 key (常见情况) 或 key 通过其他方式处理
app = FirecrawlApp(api_url=LOCAL_FIRECRAWL_API_URL, api_key=None)

print(f"[*] Firecrawl Python 客户端已配置，将连接到: {LOCAL_FIRECRAWL_API_URL}")

现在，通过这个 app 对象发出的所有请求都将发送到你本地运行的 Firecrawl 服务。

5. Python 使用示例 (连接本地服务)

以下是使用配置好的本地 app 对象的示例。

5.1 示例：基本抓取 (本地)

import json
# (假设上面的 app 初始化代码已执行)

target_url = 'https://example.com' # 使用一个简单的 URL 测试

print(f"\n[*] [本地] 正在抓取 URL: {target_url}")

try:
    scraped_data = app.scrape_url(target_url) # 使用配置好的本地 app

    if isinstance(scraped_data, dict):
        print("[+] [本地] 抓取成功!")
        print("--- Markdown 内容 (部分) ---")
        print(scraped_data.get('markdown', '无 Markdown 内容')[:200] + "...")
        print("\n--- 元数据 ---")
        metadata = scraped_data.get('metadata')
        print(json.dumps(metadata, indent=2) if metadata else "无元数据")
    else:
        print(f"[!] [本地] 抓取失败，返回类型: {type(scraped_data)}")
        print(scraped_data)

except Exception as e:
    print(f"[!] [本地] 抓取过程中发生错误: {e}")

5.2 示例：爬取网站 (本地)

import time
# (假设上面的 app 初始化代码已执行)

start_url = 'https://firecrawl.dev/docs' # 可以换成本地可访问的地址测试

print(f"\n[*] [本地] 开始爬取网站: {start_url}")

try:
    crawl_params = {
        'crawlerOptions': {
            'limit': 3,      # 限制爬取数量，本地测试时从小开始
            'maxDepth': 1    # 限制爬取深度
        },
        'pageOptions': {
            'onlyMainContent': True
        }
    }

    print("[*] [本地] 正在执行爬取任务...")
    start_time = time.time()
    # 使用本地 app，并等待完成
    crawled_data = app.crawl_url(start_url, params=crawl_params, wait_until_done=True)
    end_time = time.time()
    print(f"[*] [本地] 爬取任务完成，耗时: {end_time - start_time:.2f} 秒")

    if isinstance(crawled_data, list):
        print(f"[+] [本地] 爬取成功！共抓取到 {len(crawled_data)} 个页面。")
        for i, page in enumerate(crawled_data):
            if isinstance(page, dict):
                 print(f"- Page {i+1}: {page.get('source_url', 'N/A')}")
            else:
                 print(f"- Page {i+1}: 数据格式错误 {type(page)}")
    else:
        print(f"[!] [本地] 爬取失败或返回类型不符: {type(crawled_data)}")
        print(crawled_data)

except Exception as e:
    print(f"[!] [本地] 爬取过程中发生错误: {e}")

5.3 示例：LLM 提取 (本地 – 注意事项)

重要提示: 要使此示例在本地部署中工作，你必须已在部署 Firecrawl Docker 服务时，通过 .env 文件正确配置了 OPENAI_API_KEY (或其他 LLM 提供商的密钥)。调用 LLM 的费用将由你自己的账户承担。

# (假设上面的 app 初始化代码已执行)

target_url = 'https://firecrawl.dev/' # 示例 URL

print(f"\n[*] [本地] 正在抓取并使用 LLM 提取: {target_url}")
print("[!] 注意：这需要本地 Docker 环境已配置有效的 OPENAI_API_KEY (或等效项)")

try:
    extraction_schema = {
        "type": "object",
        "properties": {
            "title": {"type": "string"},
            "description": {"type": "string"}
        },
        "required": ["title"]
    }

    params = {
        'extractorOptions': {
            'mode': 'llm-extraction',
            'extractionSchema': extraction_schema
        }
    }
    scraped_data = app.scrape_url(target_url, params=params) # 使用本地 app

    if isinstance(scraped_data, dict) and 'llm_extraction' in scraped_data:
        print("[+] [本地] LLM 提取成功!")
        print("--- 提取的数据 ---")
        print(json.dumps(scraped_data['llm_extraction'], indent=2, ensure_ascii=False))
    elif isinstance(scraped_data, dict):
         print("[!] [本地] 抓取成功，但未找到 LLM 提取结果。检查 Docker 服务日志和 OpenAI Key 配置。")
         # print(scraped_data) # 可以打印完整结果排查
    else:
        print(f"[!] [本地] 抓取或提取失败，返回类型: {type(scraped_data)}")
        print(scraped_data)

except Exception as e:
    # 错误可能来自 Firecrawl 服务本身，也可能来自 OpenAI API (如密钥无效、额度用尽)
    print(f"[!] [本地] LLM 提取过程中发生错误: {e}")
    print("[!] 请检查本地 Firecrawl Docker 服务的日志以获取详细信息。")