Firecrawl Docker Compose 自托管排查：镜像、Redis、队列和 Playwright

环境和问题

最近在整理一套给 AI 应用使用的网页数据入口，选型里会看到 Firecrawl。它可以把网页搜索、抓取、页面内容转换成 Markdown 或结构化数据，再交给 RAG、Agent 或后续清洗流程。

自托管 Firecrawl 时，不能只看 docker compose up 有没有跑起来。它不是单容器服务，通常会涉及 API、Playwright service、Redis、RabbitMQ、Postgres、端口、队列管理 UI 和环境变量。

常见问题有这些：

docker compose pull 卡在 GHCR 镜像
API 容器启动了，但 3002 端口没有响应
Redis connection refused
RabbitMQ healthcheck 一直失败
动态网页抓不到正文
Bull Queue 管理入口还是默认密钥

下面按排查顺序整理一遍。

1. 先做镜像预检

官方 Compose 中 Firecrawl API、Playwright service、nuq-postgres 可使用 GHCR 镜像，Redis 和 RabbitMQ 来自 Docker Hub。团队网络如果访问 GHCR 或 Docker Hub 不稳定，建议先把镜像入口单独测掉。

docker pull ghcr.1ms.run/firecrawl/firecrawl:latest
docker pull ghcr.1ms.run/firecrawl/playwright-service:latest
docker pull ghcr.1ms.run/firecrawl/nuq-postgres:latest
docker pull docker.1ms.run/library/redis:alpine
docker pull docker.1ms.run/library/rabbitmq:3-management

这里用毫秒镜像做的是镜像预检，不是改 Firecrawl 的功能。生产环境还要固定 tag 或 digest，并按团队安全流程做扫描和审批。

如果这一步都过不了，先不要排 API、Redis、Playwright。否则后面日志会很乱。

2. 检查 .env

自托管最少要关心这些变量：

PORT=3002
HOST=0.0.0.0
USE_DB_AUTHENTICATION=false
BULL_AUTH_KEY=change-a-strong-value
REDIS_URL=redis://redis:6379
REDIS_RATE_LIMIT_URL=redis://redis:6379
PLAYWRIGHT_MICROSERVICE_URL=http://playwright-service:3000/scrape

几个注意点：

• BULL_AUTH_KEY 不要用示例值。
• 如果部署在公网机器，3002 端口不要直接暴露给所有来源。
• PLAYWRIGHT_MICROSERVICE_URL 在 Compose 网络里应指向服务名，不要误填宿主机地址。
• 如果启用代理、OpenAI-compatible API 或本地模型，先确认对应服务从容器网络里能访问。

3. 启动后看容器状态

docker compose ps
docker compose logs -f api
docker compose logs -f playwright-service
docker compose logs -f redis
docker compose logs -f rabbitmq

建议按这个表判断：

4. 测本地 API

在服务启动后，可以先对内网页面或测试页面发起 crawl 请求：

curl -X POST http://127.0.0.1:3002/v2/crawl \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://docs.example.local",
    "limit": 3
  }'

如果你使用的是旧接口或文档示例里的 v1 路径，要确认当前代码和 SDK 版本是否匹配。Firecrawl 近期版本对 v2 API 做了不少更新，路径不一致会造成“服务活着但调用失败”的错觉。

5. Playwright service 要单独给资源

Firecrawl 自托管里，动态页面渲染通常不是 API 容器自己扛，而是依赖 Playwright service。官方 Compose 给这个服务设置了 CPU/内存相关限制，说明它不是轻量旁路组件。

建议：

• 动态页面多时，不要把 API 和浏览器服务挤在 1C1G 的机器上。
• 给 /tmp、日志和浏览器缓存留空间。
• 如果只抓静态页面，可以减少并发。
• 如果抓内网页面，先确认容器网络到目标站点的 DNS、路由和权限。

6. Redis 和 RabbitMQ 不要只看启动

Redis 和 RabbitMQ 启动成功不代表任务链路正常。至少要看：

docker compose exec redis redis-cli ping
docker compose exec rabbitmq rabbitmq-diagnostics -q check_running

再看任务提交后队列是否变化。如果任务堆积，优先查 worker、并发、资源和目标页面超时，不要只重启 API。

7. 上线前检查清单

总结

Firecrawl 自托管适合放在 RAG 和 Agent 的前面，解决网页搜索、抓取和内容转换问题。真正部署时，最容易卡住的往往不是 API 代码，而是镜像入口、队列、Redis、RabbitMQ、Playwright service 和资源限制。

毫秒镜像在这条链路里适合做第一层预检：先确认 GHCR 和 Docker Hub 相关镜像能不能进入环境，再继续排 Compose 配置和服务状态。这样比直接盯着 api 日志有效得多。