Crawl4AI 保姆级部署教程：为 RAG 量身打造的开源爬虫

Crawl4AI（GitHub 约 8.7 万 Star）是目前 GitHub 上星标最高的爬虫项目，官方定位是「LLM-ready web crawling」：它把网页直接转成 LLM 友好的干净 Markdown，而不是一坨 HTML。与传统爬虫不同，它内置浏览器自动化、内容过滤、结构化抽取、深度爬取，专门为 RAG 数据管道设计。本文基于官方 README 的 Installation 章节。

一、项目介绍与适用场景

Crawl4AI 是一个Python 库 + 自托管服务器：你可以 pip install 后在代码里调，也可以用 Docker 起一个 HTTP API 服务，给你的 RAG 系统喂网页数据。

典型场景：

• 给 RAG 知识库喂网页：把文档站、博客整站爬成 Markdown 入库。
• 替代 Firecrawl 自托管：官方 Docker 提供 REST API 与 MCP 接口。
• 数据抽取：用 CSS/XPath 或 LLM 把网页转成结构化 JSON。
• 反爬对抗：内置 stealth 模式和 undetected-browser 适配器。

二、核心功能逐条拆解

1. 干净 Markdown 输出：自动去掉菜单、页脚、样板文字。
2. 结构化抽取：CSS/XPath schema，或 LLM 抽取成 JSON。
3. 深度爬取：BFS/DFS/best-first，支持断点续爬。
4. 浏览器控制：Chromium/Firefox/WebKit，stealth 模式，代理轮换。
5. Docker 服务器：REST API /md /html /crawl /screenshot /pdf，带 token 鉴权。
6. MCP 接口：Claude Code、Cursor 等 Agent 直接调用。
7. CLI 工具 crwl：命令行直接爬网页。

三、全套官方链接

四、硬件与环境前置要求

• Python：3.9+（pip 方式）。
• 内存：2GB 起步，浏览器爬取建议 4GB。
• 磁盘：2GB。
• 系统：Linux / macOS / Windows 均可；Docker 方式支持 AMD64 和 ARM64。

五、多平台部署步骤

5.1 pip 安装（官方推荐库方式）

官方 README 原文三步：

pip install -U crawl4ai
crawl4ai-setup        # installs the browser, once
crawl4ai-doctor       # checks the installation

逐段解释：pip install -U crawl4ai 装库；crawl4ai-setup 自动安装 Playwright 浏览器；crawl4ai-doctor 体检安装。

如果浏览器 setup 失败，官方给手动命令：

python -m playwright install --with-deps chromium

5.2 Docker 服务器（官方推荐自托管方式）

官方 README 原文：

export CRAWL4AI_API_TOKEN="$(openssl rand -hex 32)"
docker run -d -p 11235:11235 --name crawl4ai --shm-size=1g \
  -e CRAWL4AI_API_TOKEN="$CRAWL4AI_API_TOKEN" \
  unclecode/crawl4ai:latest

逐段解释：openssl rand -hex 32 生成随机 token；--shm-size=1g 给 Chromium 共享内存；-p 11235:11235 暴露端口；环境变量注入 token。官方说明：没有 token 时只在容器内部响应。

测试：

curl -s http://localhost:11235/md \
  -H "Authorization: Bearer $CRAWL4AI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://news.ycombinator.com"}' | jq -r .markdown

官方说明：dashboard 在 http://localhost:11235/dashboard，playground 在 http://localhost:11235/playground。

5.3 CLI 工具

官方 README 示例：

# 一个页面转 Markdown
crwl https://news.ycombinator.com -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"

六、配置文件全部参数解释

七、启动、后台常驻与开机自启

7.1 启动

Docker：docker run -d 已后台；pip：写 Python 脚本。

7.2 后台常驻

Docker 加 --restart=always。

7.3 开机自启

Docker 服务自启。

7.4 修改端口

改 -p 左边端口。

八、功能实操教程

第 1 步：按 5.2 启动 Docker 服务。

第 2 步：浏览器访问 http://localhost:11235/dashboard。

第 3 步：在 playground 输入 https://news.ycombinator.com，看返回的 Markdown。

第 4 步：用 curl 把 Markdown 喂给你的 RAG 系统。

第 5 步：pip 方式写一个 Python 脚本：

import asyncio
from crawl4ai import AsyncWebCrawler

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

asyncio.run(main())

第 6 步：接 Claude Code MCP：

claude mcp add --transport http crawl4ai http://localhost:11235/mcp \
  --header "Authorization: Bearer $CRAWL4AI_API_TOKEN"

九、全套报错故障排查

1. 报错原文：crawl4ai-setup 失败 原因分析：系统依赖缺失。 解决方案：python -m playwright install --with-deps chromium。

2. 报错原文：Docker 启动后 Chrome 崩溃 原因分析：--shm-size 太小。 解决方案：加 --shm-size=1g。

3. 报错原文：curl 返回 401 原因分析：token 未带或错误。 解决方案：Header 加 Authorization: Bearer $CRAWL4AI_API_TOKEN。

4. 报错原文：爬 JS 重页面只返回空壳 原因分析：未等 JS 渲染。 解决方案：用 --wait-for 或 scan_full_page 参数。

5. 报错原文：目标网站检测到爬虫 原因分析：被反爬。 解决方案：启用 stealth 模式或换代理。

十、升级、回滚与卸载

升级：pip install -U crawl4ai；Docker docker pull unclecode/crawl4ai:latest。

卸载：docker rm -f crawl4ai；pip uninstall crawl4ai。

十一、商用许可与合规风险提示

Crawl4AI 采用 Apache-2.0，商用友好。注意：爬取第三方网站时需遵守目标网站 robots 协议与版权法。

参考链接：

• Crawl4AI GitHub README：https://github.com/unclecode/crawl4ai
• 官方文档：https://docs.crawl4ai.com
• 自托管指南：https://docs.crawl4ai.com/core/self-hosting/