Docker 部署指南

Crawl4AI 提供官方 Docker 镜像，方便部署和扩展。本指南介绍在 Docker 环境中的安装、配置和使用方法。

快速开始 🚀

拉取并运行基础版本：

# 运行无安全配置的基础版本
docker pull unclecode/crawl4ai:basic
docker run -p 11235:11235 unclecode/crawl4ai:basic
# 运行启用 API 安全的版本
docker run -p 11235:11235 -e CRAWL4AI_API_TOKEN=your_secret_token unclecode/crawl4ai:basic

使用 Docker Compose 运行 🐳

使用 Docker Compose（本地构建或 Docker Hub）

Crawl4AI 提供灵活的 Docker Compose 方案来管理容器化服务。你可以选择从提供的 Dockerfile 本地构建镜像，或者直接使用 Docker Hub 上的预构建镜像。

方案 1：使用 Docker Compose 本地构建

如果希望从本地 Dockerfile 构建镜像，请使用 docker-compose.local.yml 文件：

docker-compose -f docker-compose.local.yml up -d

该命令将执行以下操作：

1. 从 Dockerfile 构建 Docker 镜像。
2. 启动容器，并在 http://localhost:11235 提供服务。

方案 2：使用 Docker Hub 上的预构建镜像

如果你想直接使用 Docker Hub 上的官方镜像，请使用 docker-compose.hub.yml 文件：

docker-compose -f docker-compose.hub.yml up -d

该命令将执行以下操作：

1. 拉取 unclecode/crawl4ai:basic（或 all 版本，取决于你的配置）。
2. 启动容器，并在 http://localhost:11235 提供服务。

停止运行的服务

要停止通过 Docker Compose 启动的服务，可以使用以下命令：

docker-compose -f docker-compose.local.yml down
# 或
docker-compose -f docker-compose.hub.yml down

如果容器没有成功停止，应用仍在运行，可以检查正在运行的容器：

docker ps

找到 CONTAINER ID 并强制停止：

docker stop <CONTAINER_ID>

使用 Docker Compose 进行调试

• 查看日志：

docker-compose -f docker-compose.local.yml logs -f

• 移除孤立容器（如果应用仍在意外运行）：

docker-compose -f docker-compose.local.yml down --remove-orphans

• 手动移除 Docker 网络（如果网络仍被占用）：

docker network ls
docker network rm crawl4ai_default

为什么使用 Docker Compose？

Docker Compose 是推荐的部署方式，因为：

1. 简化了多容器服务的管理。
2. 允许在单个文件中定义环境变量、资源和端口。
3. 便于在本地开发与生产环境之间切换。

例如，你的 docker-compose.yml 可以包含 API 密钥、令牌设置和内存限制，使部署快速且一致。

API 安全 🔒

了解 CRAWL4AI_API_TOKEN

CRAWL4AI_API_TOKEN 用于保护 Crawl4AI 实例：

• 设置 CRAWL4AI_API_TOKEN：所有 API 端点（除 /health 以外）均需要身份验证。
• 未设置 CRAWL4AI_API_TOKEN：API 端点将公开访问。

# 启用安全性的实例
docker run -p 11235:11235 -e CRAWL4AI_API_TOKEN=your_secret_token unclecode/crawl4ai:all
# 无安全性的实例
docker run -p 11235:11235 unclecode/crawl4ai:all

API 调用示例

对于启用了安全性的实例，请在所有请求中包含 API 令牌：

import requests
# 设置请求头
api_token = "your_secret_token"  # 与 CRAWL4AI_API_TOKEN 保持一致
headers = {"Authorization": f"Bearer {api_token}"} if api_token else {}
# 发送爬取任务请求
response = requests.post(
    "http://localhost:11235/crawl",
    headers=headers,
    json={
        "urls": "https://example.com",
        "priority": 10
    }
)
# 查询任务状态
task_id = response.json()["task_id"]
status = requests.get(
    f"http://localhost:11235/task/{task_id}",
    headers=headers
)

配置选项 🔧

环境变量

可以使用环境变量配置 Crawl4AI 服务：

# 基础配置
docker run -p 11235:11235 \
    -e MAX_CONCURRENT_TASKS=5 \
    unclecode/crawl4ai:all
# 启用安全性与 LLM 支持
docker run -p 11235:11235 \
    -e CRAWL4AI_API_TOKEN=your_secret_token \
    -e OPENAI_API_KEY=sk-... \
    -e ANTHROPIC_API_KEY=sk-ant-... \
    unclecode/crawl4ai:all

使用 Docker Compose（推荐） 🐳

创建 docker-compose.yml：

version: '3.8'
services:
  crawl4ai:
    image: unclecode/crawl4ai:all
    ports:
      - "11235:11235"
    environment:
      - CRAWL4AI_API_TOKEN=${CRAWL4AI_API_TOKEN:-}  # 可选的 API 令牌
      - MAX_CONCURRENT_TASKS=5
      # LLM 提供商密钥
      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
    volumes:
      - /dev/shm:/dev/shm
    deploy:
      resources:
        limits:
          memory: 4G
        reservations:
          memory: 1G

运行方式：

1. 使用环境变量直接运行：

CRAWL4AI_API_TOKEN=secret123 OPENAI_API_KEY=sk-... docker-compose up

1. 使用 .env 文件（推荐）：

在 docker-compose.yml 文件同级目录创建 .env 文件：

# API 安全令牌（可选）
CRAWL4AI_API_TOKEN=your_secret_token
# LLM 提供商密钥
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
# 其他配置
MAX_CONCURRENT_TASKS=5

然后运行：

docker-compose up

安全提醒：如果启用了 API 令牌，请确保其安全，避免将其提交到版本控制系统中。

平台专属安装指引 💻

macOS

docker pull unclecode/crawl4ai:basic
docker run -p 11235:11235 unclecode/crawl4ai:basic

Ubuntu

# 运行基础版本
docker pull unclecode/crawl4ai:basic
docker run -p 11235:11235 unclecode/crawl4ai:basic
# 运行支持 GPU 版本
docker pull unclecode/crawl4ai:gpu
docker run --gpus all -p 11235:11235 unclecode/crawl4ai:gpu

Windows（PowerShell）

docker pull unclecode/crawl4ai:basic
docker run -p 11235:11235 unclecode/crawl4ai:basic

生产环境部署 🚀

在生产环境中运行 Crawl4AI 时，建议使用以下方法：

1. 使用 Docker Compose 进行容器管理。
2. 启用 API 令牌 以防止未经授权的访问。
3. 使用反向代理（如 Nginx 或 Traefik） 来提供 HTTPS 支持。
4. 配置持久化存储，避免数据丢失。

生产环境推荐配置（Nginx + Docker Compose）

在生产环境中，建议使用 Nginx 作为反向代理，同时使用 Docker Compose 来管理容器。

步骤 1：安装 Nginx

sudo apt update && sudo apt install -y nginx

步骤 2：配置 Nginx 作为反向代理

创建 Nginx 配置文件 /etc/nginx/sites-available/crawl4ai：

server {
    listen 80;
    server_name crawl4ai.example.com;
    location / {
        proxy_pass http://localhost:11235;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

启用 Nginx 配置并重启服务：

sudo ln -s /etc/nginx/sites-available/crawl4ai /etc/nginx/sites-enabled/
sudo systemctl restart nginx

步骤 3：使用 Docker Compose 运行 Crawl4AI

在 /opt/crawl4ai/ 目录中创建 docker-compose.prod.yml 文件：

version: '3.8'
services:
  crawl4ai:
    image: unclecode/crawl4ai:all
    restart: always
    environment:
      - CRAWL4AI_API_TOKEN=your_secret_token
      - MAX_CONCURRENT_TASKS=10
    ports:
      - "11235:11235"
    volumes:
      - /dev/shm:/dev/shm

然后运行：

docker-compose -f docker-compose.prod.yml up -d

步骤 4：启用 HTTPS（Let’s Encrypt）

安装 Certbot 并获取 SSL 证书：

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d crawl4ai.example.com

让 HTTPS 自动续期：

sudo certbot renew --dry-run

Kubernetes 部署 🛠️

如果希望在 Kubernetes（K8s） 上运行 Crawl4AI，可以使用以下 Deployment 和 Service 资源配置。

步骤 1：创建 Kubernetes 部署文件

在 crawl4ai-deployment.yml 中添加以下内容：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: crawl4ai
spec:
  replicas: 2
  selector:
    matchLabels:
      app: crawl4ai
  template:
    metadata:
      labels:
        app: crawl4ai
    spec:
      containers:
        - name: crawl4ai
          image: unclecode/crawl4ai:all
          env:
            - name: CRAWL4AI_API_TOKEN
              value: "your_secret_token"
            - name: MAX_CONCURRENT_TASKS
              value: "10"
          ports:
            - containerPort: 11235
---
apiVersion: v1
kind: Service
metadata:
  name: crawl4ai-service
spec:
  selector:
    app: crawl4ai
  ports:
    - protocol: TCP
      port: 80
      targetPort: 11235
  type: LoadBalancer

步骤 2：部署到 Kubernetes

kubectl apply -f crawl4ai-deployment.yml

步骤 3：检查部署状态

kubectl get pods
kubectl get services

日志与监控 📊

查看运行日志

使用 docker logs 命令查看运行日志：

docker logs -f <CONTAINER_ID>

如果使用 Docker Compose：

docker-compose -f docker-compose.local.yml logs -f

如果使用 Kubernetes：

kubectl logs -f deployment/crawl4ai

集成 Prometheus 监控

Crawl4AI 提供 /metrics 端点，可与 Prometheus 结合使用。

步骤 1：安装 Prometheus

docker run -d -p 9090:9090 prom/prometheus

步骤 2：配置 Prometheus 采集 Crawl4AI 指标

在 prometheus.yml 添加：

scrape_configs:
  - job_name: 'crawl4ai'
    metrics_path: '/metrics'
    static_configs:
      - targets: ['localhost:11235']

重启 Prometheus：

docker restart prometheus

常见问题 ❓

1. 容器无法启动，端口被占用？

运行以下命令检查端口占用情况：

sudo netstat -tulnp | grep 11235

如果端口被其他进程占用，可以更改端口号或停止占用进程：

sudo kill -9 <PID>

2. 如何清理 Docker 旧版本和缓存？

docker system prune -af

3. 如何重启 Crawl4AI 容器？

如果你使用的是 docker run，可以使用以下命令重启：

docker restart <CONTAINER_ID>

如果使用的是 docker-compose，可以运行：

docker-compose down
docker-compose up -d