基于我最近在 Mac Studio（Apple Silicon M系列芯片）上成功部署 Firecrawl 的亲身经历，写下这篇笔记。Firecrawl 是优秀的网页爬取工具，自托管版用 Docker Compose 部署很方便，但官方仓库有一些 bug，尤其是数据库初始化部分，会导致很多人卡住（包括我折腾了好几天）。下面一步步教你正确部署，并标注所有踩过的坑。
当前日期：2025年12月12日（仓库代码在快速迭代，建议用最新 main 分支，但注意 bug）。
1. 环境准备
- 系统：macOS（Apple Silicon 如 M1/M2/M3/Mac Studio 没问题）
- 工具：
- Docker Desktop（最新版，确保启用 Rosetta 如果有兼容性问题）
- Git
- 克隆仓库：
git clone https://github.com/mendableai/firecrawl.git
cd firecrawl2. 正确部署步骤（推荐方式：全程用 docker compose）
绝对不要手动 docker run 单个容器！Firecrawl 依赖多个服务（Postgres、Redis、API、Worker 等），必须用 Compose 才能自动联网（服务名如 nuq-postgres 可互相解析）。
# 彻底清理旧残留（每次出问题必跑！）
docker compose down -v --remove-orphans
docker system prune -f
docker volume prune -f # 删除所有无用卷，小心其他项目
# 构建并启动（--build 强制重建）
docker compose up --build- 如果是后台运行：docker compose up -d –build
- 查看状态：docker compose ps 或 docker ps
- 查看日志：docker compose logs -f（重点看 nuq-postgres 的日志）
成功标志：
- 所有容器 Up
- API 日志显示 “Worker 15 listening on port 3002”
- 浏览器访问 http://localhost:3002/docs 看到 Swagger UI
3. 关键修复：修改 nuq-postgres Dockerfile（最大坑点！）
这是我遇到的核心问题，也是很多 GitHub issue 的根源（pg_cron 配置错）。
文件路径：apps/nuq-postgres/Dockerfile
找到最后这行：
printf "\n# Added for pg_cron\ncron.database_name = 'postgres'\n" >> "$conf_sample"改成
printf "\n# Added for pg_cron\ncron.database_name = 'firecrawl'\n" >> "$conf_sample"原因：
- pg_cron 默认只允许在 “postgres” 数据库创建扩展。
- Firecrawl 用的是 “firecrawl” 数据库，导致初始化脚本报错：
ERROR: can only create extension in database postgres
HINT: Add cron.database_name = 'firecrawl' ...- 容器直接退出 code 3，其他服务连不上数据库，报 ENOTFOUND nuq-postgres。
改完保存，重新 docker compose up –build 即可。
（另一个历史 bug：nuq.sql 有多余 ALTER TABLE 语句，如果你克隆的代码有，删掉最后那行 ALTER。但最新版应该已修。）
4. 其他常见坑点及解决方案
| 坑点 | 症状 | 解决方案 |
|---|---|---|
| 数据库容器 Exited (3) | postgres 初始化失败，其他服务 ENOTFOUND | 检查 docker logs firecrawl-nuq-postgres-1，99% 是 pg_cron 配置或 nuq.sql 多余语句。改 Dockerfile 如上 + 清理卷。 |
| 手动 run 容器导致连不上 | worker 报 getaddrinfo ENOTFOUND nuq-postgres | 必须用 Compose！手动 run 要自己建网络、改容器名。 |
| 残留数据卷导致重复错误 | 改代码后还是老错 | 每次大改必跑 docker compose down -v 删除卷，重初始化数据库。 |
| Apple Silicon 构建慢/失败 | cargo build 或其他编译卡住 | Docker Desktop 设置里允许 arm64，确保用最新版。有时加 platform: linux/amd64 到 compose 服务。 |
| Supabase 警告 | warn: Authentication is disabled / Supabase client not initialized | 正常！自托管版不启用 Supabase 认证和索引，不影响核心爬取功能。 |
| 端口冲突 | 5433 被占 | 杀掉占用进程，或改 compose.yml 端口映射。 |
| 构建 playwright-service 失败 | Rust/cargo 错误 | 更新仓库到最新，或用官方预构建镜像（注释 build，启用 image）。 |
5. 测试与使用
- 测试 scrape：
curl -X POST http://localhost:3002/v1/scrape -H "Content-Type: application/json" -d '{"url": "https://news.ycombinator.com"}'- Python SDK 示例：
from firecrawl import FirecrawlApp
app = FirecrawlApp(api_url="http://localhost:3002", api_key="any") # 自托管 key 随便填
print(app.scrape_url("https://example.com")['markdown'])6. 维护命令（收藏）
# 后台运行
docker compose up -d --build
# 停止
docker compose down
# 彻底重置（删数据）
docker compose down -v
# 查看特定日志
docker compose logs -f nuq-postgres
没有回复内容