Firecrawl 私有化一键部署操作手册

📦 部署文件下载

如上述链接无法直接下载，请关注公众号联系我获取。

1. 环境准备

操作系统：推荐 Linux 或 macOS，Windows 建议用 WSL2
Docker：建议 20.10 及以上
Docker Compose：建议 V2（即 docker compose 命令）
网络：服务器需能访问外网拉取镜像

检查版本：

docker --version
docker compose version

2. 获取与配置部署文件

下载本页顶部的 docker-compose.yaml 和 .env 文件，放入同一目录（如 firecrawl-deploy/）。
用文本编辑器打开 .env，根据实际需求填写相关参数：
- 仅需用到的功能填写对应 KEY，未用到可留空。
- 如需代理访问外网，填写 PROXY_SERVER、PROXY_USERNAME、PROXY_PASSWORD。

3. 一键启动服务

在部署目录下执行：

docker compose up -d

首次启动会自动拉取镜像，耐心等待。
启动后会自动创建以下服务：
- api：主服务（默认 3002）
- worker：任务处理
- playwright-service：网页爬取
- redis：缓存数据库

4. 服务验证与常用命令

访问 http://localhost:3002，如能打开即部署成功。
查看服务状态：
```
docker compose ps
```
查看日志：
```
docker compose logs -f
```
重启服务：
```
docker compose restart
```
停止并移除：
```
docker compose down
```

5. 端口与网络说明

默认 API 端口为 3002，可在 .env 修改 PORT。
所有服务通过 backend 网络互联，无需额外配置。
如需暴露其他端口，请调整 docker-compose.yaml 的 ports 配置。

6. 常见问题与排查

1. 镜像拉取慢或失败？

检查服务器网络，必要时配置代理。
镜像已用华为云加速，国内网络一般无需额外加速。

2. 服务端口无法访问？

检查防火墙/安全组，确保 3002 端口已开放。
检查 .env 端口配置与 docker-compose.yaml 是否一致。

3. 日志报错如何排查？

用 docker compose logs -f 查看详细日志。
检查环境变量是否填写正确。

4. 如何升级服务？

停止服务：docker compose down
拉取新镜像：docker compose pull
重新启动：docker compose up -d

7. 进阶配置建议

Redis 持久化：如需持久化 Redis 数据，请在 docker-compose.yaml 的 redis 服务下添加数据卷挂载。
自定义镜像：如需自定义或升级服务，请修改 docker-compose.yaml 中的镜像地址。
安全加固：生产环境建议配置防火墙、定期更换密钥。

8. 参考资料

附录：配置文件示例

docker-compose.yaml 示例

name: firecrawl

x-common-service: &common-service
  image: swr.cn-north-4.myhuaweicloud.com/ddn-k8s/ghcr.io/mendableai/firecrawl:latest
  ulimits:
    nofile:
      soft: 65535
      hard: 65535
  networks:
    - backend
  extra_hosts:
    - "host.docker.internal:host-gateway"

x-common-env: &common-env
  REDIS_URL: ${REDIS_URL:-redis://redis:6379}
  REDIS_RATE_LIMIT_URL: ${REDIS_URL:-redis://redis:6379}
  PLAYWRIGHT_MICROSERVICE_URL: ${PLAYWRIGHT_MICROSERVICE_URL:-http://playwright-service:3000/scrape}
  USE_DB_AUTHENTICATION: ${USE_DB_AUTHENTICATION}
  OPENAI_API_KEY: ${OPENAI_API_KEY}
  OPENAI_BASE_URL: ${OPENAI_BASE_URL}
  MODEL_NAME: ${MODEL_NAME}
  MODEL_EMBEDDING_NAME: ${MODEL_EMBEDDING_NAME}
  OLLAMA_BASE_URL: ${OLLAMA_BASE_URL}
  SLACK_WEBHOOK_URL: ${SLACK_WEBHOOK_URL}
  BULL_AUTH_KEY: ${BULL_AUTH_KEY}
  TEST_API_KEY: ${TEST_API_KEY}
  POSTHOG_API_KEY: ${POSTHOG_API_KEY}
  POSTHOG_HOST: ${POSTHOG_HOST}
  SUPABASE_ANON_TOKEN: ${SUPABASE_ANON_TOKEN}
  SUPABASE_URL: ${SUPABASE_URL}
  SUPABASE_SERVICE_TOKEN: ${SUPABASE_SERVICE_TOKEN}
  SELF_HOSTED_WEBHOOK_URL: ${SELF_HOSTED_WEBHOOK_URL}
  SERPER_API_KEY: ${SERPER_API_KEY}
  SEARCHAPI_API_KEY: ${SEARCHAPI_API_KEY}
  LOGGING_LEVEL: ${LOGGING_LEVEL}
  PROXY_SERVER: ${PROXY_SERVER}
  PROXY_USERNAME: ${PROXY_USERNAME}
  PROXY_PASSWORD: ${PROXY_PASSWORD}
  SEARXNG_ENDPOINT: ${SEARXNG_ENDPOINT}
  SEARXNG_ENGINES: ${SEARXNG_ENGINES}
  SEARXNG_CATEGORIES: ${SEARXNG_CATEGORIES}

services:
  playwright-service:
    #image: ghcr.io/mendableai/playwright-service:latest
    image:  swr.cn-north-4.myhuaweicloud.com/ddn-k8s/ghcr.io/mendableai/playwright-service:latest
    environment:
      PORT: 3000
      PROXY_SERVER: ${PROXY_SERVER}
      PROXY_USERNAME: ${PROXY_USERNAME}
      PROXY_PASSWORD: ${PROXY_PASSWORD}
      BLOCK_MEDIA: ${BLOCK_MEDIA}
    networks:
      - backend

  api:
    <<: *common-service
    environment:
      <<: *common-env
      HOST: "0.0.0.0"
      PORT: ${INTERNAL_PORT:-3002}
      FLY_PROCESS_GROUP: app
      ENV: local
    depends_on:
      - redis
      - playwright-service
    ports:
      - "${PORT:-3002}:${INTERNAL_PORT:-3002}"
    command: [ "pnpm", "run", "start:production" ]

  worker:
    <<: *common-service
    environment:
      <<: *common-env
      FLY_PROCESS_GROUP: worker
      ENV: local
    depends_on:
      - redis
      - playwright-service
      - api
    command: [ "pnpm", "run", "workers" ]

  redis:
    image: swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/redis:7.0.12
    networks:
      - backend
    command: redis-server --bind 0.0.0.0

networks:
  backend:
    driver: bridge

.env 示例

REDIS_URL=redis://redis:6379
PLAYWRIGHT_MICROSERVICE_URL=http://playwright-service:3000/scrape
USE_DB_AUTHENTICATION=false
OPENAI_API_KEY=
OPENAI_BASE_URL=
MODEL_NAME=
MODEL_EMBEDDING_NAME=
OLLAMA_BASE_URL=
SLACK_WEBHOOK_URL=
BULL_AUTH_KEY=
TEST_API_KEY=
POSTHOG_API_KEY=
POSTHOG_HOST=
SUPABASE_ANON_TOKEN=
SUPABASE_URL=
SUPABASE_SERVICE_TOKEN=
SELF_HOSTED_WEBHOOK_URL=
SERPER_API_KEY=
SEARCHAPI_API_KEY=
LOGGING_LEVEL=info
PROXY_SERVER=
PROXY_USERNAME=
PROXY_PASSWORD=
SEARXNG_ENDPOINT=
SEARXNG_ENGINES=
SEARXNG_CATEGORIES=
PORT=3002
INTERNAL_PORT=3002
BLOCK_MEDIA=false

📦 部署文件下载​

目录​

1. 环境准备​

2. 获取与配置部署文件​

3. 一键启动服务​

4. 服务验证与常用命令​

5. 端口与网络说明​

6. 常见问题与排查​

7. 进阶配置建议​

8. 参考资料​

附录：配置文件示例​

docker-compose.yaml 示例​

.env 示例​

📦 部署文件下载

目录

1. 环境准备

2. 获取与配置部署文件

3. 一键启动服务

4. 服务验证与常用命令

5. 端口与网络说明

6. 常见问题与排查

7. 进阶配置建议

8. 参考资料

附录：配置文件示例

docker-compose.yaml 示例

.env 示例