> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-27eiio.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 自托管 Firecrawl

> 使用 Docker Compose 自托管 Firecrawl，验证本地抓取，了解开源版本的限制，并为生产环境做好准备。

<span id="self-hosting-firecrawl" />

当您需要掌控源代码或基础设施时，可使用 Docker Compose 自托管 Firecrawl。本指南固定使用版本 `v2.11.162`，在 `http://localhost:3002` 启动 API，并验证 `POST /v2/scrape` 成功返回 Markdown 响应。

<Warning>
  此面向受信任网络的 Quickstart 会禁用 API 身份验证，并非
  生产环境架构。它不包含持久化存储、TLS、高可
  用性，也不具备 Firecrawl Cloud 的全部功能。
</Warning>

<div id="choose-self-hosting-or-firecrawl-cloud">
  ## 选择自托管或使用 Firecrawl Cloud
</div>

<div id="self-host-firecrawl-when">
  ### 在以下情况下自托管
</div>

* **您希望掌控源代码或基础设施。** 本指南将帮助您在自己的机器上运行 API 及其配套服务。
* **您熟悉整套技术栈的运维。** 您需要负责升级、安全、存储、监控和恢复。
* **您希望在自身环境中验证 Firecrawl。** 请先在此处完成基础配置，然后在[生产前准备](#before-production)中设计相应的控制措施。

如果您希望无需自行运行基础设施即可开始抓取，请选择 [Firecrawl Cloud](https://firecrawl.dev)。有关功能差异，请参见[开源版与 Cloud](/zh/contributing/open-source-or-cloud)。

**我们的建议：** 只有当源代码访问权限或基础设施控制带来的价值值得额外运维工作时，才选择自行托管。如果您希望通过最快的受支持路径投入生产，请从 Firecrawl Cloud 开始。

<div id="what-self-hosting-requires">
  ### 自托管需要承担的事项
</div>

* 升级、密钥、存储、监控、恢复和事件响应均由你负责。
* 抓取仍会向目标网站发送出站请求。可选的代理、解析或 AI 提供商会带来额外的数据流。
* 本指南刻意简化首次运行。先让一次抓取成功，再逐项调整配置。
* 这些命令固定使用 `v2.11.162`。其他版本可能采用不同的 Compose 约定。

<div id="self-host-firecrawl-with-docker-compose">
  ## 使用 Docker Compose 自托管 Firecrawl
</div>

<div id="start-with-these-defaults">
  ### 采用以下默认设置
</div>

* **版本：Firecrawl `v2.11.162`。** 先固定代码和配置。查看目标版本的 `docker-compose.yaml` 和自托管说明后再升级。
* **API 身份验证：此次本地运行关闭。** 仅在具备完整且受支持的身份验证和数据库设计时启用；仅设置一个环境变量并不够。
* **队列：PostgreSQL。** 除非你有意运维可选的 FoundationDB 后端，否则请保持此设置。
* **队列管理 UI：关闭。** 仅在设置高强度 `BULL_AUTH_KEY` 并采取网络控制措施后启用。
* **AI 和高级抓取提供商：未配置。** 当所需功能依赖某个提供商时再添加。

首次运行尽量保持简单：先让一次抓取正常运行，再按用例需要添加功能。

<div id="prerequisites">
  ### 前置条件
</div>

开始前，请安装：

* [Git](https://git-scm.com/downloads)
* [Docker Engine](https://docs.docker.com/engine/install/) 或 Docker Desktop
* Docker Compose v2 (通过 `docker compose` 调用)
* 用于发送验证请求的 `curl`

请确保端口 `3002` 可用，并且 Docker 有足够资源来构建和运行多个服务。Firecrawl 尚未公布此技术栈经过验证的最低主机配置。

<div id="clone-the-verified-release">
  ### 克隆经验证的版本
</div>

本指南已基于 Firecrawl `v2.11.162` 验证。请检出该特定版本，以确保代码、命令和配置保持同步：

```bash theme={null}
git clone https://github.com/firecrawl/firecrawl.git
cd firecrawl
git checkout v2.11.162
```

想使用其他版本？复用这些值前，请先查看该版本的 `docker-compose.yaml` 和自托管说明。

<div id="configure-the-evaluation-deployment">
  ### 配置评估环境部署
</div>

在仓库根目录创建最简可用的 `.env` 文件：

```bash theme={null}
cat > .env <<'EOF'
USE_DB_AUTHENTICATION=false
POSTGRES_USER=postgres
POSTGRES_PASSWORD=replace-with-at-least-32-random-characters
POSTGRES_DB=postgres
EOF
```

请在启动整套服务前更改 PostgreSQL 密码，并且不要提交 `.env`。对于 `v2.11.162`，请保留 `POSTGRES_DB=postgres`，因为内置的 `pg_cron` 配置针对该数据库。Compose 会将这些值传递给 API 和 PostgreSQL 服务。

<Note>
  `apps/api/.env.example` 用于 API 开发，并非可直接用于 Compose 的配置文件。
  首次运行会禁用数据库身份验证，因此请求无需提供
  API 密钥或 `Authorization` 请求头。
</Note>

请勿设置 `NUQ_BACKEND` 和 `BULL_AUTH_KEY`。你将使用 PostgreSQL 队列，无需运行队列管理 UI——这样首次抓取所需的组件更少。

<div id="build-and-start-firecrawl">
  ### 构建并启动 Firecrawl
</div>

构建已检出的源代码，并在后台启动所有组件：

```bash theme={null}
docker compose up --build -d
docker compose ps --all
```

此基线中出现未设置可选变量的警告属于预期情况。`docker compose ps --all` 应显示 API 和支持服务正在运行，而一次性初始化服务已完成。如果服务仍在启动，请稍候片刻。

<div id="check-api-reachability">
  ### 检查 API 是否可访问
</div>

首先，确保 API 能响应 HTTP 请求：

```bash theme={null}
curl \
  --fail \
  --silent \
  --show-error \
  --max-time 5 \
  http://localhost:3002/v0/health/readiness
```

预期响应：

```json theme={null}
{"status":"ok"}
```

<Warning>
  这只是心跳检测，并非端到端测试。它不会检查 Redis、
  PostgreSQL、RabbitMQ、Playwright、worker 或出站网络访问。在将该部署视为可用之前，请先运行
  以下抓取操作。
</Warning>

<div id="run-a-functional-smoke-test">
  ### 运行功能冒烟测试
</div>

现在测试关键路径：执行一次真实抓取。请求超时以毫秒为单位；curl's 客户端超时以秒为单位，且略长一些：

```bash theme={null}
curl \
  --fail-with-body \
  --silent \
  --show-error \
  --max-time 75 \
  -X POST \
  http://localhost:3002/v2/scrape \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown"],
    "timeout": 60000
  }'
```

成功的响应如下：

```json theme={null}
{
  "success": true,
  "data": {
    "markdown": "...",
    "metadata": {
      "statusCode": 200
    }
  }
}
```

这会同时检查 API、抓取流水线、一条抓取引擎路径以及出站访问。具体元数据可能因目标响应而异。

如果返回这些成功字段，说明 Firecrawl 已在您的基础设施上端到端正常运行。保留这一基线，然后选择下一步要添加的内容。

<div id="self-hosted-feature-support">
  ## 自托管功能支持
</div>

首次抓取已成功。只有在确有需求时再添加相应功能，而不是因为它存在就启用：

| 如果你需要                                                   | 建议                                                    |
| ------------------------------------------------------- | ----------------------------------------------------- |
| 核心抓取、crawl、map 和 search 路由                              | 保持默认技术栈。已包含 Fetch 和 Playwright 处理。                    |
| 基于 LLM 的提取或 formats                                     | 连接兼容 OpenAI 的提供商或 Ollama，然后单独测试该流程。                   |
| Fire-engine 或其高级反爬行为                                    | 单独运行并配置该服务；默认技术栈不包含它。                                 |
| 截图或页面 actions                                           | 默认技术栈不支持。Fetch 和 Playwright 均报告不支持；两者都需要 Fire-engine。 |
| Agent、Browser、interact、feedback，或专用的产品、菜单、音频和视频 formats | 使用 Firecrawl Cloud，或确认特定功能所需的外部服务要求。                  |

如需更全面的产品对比，请参见[开源版与 Cloud](/zh/contributing/open-source-or-cloud)。如需针对特定版本进行配置，请使用固定版本的 [`docker-compose.yaml`](https://github.com/firecrawl/firecrawl/blob/v2.11.162/docker-compose.yaml) 作为配套参考。

<div id="before-production">
  ## 上线前
</div>

Compose 可帮助你快速完成首次部署。要将 API 置于受信任网络之外用于生产环境，还需做出几项明确决策：

* \*\*如果数据必须在服务替换后保留，\*\*请为 PostgreSQL、Redis 和 RabbitMQ 添加持久化存储，并制定和测试备份与恢复流程。提供的 Compose 文件未添加这些数据卷。
* \*\*如果用户或不受信任的网络可以访问 API，\*\*请采用受支持的身份验证方案、网络访问控制，并在反向代理或入口层配置 TLS。请勿将这个未经身份验证的基础配置暴露在公网。
* \*\*如果对可用性或容量有要求，\*\*请设定正常运行时间目标、监控、资源规格、扩缩容触发条件，以及升级和回滚流程。Compose 中的限制并非经验证的最低要求。
* \*\*如果数据存储位置或合规性至关重要，\*\*请在启用前确认请求会发送至哪些目标网站，以及每个可选的 AI、代理或解析提供商。
* \*\*如果必须集中管理密钥，\*\*请将数据库密码从 `.env` 移至平台的密钥管理系统。

这些都是基础设施层面的决策。没有任何一个 `.env` 开关能让该技术栈满足生产环境要求。

<div id="where-to-go-next">
  ## 下一步
</div>

* **仍在评估？** 请将 API 保持在受信任的网络中，并在完成后运行 `docker compose down`。
* **要添加开源功能？** 通过[自托管功能支持](#self-hosted-feature-support)查找所需的提供商或服务，然后单独测试该方案。
* **要修改 Firecrawl 代码？** 请参阅[本地运行](/zh/contributing/guide)，设置贡献者开发环境。
* **要连接客户端？** 将 [Firecrawl CLI](/zh/sdks/cli#connect-the-cli-to-self-hosted-firecrawl) 或[本地 MCP 服务器](/zh/mcp-server/local#connect-mcp-to-self-hosted-firecrawl)配置为使用已验证的 API URL。
* **要迁移到 Kubernetes？** 请先参考 [`SELF_HOST.md`](https://github.com/firecrawl/firecrawl/blob/main/SELF_HOST.md) 中链接的带版本 Kubernetes 或 Helm 文档，然后针对你的平台明确做出上述生产环境决策。
* **需要托管基础设施或仅限 Cloud 的功能？** 请比较[开源版与 Cloud](/zh/contributing/open-source-or-cloud)。
* **要投入生产？** 请在公开 API 前完成[生产前准备](#before-production)中的每项决策。

<div id="troubleshooting">
  ## 故障排查
</div>

<div id="youre-bypassing-authentication">
  ### 你正在绕过身份验证
</div>

如果在 `USE_DB_AUTHENTICATION=false` 时看到此警告，说明这是预期的首次运行流程。请求会使用 self-hosted 身份，无需 API 密钥。如果该 API 可从不受信任的网络访问，请停止操作，并按照[生产环境前](#before-production)中的说明添加控制措施。

<div id="docker-containers-fail-to-start">
  ### Docker 容器无法启动
</div>

如果任何长期运行的服务退出，请检查容器状态和最新日志：

```bash theme={null}
docker compose ps --all
docker compose logs --tail=200
```

* 如果源代码版本不同，请检出 `v2.11.162`，或使用该版本的配置。
* 如果构建过程或容器受资源限制，请增加 Docker 的 CPU、内存或磁盘容量。
* 如果 PostgreSQL 启动失败，请检查 `.env` 语法，保持 `POSTGRES_DB=postgres`，并确保用户名和密码一致。

<div id="connection-issues-with-redis">
  ### Redis 连接问题
</div>

如果容器无法连接到 Redis，请使用 Compose 服务地址 `redis://redis:6379`。`localhost` 指向容器自身，而不是 Redis 服务。

```bash theme={null}
docker compose ps redis
docker compose logs --tail=100 redis
```

如果您设置了 `REDIS_URL` 或 `REDIS_RATE_LIMIT_URL`，请移除覆盖配置以恢复默认值，或使用可在 Compose 网络内部解析的地址。

<div id="api-endpoint-does-not-respond">
  ### API 端点无响应
</div>

如果端口 `3002` 无响应，请检查 API 容器及其日志：

```bash theme={null}
docker compose ps api
docker compose logs --tail=200 api
```

如果其他进程占用了端口 `3002`，请停止该进程，或同步修改发布的端口。初次启动时，只有在 API 容器显示为正在运行后再重试。

如果 `/v0/health/readiness` 请求成功，但 `/v2/scrape` 失败，请检查 API 和 Playwright 日志，因为可达性端点不会验证这些依赖项：

```bash theme={null}
docker compose logs --tail=200 api playwright-service
```

<div id="scrape-request-times-out">
  ### 抓取请求超时
</div>

如果抓取操作超时，请确认部署环境可以访问 `https://example.com`，且 API 和 Playwright 服务正在运行。请将 curl 的 `--max-time` 设置为长于请求正文中的 `timeout`，以便 API 能返回自身的超时响应。