Crawl4AI 详细部署教程

项目概述

Crawl4AI 是一个开源、面向 LLM 的网页爬虫与抓取引擎，能将网页转换为干净的、适合 LLM 处理的 Markdown 格式，专为 RAG、AI Agent 和数据管道设计。

核心特性：

  • LLM 友好输出：生成结构化 Markdown，保留标题、表格、代码等格式
  • 异步高性能：基于 Playwright 的异步浏览器池，支持并发抓取
  • 完整浏览器控制：支持会话管理、代理、Cookie、自定义脚本、钩子
  • 灵活部署：支持 pip 安装、Docker 部署、CLI 工具

最新版本：v0.9.3（安全更新版本），修复了 PDF 处理路径的任意文件写入、SSRF 和 DoS 漏洞，以及 Docker Playground 的两个 XSS 问题。

部署前准备

系统要求

项目 要求
Python 3.10+
操作系统 Windows / macOS / Linux
内存 最低 2GB，推荐 4GB+（Docker 部署需增加 shm-size）
磁盘空间 最低 2GB

环境检查

1
2
python --version
pip --version

方案一：pip 安装（推荐）

这是最简单的部署方式，适合大多数用户。

步骤 1：安装 Crawl4AI

1
pip install -U crawl4ai

步骤 2：运行安装后设置

1
crawl4ai-setup

此命令会自动安装并配置 Playwright 浏览器。

步骤 3：验证安装

1
crawl4ai-doctor

步骤 4：如果遇到浏览器问题

可以手动安装 Playwright：

1
python -m playwright install --with-deps chromium

步骤 5：快速测试

1
2
3
4
5
6
7
8
9
10
import asyncio
from crawl4ai import AsyncWebCrawler

async def main():
    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun(url="https://www.nbcnews.com/business")
        print(result.markdown)

if __name__ == "__main__":
    asyncio.run(main())

方案二：Docker 部署

Docker 部署适合隔离环境或生产部署，提供 API 服务器、监控仪表盘和 Playground。

步骤 1：拉取镜像

1
docker pull unclecode/crawl4ai:latest

步骤 2：运行容器

1
2
3
4
5
docker run -d \
  -p 11235:11235 \
  --name crawl4ai \
  --shm-size=1g \
  unclecode/crawl4ai:latest

注意：--shm-size 参数用于设置共享内存，建议至少 1GB。复杂页面或大规模抓取建议设置 3-4GB。

步骤 3：访问服务

服务 地址
监控仪表盘 http://localhost:11235/dashboard
Playground http://localhost:11235/playground

步骤 4：测试 API

1
2
3
curl -X POST http://localhost:11235/crawl \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com"]}'

使用 LLM 支持（可选）

如果需要 LLM 提取功能，创建 .llm.env 文件：

1
2
3
4
cat > .llm.env << EOL
OPENAI_API_KEY=sk-your-key
ANTHROPIC_API_KEY=your-anthropic-key
EOL

运行时挂载：

1
2
3
4
5
6
docker run -d \
  -p 11235:11235 \
  --name crawl4ai \
  --shm-size=1g \
  --env-file .llm.env \
  unclecode/crawl4ai:latest

安全注意事项（重要）

Crawl4AI 的 Docker API 服务器在 v0.9.0 版本之前默认无认证，存在多个严重安全漏洞：

漏洞类型 影响 修复版本
Chromium 启动参数注入 RCE 未认证远程代码执行 v0.9.0
流式抓取路径 SSRF 读取内部服务和云元数据 v0.9.0
PDF 处理路径漏洞 任意文件写入、SSRF、DoS v0.9.3
Docker Playground XSS 可能泄露操作员 API Token v0.9.3

安全部署建议

  1. 务必升级到 v0.9.3 或更高版本：

    1
    pip install -U crawl4ai

  2. 启用认证（v0.9.0+ 默认启用）：

    1
    2
    3
    4
    5
    6
    docker run -d \
      -p 11235:11235 \
      -e CRAWL4AI_API_TOKEN=your_secure_token \
      --name crawl4ai \
      --shm-size=1g \
      unclecode/crawl4ai:latest

  3. 不要将 API 暴露到公网：默认绑定 loopback，如需外部访问请使用反向代理并配置认证

  4. 注意 v0.9.0 的破坏性变更：extra_args、proxy、user_data_dir 等字段现在被禁止从不可信请求中设置，会返回 HTTP 400

常用 CLI 命令

1
2
3
4
5
6
7
8
# 基础抓取，输出 Markdown
crwl https://www.nbcnews.com/business -o markdown

# 深度抓取，BFS 策略，最多 10 页
crwl https://docs.crawl4ai.com --deep-crawl bfs --max-pages 10

# 使用 LLM 提取，指定问题
crwl https://www.example.com/products -q "Extract all product prices"

常见问题排查

问题 解决方案
Playwright 安装失败 运行 python -m playwright install chromium
Docker 内存不足 增加 --shm-size 参数（建议 3-4GB）
内存泄漏（Docker 环境） 已知问题，升级到最新版本；使用 MemoryAdaptiveDispatcher 控制并发
API 返回 401 v0.9.0+ 默认启用认证，检查 CRAWL4AI_API_TOKEN
PDF 处理报错 升级到 v0.9.3，PDF 下载已限制为 100MiB 和 2000 页

版本选择建议

版本 特点 推荐度
v0.9.3 最新稳定版，安全修复 ⭐⭐⭐⭐⭐
v0.9.0+ 安全默认，认证启用 ⭐⭐⭐⭐
早期版本 存在已知安全漏洞 不推荐

总结

部署方式 适用场景 难度 推荐度
pip 安装 大多数用户 ⭐ ⭐⭐⭐⭐⭐
Docker 部署 隔离环境/API 服务 ⭐⭐ ⭐⭐⭐⭐

对于大多数用户，pip 安装是最简单直接的选择：

1
2
3
4
5
6
7
8
# 安装
pip install -U crawl4ai

# 设置
crawl4ai-setup

# 验证
crawl4ai-doctor

如果使用 Docker 部署，务必升级到 v0.9.3 并配置 CRAWL4AI_API_TOKEN 认证，不要将未认证的 API 暴露到公网。