Crawl4AI Docker 容器化部署指南

关注

原创最新推荐文章于 2026-09-06 15:29:49 发布 1.2k 阅读 AI 写同款· GEO 优化 ›

Docker 部署 - Crawl4AI 文档 (v0.5.x) 本文介绍了如何使用 Docker 部署 Crawl4AI 服务，提供了快速入门指南和详细配置选项。用户可以通过 Docker 直接运行基础版本，或使用 Docker Compose 进行本地构建或从 Docker Hub 拉取预构建镜像。文章还强调了 API 安全性的重要性，建议通过设置 CRAWL4AI_API_TOKEN 来保护 API 端点。此外，提供了环境变量配置和 Docker Compose 文件的示例，帮助用户灵活管理服务。最后，文章展示了如何测试部署，确保服务正常运行。阅读详情

概述

Crawl4AI 是一款开源的LLM友好型网络爬虫和抓取工具，专为LLMs（大型语言模型）、AI代理和数据管道设计。作为GitHub上的热门项目，Crawl4AI 由活跃的社区维护，具备以下核心特点：

高性能：提供极速的网页抓取能力，满足实时数据处理需求
AI适配：原生支持与LLM集成，数据输出格式适合AI模型处理
灵活性：支持自定义配置、浏览器配置文件和过滤规则
易部署：通过Docker容器化方案实现快速部署和扩展

本文将详细介绍 Crawl4AI 的Docker容器化部署流程，包括环境准备、镜像拉取、容器部署、功能测试及生产环境优化建议，帮助开发者快速上手并应用于实际项目中。

环境准备

Docker环境安装

Crawl4AI 基于Docker容器化部署，首先需要在目标服务器上安装Docker环境。推荐使用以下一键安装脚本，适用于主流Linux发行版：

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

脚本执行过程中可能需要sudo权限，请根据提示完成操作。安装完成后，可通过以下命令验证Docker是否正常运行：

docker --version  # 检查Docker版本
systemctl status docker  # 检查Docker服务状态

镜像准备

拉取Crawl4AI镜像

使用以下命令通过轩辕镜像访问支持地址拉取最新版本的CRAWL4AI镜像：

docker pull xxx.xuanyuan.run/unclecode/crawl4ai:latest

如需指定版本，可参考CRAWL4AI镜像标签列表选择合适的标签。镜像支持多架构（amd64、arm64），可自动适配不同硬件平台。

容器部署

基础部署命令

使用以下命令启动Crawl4AI容器，这是官方推荐的基础部署方式：

docker run -d \
  -p 11235:11235 \
  --name crawl4ai \
  --shm-size=3g \
  xxx.xuanyuan.run/unclecode/crawl4ai:latest

参数说明：

-d：后台运行容器
-p 11235:11235：端口映射，将容器内11235端口映射到主机11235端口
--name crawl4ai：指定容器名称为crawl4ai，便于后续管理
--shm-size=3g：设置共享内存大小为3GB，优化浏览器渲染性能

高级配置选项

根据实际需求，可添加以下可选参数进行定制化部署：

1. 持久化配置文件

如需保存自定义配置，可挂载本地目录到容器内：

docker run -d \
  -p 11235:11235 \
  --name crawl4ai \
  --shm-size=3g \
  -v /path/to/local/config:/app/config \
  xxx.xuanyuan.run/unclecode/crawl4ai:latest

2. 环境变量配置

CRAWL4AI支持通过环境变量配置LLM服务（如OpenAI、Claude、Groq等），可使用-e参数传递：

docker run -d \
  -p 11235:11235 \
  --name crawl4ai \
  --shm-size=3g \
  -e OPENAI_API_KEY=your_api_key \
  -e GROQ_API_KEY=your_groq_key \
  xxx.xuanyuan.run/unclecode/crawl4ai:latest

或通过挂载.llm.env文件批量配置环境变量：

docker run -d \
  -p 11235:11235 \
  --name crawl4ai \
  --shm-size=3g \
  -v /path/to/.llm.env:/app/.llm.env \
  xxx.xuanyuan.run/unclecode/crawl4ai:latest

功能测试

服务可用性验证

容器启动后，首先检查容器运行状态：

docker ps -f name=crawl4ai

若状态为Up，表示容器正常运行。接着通过以下方式验证服务可用性：

1. 访问Web控制台

打开浏览器访问 http://localhost:11235/playground（如部署在远程服务器，将localhost替换为服务器IP），可看到CRAWL4AI的交互式测试界面，用于配置爬虫参数、测试抓取任务和生成JSON配置。

2. API调用测试

使用curl命令测试基础抓取功能：

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

若服务正常，将返回包含抓取结果的JSON响应。

3. 流式结果测试

测试流式抓取功能，实时获取结果：

curl -N -X POST http://localhost:11235/crawl/stream \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com"], "crawler_config": {"type": "CrawlerRunConfig", "params": {"stream": true}}}'

日志查看

如遇到服务异常，可通过查看容器日志定位问题：

docker logs crawl4ai
# 实时查看日志
docker logs -f crawl4ai

生产环境建议

资源配置优化

内存设置：根据抓取任务复杂度调整--shm-size参数，复杂页面或大规模抓取建议设置为4GB以上
CPU分配：通过--cpus参数限制CPU使用，避免资源占用过高：--cpus=2（限制为2核）
重启策略：添加--restart=always参数，确保容器异常退出后自动重启

docker run -d \
  -p 11235:11235 \
  --name crawl4ai \
  --shm-size=4g \
  --cpus=2 \
  --restart=always \
  xxx.xuanyuan.run/unclecode/crawl4ai:latest

数据安全与持久化

配置文件备份：定期备份挂载的配置目录，防止自定义配置丢失
敏感信息管理：通过环境变量或.llm.env文件管理API密钥等敏感信息，避免硬编码
数据存储：对于大规模抓取结果，建议配置外部数据库存储，避免容器内数据丢失

监控与维护

健康检查：结合Docker的--health-cmd参数实现基本健康检查：

docker run -d \
  -p 11235:11235 \
  --name crawl4ai \
  --shm-size=3g \
  --health-cmd "curl -f http://localhost:11235/health || exit 1" \
  --health-interval=30s \
  --health-timeout=10s \
  --health-retries=3 \
  xxx.xuanyuan.run/unclecode/crawl4ai:latest