如何用 Docker Compose 10 分钟自托管 Firecrawl 网页抓取 API：完整教程
【免费下载链接】firecrawl🔥 Supercharge your AI agents with data from the web and beyond. A web data API to search, scrape, and access more sources.项目地址: https://gitcode.com/GitHub_Trending/fi/firecrawl
大量页面抓取、数据要留在自己机器上，却还要请求第三方服务，是很多人的痛点。Firecrawl 是开源网页抓取 API，你提交一个 URL，它返回干净的 Markdown 或结构化 JSON。照本教程操作，用 Docker Compose 自托管 Firecrawl 全程 10 分钟，并完成第一次抓取。
开始之前
动手前逐条确认，全部打勾再往下走：
- 已安装 Docker 与 Compose 插件，
docker compose version能打印出版本号。 - 机器可用内存不低于 4GB、磁盘剩余不低于 20GB（首次构建 5 个镜像体积不小）。
- 宿主机 3002 端口未被占用：
curl -s http://localhost:3002/无响应或连接拒绝即为空闲。 - 网络可拉取 Docker 基础镜像；若走代理或镜像源，先配置好再开始。
- 使用 Linux/macOS 时终端有管理员权限。
任何一条不满足，先解决再继续，后面的报错大多源自这里。
主流程 🚀
克隆代码仓库
git clone https://gitcode.com/GitHub_Trending/fi/firecrawl cd firecrawl看到什么算成功：目录下能直接看到 docker-compose.yaml 和 SELF_HOST.md 两个文件。
启动整套服务
docker compose up -d首次会构建 API、Playwright 服务、队列数据库等镜像，耗时 10~30 分钟。看到什么算成功：执行
docker compose ps，api与各 worker 均为 running/healthy。卡在建镜像阶段不动，直接查文末「出问题了」表格。验证 API 入口
curl -s http://localhost:3002/看到什么算成功：返回包含
"message": "Firecrawl API"的 JSON，说明网关已通。发出第一次抓取
curl -s http://localhost:3002/v1/scrape \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com","formats":["markdown"]}'看到什么算成功：响应
success为true，data.markdown里有完整正文。更多请求形态可参考仓库里的 apps/api/requests/v2/scrape.requests.http。图里重点看右侧 200 响应：markdown、links、screenshot 等字段就是自托管实例实际会吐出的结构。
用 map 端点收尾验证
curl -s http://localhost:3002/v1/map \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com","limit":2}'看到什么算成功：返回 2 条站点 URL 的列表。到此，Firecrawl 自托管部署完成。
参数速查
以下值与根目录 Compose 文件默认值一致，改参数只需在根目录建.env覆盖同名变量：
| 参数 | 推荐值 | 为什么是这个值 |
|---|---|---|
| PORT | 3002 | 默认唯一对外发布的端口，改它不影响内部通信 |
| USE_DB_AUTHENTICATION | false | 首次自托管保持默认；开启前需先备好数据库鉴权结构 |
| NUM_WORKERS_PER_QUEUE | 8 | 每个队列的并行 worker 数，队列消费速度的上限 |
| CRAWL_CONCURRENT_REQUESTS | 10 | 一次 crawl 同时抓取的 URL 数，太高内存先爆 |
| MAX_CONCURRENT_JOBS | 5 | 同时执行的大任务数，防止多任务互抢浏览器 |
| BROWSER_POOL_SIZE | 5 | Playwright 浏览器实例池大小，直接决定内存占用 |
| NUQ_BACKEND | 留空（pg） | 队列跑在自带的 PostgreSQL 上，多机再考虑切换 |
三种常见场景，只改这几个数：
- 2 核 4GB 轻机：NUM_WORKERS_PER_QUEUE 改 4，CRAWL_CONCURRENT_REQUESTS 改 4，BROWSER_POOL_SIZE 改 2，MAX_CONCURRENT_JOBS 改 2。
- 对外公网暴露：只加两件事——按 SELF_HOST.md 配齐鉴权并把 USE_DB_AUTHENTICATION 设为 true，再加一层 TLS 终结；默认 API 无认证，不能裸奔。
- 批量抓取压测：CRAWL_CONCURRENT_REQUESTS 提到 20、BROWSER_POOL_SIZE 提到 10，跑一轮看内存曲线，稳了再往上加。
为什么这么配
- 并发参数是联动的：worker 数、URL 并发、浏览器池都吃内存，单抬一个只会让另两个排队。
- 队列默认走自带 PostgreSQL，任务状态与抓取结果同源，多节点扩展才需要 FoundationDB。
- 默认只暴露 API 一个端口，其余服务留在内部网络，暴露面最小。
出问题了 🛠️
排查前先跑docker compose ps和docker compose logs <服务名>，资源水位可以参考仓库里的监控图表：
图里重点看尖峰出现时利用率是否长期贴着 100%，那就是并发参数超标的信号。
| 现象 | 原因 | 处理 |
|---|---|---|
| 3002 端口连不上 | 端口被占用或未启动 | 换宿主机 PORT 为 3003，内部端口保持 3002 不变 |
| 构建拉镜像失败 | 基础镜像源网络不通 | 配置 Docker 镜像加速器后重新docker compose up -d |
| 根路径正常但 /v1/scrape 502 或超时 | Playwright 服务未就绪或页面过重 | 先抓静态页验证链路，再看docker compose logs playwright-service |
| crawl 一直排队不完成 | NuQ PostgreSQL 不健康 | docker compose ps nuq-postgres确认 healthy，异常则看其日志 |
| 内存超 4GB 触发 OOM | 浏览器池或并发过大 | BROWSER_POOL_SIZE 降到 2~3，CRAWL_CONCURRENT_REQUESTS 降到 4 |
| 部分页面抓取失败 | 目标站点限流反爬 | 降低并发、请求间加重试，再评估是否配 PROXY_SERVER |
收尾自查
curl http://localhost:3002/返回 Firecrawl API 的 JSON- 第一次 scrape 拿到了完整 markdown 正文
docker compose ps全部服务 running，日志无持续报错- 记录了你当前使用的并发参数，作为后续调优的基线
- 如需对外暴露，已按 SELF_HOST.md 完成鉴权与 TLS
跑通之后可以往两个方向走：用 cron 表达式把抓取排成定期任务，配合 apps/api/requests/v2/crawl.requests.http 里的请求样例做定时 crawl；
图里重点看五个星号的位置，分、时、日、月、周，定时抓取任务就靠它描述。
正式上多节点或集群时，参考仓库内 examples/kubernetes/cluster-install/ 的清单与 examples/kubernetes/firecrawl-helm/ 的 Helm 图。
【免费下载链接】firecrawl🔥 Supercharge your AI agents with data from the web and beyond. A web data API to search, scrape, and access more sources.项目地址: https://gitcode.com/GitHub_Trending/fi/firecrawl
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
