Как установить и настроить Crawl4AI на VPS

MAATRIX

Развернуть Crawl4AI на ноутбуке получается за пять минут — а через день браузер съедает всю память, IP улетает в бан после первой сотни запросов к одному домену, а сам процесс без присмотра гибнет вместе с закрытой сессией терминала. На чистом VPS установка Crawl4AI занимает столько же времени, но краулер после неё работает сутками без вас. Разберём установку по шагам — от venv и системных библиотек Chromium до Docker-сервиса с HTTP API, с реальными текстами ошибок и честным счётом по ресурсам.

Что такое Crawl4AI и зачем ставить его на сервер

Crawl4AI — открытый Python-фреймворк для краулинга сайтов под задачи LLM: он не просто скачивает HTML, а сразу отдаёт чистый Markdown, структурированные данные по CSS-схеме или результат LLM-извлечения. Под капотом — Playwright с headless Chromium, поэтому Crawl4AI честно рендерит JavaScript: React- и Vue-сайты, бесконечную прокрутку, контент, который подгружается через fetch уже после загрузки страницы.

В отличие от облачных API вроде Firecrawl, Crawl4AI — это библиотека, а не сервис с готовым эндпоинтом в интернете: сервер под неё поднимаете вы сами. Зато нет ни лимита запросов в месяц, ни платы за страницу, ни чужого журнала логов с вашими URL и результатами.

Именно поэтому его редко держат на рабочем ноутбуке дольше тестового скрипта. Headless Chromium — это полноценный браузерный процесс, а не лёгкий HTTP-клиент: на паре десятков страниц он ощутимо ест RAM и CPU, конкурируя с остальными вашими программами. Домашний или офисный IP один на все сайты, которые вы дёргаете, — и после первой сотни запросов к одному домену вы получаете капчу или бан по адресу. А сама задача обычно подразумевает процесс, который работает сутками без присмотра, — ноутбук для этого не приспособлен: закрыли крышку, уснул Wi-Fi, оборвалась SSH-сессия — краулинг встал.

Ниже — установка Crawl4AI на чистый VPS с Ubuntu 24.04 или Debian 12: подготовка системы, сам pip-пакет, Docker-вариант с HTTP API и ошибки, с которыми вы почти наверняка столкнётесь на голом сервере.

Подготовка VPS: Python, venv и системные библиотеки для Chromium

Обновите систему и проверьте версию Python — Crawl4AI требует Python 3.9 и новее, а у Ubuntu 24.04 (Python 3.12) и Debian 12 (Python 3.11) это в любом случае не проблема:

sudo apt update && sudo apt upgrade -y
python3 --version

Дальше первая типичная засада — она же причина, по которой «обычный» pip install не работает на свежем сервере. Ubuntu 24.04 и Debian 12 запрещают ставить пакеты в системный Python напрямую — срабатывает PEP 668:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

Обходить это флагом --break-system-packages не стоит: рано или поздно ломаются системные утилиты, которые тоже написаны на Python. Правильный путь — виртуальное окружение:

sudo apt install -y python3-venv python3-pip git
python3 -m venv ~/crawl4ai-env
source ~/crawl4ai-env/bin/activate

Дальше pip в venv работает как обычно, без единого системного пакета. После каждого нового SSH-подключения окружение нужно активировать заново — source ~/crawl4ai-env/bin/activate перед любой командой crawl4ai или python3.

Установка Crawl4AI: pip, crawl4ai-setup и crawl4ai-doctor

Сам пакет ставится одной командой внутри venv:

pip install -U crawl4ai

Следом обязательно запустите crawl4ai-setup — это не формальность, а отдельный шаг, который pip install сам не выполняет: он скачивает сборку headless Chromium для Playwright и проверяет системные зависимости.

crawl4ai-setup

Если пропустить этот шаг и сразу запустить краулинг, Playwright откажется запускать браузер:

Error: BrowserType.launch: Executable doesn't exist at
/root/.cache/ms-playwright/chromium-1187/chrome-linux/chrome
╔═══════════════════════════════════════════════════════════╗
║ Looks like Playwright Test or Playwright was just installed ║
║ or updated. Please run the following command to download    ║
║ new browsers:                                                ║
║                                                               ║
║     playwright install                                       ║
╚═══════════════════════════════════════════════════════════╝

Номер сборки (chromium-1187) у вас будет свой — это версия конкретного релиза Playwright, не опечатка.

На минимальном образе Ubuntu или Debian сама бинарь Chromium может скачаться, а вот системных библиотек для её запуска ещё нет — тогда ошибка другая, уровнем ниже, от динамического линковщика:

error while loading shared libraries: libnss3.so: cannot open
shared object file: No such file or directory

Лечится одной командой от root или через sudo — она ставит весь пакет зависимостей для нужного браузера через apt, без ручного перечисления полутора десятков библиотек:

sudo playwright install-deps chromium
crawl4ai-setup

Финальная проверка — crawl4ai-doctor: команда прогоняет тестовый краулинг example.com и по очереди отчитывается о версии Python, наличии браузера Playwright и сетевом доступе. Если все три пункта прошли — установка Crawl4AI закончена, можно писать первый скрипт.

Первый краулинг и настройка через Python: BrowserConfig и CrawlerRunConfig

Минимальный рабочий пример — асинхронная функция вокруг AsyncWebCrawler:

import asyncio
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode

async def main():
    browser_conf = BrowserConfig(headless=True, verbose=True)
    run_conf = CrawlerRunConfig(cache_mode=CacheMode.BYPASS)

    async with AsyncWebCrawler(config=browser_conf) as crawler:
        result = await crawler.arun(url="https://example.com", config=run_conf)
        print(result.markdown.raw_markdown[:500])

asyncio.run(main())

python3 crawl_test.py

headless=True в BrowserConfig — не опция, а необходимость: на сервере без графического окружения headless=False упадёт с ошибкой запуска дисплея, если заранее не поднять xvfb. Для обычного краулинга это и не нужно — видимый режим полезен только при локальной отладке селекторов на своей машине.

Отдельная ловушка — обращение к результату. В актуальных версиях result.markdown — не строка, а объект MarkdownGenerationResult: у него есть .raw_markdown (сырой перевод HTML в Markdown) и .fit_markdown (после фильтрации шаблонных блоков вроде меню и подвала). Код из старого туториала, где result.markdown печатали напрямую как строку, в новых релизах либо работает случайно за счёт __str__, либо ломается на конкатенации — берите за привычку сразу писать result.markdown.raw_markdown.

CacheMode.BYPASS в примере — не для красоты: по умолчанию Crawl4AI кеширует результат по URL на диск, и при повторном запуске скрипта во время отладки вы получаете старую версию страницы, а не свежий запрос. Для регулярного обновления данных BYPASS — обычно то, что нужно; включайте кеш только когда действительно гоняете одни и те же URL несколько раз в рамках одной сессии.

Docker-развёртывание: Crawl4AI как HTTP-сервис

Библиотека внутри Python-скрипта удобна, пока краулер вызываете вы сами. Как только к нему должны обращаться несколько сервисов — n8n, бэкенд, другой сервер, — проще поднять Crawl4AI Docker-образом как отдельный HTTP-сервис со своим API:

docker pull unclecode/crawl4ai:latest
docker run -d --name crawl4ai \
  -p 11235:11235 \
  --shm-size=1g \
  unclecode/crawl4ai:latest

Флаг --shm-size=1g здесь не для галочки. Docker по умолчанию выделяет контейнеру всего 64 МБ /dev/shm, а Chromium активно использует разделяемую память — на первой же тяжёлой странице браузер падает молча, а краулинг зависает или обрывается с ошибкой закрытого контекста. Без этого флага проблема воспроизводится почти гарантированно, и это не особенность именно Crawl4AI — та же болезнь у любого headless Chrome в контейнере, будь то Puppeteer или Selenium.

Проверка, что сервис поднялся:

curl http://127.0.0.1:11235/health

Сам краулинг — запрос к /crawl с телом в JSON:

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

Актуальную схему запроса и полный список эндпоинтов удобнее смотреть не в статье, а в /playground самого контейнера — свежая версия образа иногда добавляет параметры быстрее, чем обновляются сторонние мануалы в интернете.

Отдельно про безопасность: по умолчанию контейнер слушает 0.0.0.0:11235 без единой проверки, кто стучится. Задайте CRAWL4AI_API_TOKEN при запуске — сервис начнёт требовать заголовок Authorization: Bearer <токен> на каждый запрос — и не открывайте порт наружу без него:

docker run -d --name crawl4ai \
  -p 127.0.0.1:11235:11235 \
  --shm-size=1g \
  -e CRAWL4AI_API_TOKEN=$(openssl rand -hex 24) \
  --restart unless-stopped \
  unclecode/crawl4ai:latest

Публикация 127.0.0.1:11235:11235 вместо голого 11235:11235 ограничивает доступ localhost-ом; наружу сервис отдаётся уже через Nginx с TLS и вашей авторизацией, а не напрямую в интернет.

Частые проблемы: /dev/shm, память, антибот-защита и LLM-ключи

Память при параллельном краулинге. Один headless-контекст Chromium на простой странице обычно укладывается в 300–500 МБ RAM, на тяжёлых SPA с кучей скриптов и картинок — больше. Crawl4AI умеет краулить пачками через arun_many() с параметром max_session_permit — и вот здесь на сервере с 1–2 ГБ RAM легко словить OOM: несколько параллельных контекстов плюс сам процесс Python быстро выбирают память, ядро убивает процесс, а в dmesg остаётся строка вида Out of memory: Killed process ... (python3). Решение простое и неприятное одновременно: либо снижаете max_session_permit до 1–2, либо берёте сервер с запасом по RAM, а не по CPU — процессор здесь почти всегда свободен, узкое место в памяти.

Антибот-защита. Cloudflare, DataDome и подобные системы умеют отличать headless-браузер от живого пользователя даже с валидным Chromium под капотом: вместо страницы вы получаете интерстишл с заголовком Just a moment... и HTTP-статусом 403 вместо 200. В CrawlerRunConfig есть флаг magic=True — по документации проекта он включает набор эвристик против детекта: имитацию поведения пользователя, автоматическое закрытие cookie-баннеров, подмену части браузерных признаков. Помогает не всегда: против серьёзно защищённых сайтов ни один headless-краулер, включая Crawl4AI, гарантий не даёт — там уже нужна ротация резидентных прокси, а это отдельная и куда более дорогая задача.

LLM-извлечение просит собственные ключи. LLMExtractionStrategy в Crawl4AI работает через LiteLLM, и строка провайдера повторяет его формат: openai/gpt-4o-mini, anthropic/claude-sonnet-4-5. Без переменной окружения вида OPENAI_API_KEY вы получите ошибку авторизации ещё на уровне LiteLLM, а не самого Crawl4AI — сам краулинг страницы при этом полностью отработает, упадёт только шаг извлечения.

Полностью локальный вариант без единого внешнего ключа — Ollama на том же сервере: LLMConfig(provider="ollama/qwen2.5:7b", base_url="http://127.0.0.1:11434"). Здесь важно трезво спланировать ресурсы, а не полагаться на «CPU справится» — тем более что извлечение из краулинга устроено обычно наоборот, чем чат: на входе длинный текст страницы, на выходе короткий JSON, то есть важна скорость обработки промпта, а не только генерации. По нашим замерам на AMD EPYC 9554 (16 vCPU = 8 физических ядер с HT, Ollama 0.33.1, модель qwen2.5:7b в квантовании Q4_K_M) обработка промпта при num_thread 2/4/8/16 растёт с 12,6 до 31,0 / 61,7 / 68,0 токена в секунду — почти линейно до 8–16 потоков. А вот генерация выходит на полку уже на 4 потоках (5,7 → 7,6 → 7,6 → 7,4 ток/с) — упирается в память, не в CPU. Выставленные вручную 32 потока на этих же 16 vCPU обваливают обе метрики: генерация падает до 0,35 ток/с, обработка промпта — до 10,9. Вывод для сервера с Crawl4AI и Ollama на борту: не задирайте num_thread выше числа реальных vCPU, а по памяти сама модель qwen2.5:7b в Q4_K_M весит около 5,1 ГБ резидентно — и это поверх того, что уже просит Chromium.

Какой сервер под Crawl4AI брать в MAATRIX

Crawl4AI — не инференс-сервис, а браузерная нагрузка: считает не столько CPU, сколько RAM на Chromium-контексты и NVMe под кеш и логи. Требования разные в зависимости от того, что именно вы строите.

Честный минимум: 2 vCPU, 4 ГБ RAM, 40 ГБ NVMe. Хватает на pip-установку из venv, последовательный краулинг (max_session_permit=1–2) и периодические задачи без Docker. Ограничение прямое: 1–2 ГБ, как показано выше, — почти гарантированный OOM при первой же параллельной пачке страниц, поэтому ниже 4 ГБ конфигурацию честно не рекомендуем даже для теста.

Комфортный вариант: 4–8 vCPU, 8–16 ГБ RAM, 80–100 ГБ NVMe. Помещаются Docker-контейнер с несколькими одновременными контекстами, запас под скачки памяти на тяжёлых страницах и логи за недели работы. Если добавляете локальное LLM-извлечение через Ollama — берите верхнюю границу, 16 ГБ: модель вроде qwen2.5:7b в Q4_K_M сама по себе занимает около 5 ГБ, и это не считая Chromium и системных процессов.

Локация — Великобритания (Лондон). Дело не только в самом браузере: если извлечение идёт через облачный LLM, у OpenAI, Anthropic и Google есть региональные ограничения по IP — у OpenAI это прямая ошибка 403 unsupported_country_region_territory на российский адрес. Сервер за рубежом снимает вопрос сразу для всей цепочки, а не только для браузерной части. Лондон даёт короткий маршрут до большинства сайтов западного интернета и до API основных LLM-провайдеров — заметно короче, чем из России, и без вопросов к трансграничной передаче данных при обработке чужого контента.

Crawl4AI не входит в каталог готовых приложений apps.maatrix.io — сервер приходит чистым, с Ubuntu 24.04 или Debian 12, и вы ставите библиотеку сами по шагам выше, это буквально pip install и пара команд на десять минут. А вот смежные инструменты в каталоге уже есть готовыми сборками: Ollama и LiteLLM поднимаются одной кнопкой из личного кабинета, доступы приходят сразу. Если план — весь конвейер «краулинг → локальная LLM-обработка» из раздела выше, эти два компонента разворачивать руками не придётся, останется поставить только сам Crawl4AI поверх.

Оплата — картой российского банка, по СБП или криптовалютой; иностранная карта для сервера в Лондоне не нужна.

Частые вопросы