Firecrawl 本地 Docker 部署指南（Windows 系统）

最新推荐文章于 2025-06-10 10:30:03 发布

少年与漫光

最新推荐文章于 2025-06-10 10:30:03 发布

阅读量4.5k

点赞数 45

CC 4.0 BY-SA版权

文章标签： docker windows python

本文链接：https://blog.youkuaiyun.com/javatrip01/article/details/147040768

Firecrawl 本地 Docker 部署指南（Windows 系统）

**本文将介绍如何在 Windows 本地开发环境中利用 Docker Desktop 来部署 Firecrawl 项目，使用默认配置（无需提供 API Key 等可选参数）。**步骤涵盖代码仓库克隆、Docker 环境准备、环境变量配置、容器启动、服务访问以及常见错误的排查。

1. 克隆 Firecrawl 项目仓库

在开始之前，请确保已安装 Git 工具。然后，在终端（Windows 下可使用 Git Bash 或 PowerShell）中执行以下命令，将 Firecrawl 源代码克隆到本地 (本地部署 Firecrawl_firecrawl本地部署-优快云博客)：

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

克隆完成后，会生成一个名为 firecrawl 的目录。请进入该目录，准备进行后续配置和部署步骤。

2. 安装并启动 Docker Desktop

确保本机已安装 Docker Desktop（Windows 版）。如果尚未安装，可从 Docker 官方网站下载并按照指引安装 (Firecrawl 部署安装及 Dify 调用（保证好使）_dify firecrawl-优快云博客)。安装过程中 Docker 会提示启用 WSL2 后端支持，按提示操作即可。安装完成后，启动 Docker Desktop，并确保其后台的 Docker 守护进程已经运行。

提示： Docker Desktop 正常运行后，可以在终端中运行 docker info 或 docker version 来测试。如果出现 “Cannot connect to the Docker daemon” 等错误，表示 Docker 守护进程未启动，请先打开 Docker Desktop 应用并等待其初始化完毕 (Troubleshooting the Docker daemon | Docker Docs
)。

3. 配置环境变量 (.env 文件)

克隆的项目中包含一个环境变量示例文件。需要将其复制为实际配置文件并使用默认值运行：

找到项目目录下的 apps/api/.env.example 文件。将该文件复制到 项目根目录 并重命名为 .env (Firecrawl 部署安装及 Dify 调用（保证好使）_dify firecrawl-优快云博客)。在 Git Bash 或 PowerShell 中可以用以下命令完成复制：
```
cd firecrawl/apps/api
# 将 .env.example 复制到上两级目录（项目根目录）并命名为 .env
cp .env.example ../../.env
```
打开项目根目录下新生成的 .env 文件，确认和调整以下内容：
- 必需参数： 设置基本的服务参数。例如：
```
PORT=3002
HOST=0.0.0.0
USE_DB_AUTHENTICATION=false
NUM_WORKERS_PER_QUEUE=8
BULL_AUTH_KEY=CHANGEME
```
  上述配置指定 Firecrawl API 服务监听本机的 3002 端口，允许所有网卡地址访问（0.0.0.0），不启用数据库用户认证，并使用默认的 Bull 队列管理密钥 CHANGEME（仅本地开发可使用默认值） (本地部署 Firecrawl_firecrawl本地部署-优快云博客)。
- 可选参数： 绝大多数其他环境变量（如 OpenAI API Key、代理设置等）可保持为空或注释状态。默认情况下不提供这些可选参数并不会影响核心抓取功能，相关高级功能（如 LLM 内容提取、第三方抓取服务等）将自动处于禁用状态 (本地部署 Firecrawl_firecrawl本地部署-优快云博客)。例如，.env 文件中 OpenAI API Key 一项可保持如下：
```
OPENAI_API_KEY=
```
  留空表示不使用 OpenAI 功能。类似地，其他可选配置如 ScrapingBee API 密钥、Supabase URL 等都可保持默认空值。
- 内部服务地址： Firecrawl 使用 Docker Compose 同时运行多个服务容器（包括 Redis 和 Playwright 服务）。对于 .env 中涉及内部服务地址的变量（例如 REDIS_URL、REDIS_RATE_LIMIT_URL 和 PLAYWRIGHT_MICROSERVICE_URL），如果 .env.example 中存在这些项，请确保它们指向容器内部地址而非 localhost。通常官方模板中已注明这些变量由 Docker Compose 自动配置，无需手动设置 (本地部署 Firecrawl_firecrawl本地部署-优快云博客)。建议将相关行保留为注释状态，以使用 Compose 文件中的默认值。例如：
```
# (Docker Compose 自动配置，无需手动设置)
# PLAYWRIGHT_MICROSERVICE_URL=http://playwright-service:3000/scrape
# REDIS_URL=redis://redis:6379
# REDIS_RATE_LIMIT_URL=redis://redis:6379
```
  上述注释表示容器内部将自动采用 redis://redis:6379 等默认地址。因此，无需在本地 .env 中修改这些值。

完成 .env 文件配置并保存后，Firecrawl 的环境变量即已就绪。默认配置下不需要填写任何 API Key 或可选参数即可运行。

4. 使用 Docker Compose 构建并启动容器

在项目根目录下，通过 Docker Compose 来构建和启动 Firecrawl 所需的所有容器服务。

首先，（可选）构建镜像：运行以下命令让 Docker 根据仓库内容构建应用镜像（首次运行会自动下载所需基础镜像，耗时可能较长） (本地部署 Firecrawl_firecrawl本地部署-优快云博客)：

docker compose build

然后，启动容器：执行 Docker Compose 的启动命令，将所有服务以后台方式运行 (本地部署 Firecrawl_firecrawl本地部署-优快云博客)：

docker compose up -d

Docker Compose 将根据定义启动多个容器，包括 Firecrawl 主应用（API 服务）、后台工作进程、Playwright 微服务、Redis 数据库等。使用 -d 参数会使容器在后台运行，您可以继续使用终端而不会被日志输出刷屏。

注意： 如果在执行 docker compose up -d 时未提前构建镜像，Docker Compose 会自动先进行构建，再启动容器。此外，首次启动时需要下载基础镜像和依赖，耐心等待所有容器启动完成。

5. 验证容器状态与访问服务

检查容器状态： 在终端执行 docker compose ps 可以查看当前运行的容器列表及其状态。也可以打开 Docker Desktop，进入 Containers / Apps 面板查看名为 firecrawl 的应用组下的各个容器是否都处于运行（Running）状态。

如果某些容器意外退出（Exited）或未正常运行，可执行 docker compose logs 或 docker compose logs -f 查看详细日志以定位问题。

访问 Firecrawl 服务： 按默认配置，Firecrawl 的 API 服务监听在本机的 3002 端口。启动成功后，可在浏览器中访问 http://localhost:3002 来验证服务是否对外提供接口 (本地部署 Firecrawl_firecrawl本地部署-优快云博客)。首次打开时，浏览器可能不会显示特定页面（因为 Firecrawl 是一个后端 API 服务），但不会出现无法连接的错误即表示服务已启动成功。

使用管理界面： Firecrawl 内置了任务队列的管理界面（基于 Bull Queue）。您可以在浏览器访问 http://localhost:3002/admin/CHANGEME/queues 查看当前爬取任务队列情况 (本地部署 Firecrawl_firecrawl本地部署-优快云博客)。其中路径中的 CHANGEME 是默认的队列管理密钥（即 .env 文件中配置的 BULL_AUTH_KEY）。如果您已修改过 BULL_AUTH_KEY，请将 URL 中的 CHANGEME 替换为您设置的值。这个界面将显示任务队列状态、执行中的任务等，用于监控 Firecrawl 的工作情况。

6. 常见问题排查

部署过程中若遇到问题，可参考以下方案进行排查：

Docker 服务未启动： 如果在运行 Docker 命令时收到 “Cannot connect to the Docker daemon” 或 “Is the docker daemon running?” 等错误提示，说明 Docker Desktop 未启动或 Docker 守护进程未运行。请先启动 Docker Desktop 并确保其状态正常，然后重试上述命令 (Troubleshooting the Docker daemon | Docker Docs
)。
无需提供 API 密钥： Firecrawl 本地部署时不需要提供任何 API Key。当使用官方 SDK 连接云端服务时才需要 API Key，本地自部署完全可运行而不填写此项 (本地部署 Firecrawl_firecrawl本地部署-优快云博客)。
忽略 Supabase 配置： Firecrawl 自行部署的版本暂不支持 Supabase 相关的用户认证功能，所以 .env 中关于 Supabase 的配置可留空。即使控制台出现未配置 Supabase 的提示，也不影响正常的爬取功能 (本地部署 Firecrawl_firecrawl本地部署-优快云博客)。
容器启动失败： 如果执行 docker compose up 后容器立即退出或无法启动，请检查容器日志来获取错误原因（如运行 docker compose logs api 查看主应用日志）。常见问题包括 .env 环境变量缺失或拼写错误，以及 Docker Compose 配置未正确应用等 (本地部署 Firecrawl_firecrawl本地部署-优快云博客)。确认 .env 文件中必需变量都已设置且没有拼写错误，Docker Compose 文件未被意外修改。
Redis 连接问题： 若 Firecrawl 服务日志显示无法连接 Redis，可能是环境变量配置不正确或容器网络问题。请确保 Redis 容器正常运行，以及 .env 文件中的 REDIS_URL 和 REDIS_RATE_LIMIT_URL 都指向 redis://redis:6379（即 Docker 内部网络地址） (本地部署 Firecrawl_firecrawl本地部署-优快云博客)。使用默认配置时，Docker Compose 已处理好容器网络和名称解析，一般无需额外配置。
API 接口无响应： 如果浏览器访问 http://localhost:3002 没有任何响应，请检查 Firecrawl 的 API 容器是否在运行，并确认 .env 中的 PORT 和 HOST 设置正确无误（默认情况下应为 3002 和 0.0.0.0） (本地部署 Firecrawl_firecrawl本地部署-优快云博客)。另外，确保本机防火墙或安全软件没有拦截 Docker 容器的网络通信。您也可以尝试用 curl 或 Postman 等工具对 http://localhost:3002/v1/health（假设 Firecrawl 提供健康检查端点）发送请求，来判断服务是否正常响应。