内容
# Firecrawl 本地版
Firecrawl 通过 Docker（OrbStack 或 Docker Desktop）在 Mac 上本地运行。停止时占用 0 RAM，启动需约 5 秒。
技术栈：5 个容器 — API、Playwright、Redis、RabbitMQ、PostgreSQL。
## 快速开始
```bash
git clone https://github.com/raphaelmarcelo/firecrawl-local.git
cd firecrawl-local
./install.sh
```
`install.sh` 自动完成以下操作：
1. 检查 OrbStack/Docker Desktop 是否已安装
2. 如果 Docker 未运行，则打开它
3. 检查 `docker compose`、`curl`、`node`、`python3`
4. 下载镜像（约 2-3 GB）
5. 创建容器并测试爬虫
6. 停止容器（按需启动）
## 要求
- **macOS**（测试于 macOS Sequoia）
- **OrbStack**（推荐）或 **Docker Desktop**
- **curl**（macOS 自带）
- **Node.js + npx**（MCP 与 Claude Code/Codex 需要）
### 安装 OrbStack
比 Docker Desktop 更轻量，占用更少的 RAM 和 CPU：
```bash
brew install orbstack
```
或直接下载：https://orbstack.dev
## 使用
### 手动命令
```bash
./scripts/firecrawl.sh start # 启动容器
./scripts/firecrawl.sh stop # 停止（释放 RAM）
./scripts/firecrawl.sh status # 显示运行状态 + RAM 占用
./scripts/firecrawl.sh test # 快速测试爬虫
./scripts/firecrawl.sh logs # 查看 API 日志（tail -f）
./scripts/firecrawl.sh pull # 更新 Docker 镜像
./scripts/firecrawl.sh reset # 删除所有（容器 + 数据卷）
```
### 直接使用 curl
```bash
# 爬取 URL
curl -s -X POST http://localhost:3002/v1/scrape \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer fc-local' \
-d '{"url": "https://example.com", "formats": ["markdown"]}'
# 搜索
curl -s -X POST http://localhost:3002/v1/search \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer fc-local' \
-d '{"query": "your search here", "limit": 5}'
# 映射网站 URL
curl -s -X POST http://localhost:3002/v1/map \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer fc-local' \
-d '{"url": "https://example.com"}'
```
## 集成
### Claude Code (MCP)
1. 添加 MCP 服务器：
```bash
claude mcp add firecrawl -s user \
-e FIRECRAWL_API_URL=http://localhost:3002 \
-e FIRECRAWL_API_KEY=fc-local \
-- npx -y firecrawl-mcp
```
2. 在项目设置中配置自动启动/停止钩子（`.claude/settings.local.json`）：
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "mcp__firecrawl__.*",
"hooks": [
{
"type": "command",
"command": "/PATH/TO/firecrawl-local/scripts/ensure-firecrawl.sh"
}
]
}
],
"PostToolUse": [
{
"matcher": "mcp__firecrawl__.*",
"hooks": [
{
"type": "command",
"command": "/PATH/TO/firecrawl-local/scripts/stop-firecrawl.sh"
}
]
}
]
}
}
```
替换 `/PATH/TO/` 为实际的项目克隆路径。
这样，每当 Claude 使用 `mcp__firecrawl__*` 工具时：
- **之前**：`ensure-firecrawl.sh` 自动启动 Docker
- **之后**：`stop-firecrawl.sh` 在 10 分钟不活动后安排自动停止
### Codex (OpenAI)
使用已自动确保/停止的 MCP 包装器：
```json
{
"mcpServers": {
"firecrawl": {
"command": "/PATH/TO/firecrawl-local/scripts/codex-firecrawl-mcp.sh",
"env": {
"FIRECRAWL_API_URL": "http://localhost:3002",
"FIRECRAWL_API_KEY": "fc-local"
}
}
}
}
```
### 任意 MCP 客户端（Cline、Cursor 等）
添加到项目的 `.mcp.json` 中：
```json
{
"mcpServers": {
"firecrawl": {
"command": "npx",
"args": ["-y", "firecrawl-mcp"],
"env": {
"FIRECRAWL_API_URL": "http://localhost:3002",
"FIRECRAWL_API_KEY": "fc-local"
}
}
}
}
```
在这种情况下，请在手动启动前使用：`./scripts/firecrawl.sh start`
## 工作原理
### 架构
```
┌──────────────┐
Claude/Codex ───► │ API (:3002) │
(MCP) └──────┬───────┘
│
┌────────────┼────────────┐
│ │ │
┌──────┴──────┐ ┌─┴──┐ ┌─────┴─────┐
│ Playwright │ │Redis│ │ RabbitMQ │
│ （浏览器） │ └────┘ └───────────┘
└─────────────┘ │
┌─────┴──────┐
│ PostgreSQL │
└────────────┘
```
### 按需流程（带有钩子）
1. 您请求 Claude 爬取/搜索内容
2. `PreToolUse` 钩子检测到 Docker 未运行
3. 如果需要，打开 OrbStack/Docker
4. 启动容器（如果已存在则约 5 秒，首次则约 15 秒）
5. Claude 通过 MCP 正常进行爬取
6. `PostToolUse` 钩子安排 10 分钟后自动停止
7. 如果不再使用，容器停止并释放 RAM
### RAM 消耗
| 状态 | RAM |
|--------|-----|
| 停止 | 0 |
| 运行 | 约 2.5-3.5 GB |
容器限制：
- API：2 GB
- Playwright：1 GB
- Redis：128 MB
- RabbitMQ：128 MB
- PostgreSQL：256 MB
## API 参考
### POST /v1/scrape
提取 URL 内容。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-----------|
| `url` | 字符串 | （必填） | 爬取 URL |
| `formats` | 字符串数组 | `["markdown"]` | 格式：`markdown`、`html` |
| `onlyMainContent` | 布尔值 | `true` | 移除头部/页脚/侧边栏 |
| `waitFor` | 数字 | 0 | 等待 X 毫秒后再捕获（SPA） |
| `timeout` | 数字 | 30000 | 超时毫秒数 |
### POST /v1/search
搜索网页并返回内容。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-----------|
| `query` | 字符串 | （必填） | 搜索查询 |
| `limit` | 数字 | 5 | 最大结果数 |
| `lang` | 字符串 | — | 语言（例如 `pt-br`） |
| `country` | 字符串 | — | 国家（例如 `br`） |
### POST /v1/map
发现网站的所有 URL。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-----------|
| `url` | 字符串 | （必填） | 根 URL |
| `search` | 字符串 | — | 过滤 URL |
| `limit` | 数字 | — | 最大 URL 数 |
## 故障排除
### 端口 3002 上的“连接被拒绝”
Firecrawl 未运行：
```bash
./scripts/firecrawl.sh start
```
### Docker 未启动
检查 OrbStack/Docker Desktop 是否打开：
```bash
docker info
```
如果未打开：
```bash
open -a OrbStack # 或：open -a Docker
```
### 爬取返回空（包含重 JavaScript 的网站）
增加 `waitFor`：
```bash
curl -s -X POST http://localhost:3002/v1/scrape \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer fc-local' \
-d '{"url": "https://spa-site.com", "formats": ["markdown"], "waitFor": 5000}'
```
### 爬取超时
增加 `timeout`：
```bash
-d '{"url": "...", "formats": ["markdown"], "timeout": 60000}'
```
### 包含 Cloudflare 的网站
通常第一次尝试会较慢。Firecrawl 执行瀑布式：直接获取 -> Playwright（浏览器）。可能需要 ~10-15 秒。
### 完全重置
```bash
./scripts/firecrawl.sh reset # 删除所有
./install.sh # 从零重新安装
```
### 查看日志
```bash
./scripts/firecrawl.sh logs
```
## 更新
```bash
./scripts/firecrawl.sh pull # 下载最新镜像
./scripts/firecrawl.sh reset # 删除旧容器
./install.sh # 重新创建所有
```
## 项目结构
```
firecrawl-local/
├── install.sh # 完整安装程序
├── README.md # 本文件
├── .gitignore
└── scripts/
├── docker-compose.yml # 5 个容器的技术栈
├── nuq-init.sql # PostgreSQL 模式
├── firecrawl.sh # CLI（start/stop/status/test/logs/pull/reset）
├── ensure-firecrawl.sh # PreToolUse 钩子（自动启动）
├── stop-firecrawl.sh # PostToolUse 钩子（10 分钟后自动停止）
├── codex-firecrawl-mcp.sh # Codex 的 MCP 包装器
└── codex-firecrawl-mcp.cjs # 带有钩子的 Node.js MCP 代理
```
## 许可证
MIT
