Пайплайны RAG (Retrieval-Augmented Generation), локальные LLM и автономные ИИ-агенты бесполезны без качественных структурированных данных. Но сбор информации из современного интернета превратился в инженерный кошмар: Single Page Applications (React, Vue, Next.js), бесконечные DOM-деревья, тонны рекламного мусора, навигационных обвесов и скриптов отслеживания ломают классические парсеры на базе BeautifulSoup или Scrapy. Firecrawl — это современный open-source движок от Mendable (более 200 000 звёзд на GitHub), который берет любой URL, поднимает под капотом изолированный headless-браузер Chromium, дожидается выполнения клиентских скриптов и возвращает чистый, семантически выверенный Markdown, готовый к векторизации и передаче в нейросети.
Облачная версия Firecrawl Cloud тарифицируется по подписке (от $16 до $99 в месяц и выше при серьезных объемах краулинга). Развертывание Firecrawl на собственном VDS в Docker Compose полностью снимает лимиты на число спарсенных страниц, гарантирует конфиденциальность собираемых данных согласно 152-ФЗ и исключает зависимость от зарубежных платформ и карт.
Проблема RAG-ингестии: почему BeautifulSoup и Requests больше не работают
При построении корпоративных баз знаний и RAG-систем инженеры сталкиваются с тремя фундаментальными барьерами веб-скрапинга:
- Клиентский рендеринг (Client-Side Rendering): более 70% современных SaaS-документаций и веб-порталов генерируют контент через JavaScript. Простой HTTP-запрос через
curl,requestsили парсерBeautifulSoupвозвращает пустой тег<div id="root"></div>или лоадер. - Информационный шум и перерасход токенов: в необработанном HTML полезный контент статьи занимает от 5% до 15% общего объема документа. Остальное — шапки, сайдбары, баннеры, футеры, SVG-иконки и скрипты аналитики. Если скармливать сырой HTML в языковую модель напрямую, контекстное окно LLM мгновенно переполняется мусором, стоимость запросов растет в 10 раз, а ретривер извлекает нерелевантные фрагменты.
- Сложность рекурсивного обхода (Deep Crawl): чтобы спарсить техническую документацию целиком, требуется краулер, который умеет находить внутренние ссылки, следовать sitemap.xml, фильтровать пути по регулярным выражениям, сохранять статус задач и обрабатывать сбои сетевых запросов.
Firecrawl решает эти задачи «под ключ»: микросервис на базе Playwright полностью отрисовывает страницу, встроенный движок очистки вырезает весь визуальный шум, а конвертер преобразует семантическое дерево в чистый GitHub Flavored Markdown (включая таблицы, ссылки, заголовки и блоки кода) или строгий структурированный JSON по заданной JSON-схеме.
| Критерий / Инструмент | Firecrawl (Self-Hosted) | Crawl4AI | BeautifulSoup + Requests | Firecrawl Cloud (SaaS) |
|---|---|---|---|---|
| Рендеринг JS / SPA | Да (Playwright Chromium) | Да (Playwright) | Нет (только статичный HTML) | Да (облачный кластер) |
| Рекурсивный краулинг | Да (RabbitMQ + NuQ/Postgres) | Базовый (asyncio) | Требует внешней обвязки | Да (по подписке) |
| Преобразование в Markdown | Идеальное GFM + таблицы | Хорошее GFM | Ручное через html2text | Идеальное GFM |
| Формат API | REST API (OpenAPI 3.0) | Python SDK / CLI | Библиотека Python | REST API |
| Лимиты и стоимость | Безлимитно (цена VDS ~600-900 ₽/мес) | Безлимитно | Безлимитно | От $16 до $99+/мес |
| Конфиденциальность (152-ФЗ) | 100% изоляция на вашем сервере в РФ | 100% изоляция | 100% изоляция | Данные уходят на серверы США |
Архитектура Firecrawl и требования к ресурсам VDS
Архитектура self-hosted релиза Firecrawl спроектирована как распределенный микросервисный стек:
playwright-service: TypeScript-микросервис, управляющий пулом инстансов headless-браузера Chromium. Отвечает за открытие страниц, ожидание селекторов, выполнение пользовательских JavaScript-действий и снятие DOM-снимка.api(Harness Engine): основное ядро на Node.js. Включает REST API контроллер, оркестратор задач скрапинга и воркеры извлечения контента (extract worker, crawl worker).rabbitmq: высокопроизводительный брокер очередей сообщений для координации фоновых краулинг-задач.nuq-postgres: база данных PostgreSQL, выступающая надежным бэкендом очереди NuQ для долгоживущих краулов.redis: оперативный кэш и хранилище состояний для rate limiting.
Так как headless-браузер Chromium требователен к оперативной памяти при загрузке тяжелых страниц, правильный расчет ресурсов VDS критически важен для стабильности.
| Профиль нагрузки | Конфигурация VDS | Параметры параллелизма | Рекомендуемое применение |
|---|---|---|---|
| Минимальный (Solo/Dev) | 2 vCPU, 2 ГБ RAM, 20 ГБ NVMe, 2 ГБ Swap | MAX_CONCURRENT_PAGES=2, CRAWL_CONCURRENT=2 |
Точечный скрапинг статей, одиночные URL, тесты RAG |
| Оптимальный (Production) | 2-4 vCPU, 4 ГБ RAM, 40 ГБ NVMe | MAX_CONCURRENT_PAGES=5, CRAWL_CONCURRENT=5 |
Краулинг средних сайтов (100–500 страниц), парсинг документаций |
| Высоконагруженный (Batch RAG) | 4-8 vCPU, 8 ГБ RAM, 80 ГБ NVMe | MAX_CONCURRENT_PAGES=10, CRAWL_CONCURRENT=10 |
Полномасштабный сбор обучающих датасетов, непрерывный мониторинг |
Для надежного развертывания в российских реалиях отлично подходят проверенные провайдеры с быстрыми NVMe-дисками и изолированными портами: Timeweb Cloud, Selectel или Beget.
Подготовка VDS и файловой структуры
Для развертывания рекомендуется свежий образ Ubuntu 24.04 LTS или Debian 12. Подключитесь к серверу по SSH и подготовьте изолированную директорию:
# 1. Обновляем пакеты и создаем структуру директорий
sudo apt update && sudo apt upgrade -y
sudo mkdir -p /opt/firecrawl/{data,logs,scripts}
cd /opt/firecrawl
# 2. Если Docker Compose еще не установлен:
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
Если на вашем VDS доступно только 2 ГБ оперативной памяти, обязательно создайте файл подкачки (Swap) на 2–4 ГБ. Это предотвратит аварийное завершение Chromium процессом OOM (Out-Of-Memory Killer) при обработке тяжелых сайтов:
# Создание Swap-файла на 2 ГБ (для тарифов с 2 ГБ RAM)
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
Создайте конфигурационный файл .env. Для защиты паролей можно использовать наш встроенный генератор сложных паролей SysKit:
# Переходим в рабочую директорию
cd /opt/firecrawl
# Создаем файл переменных окружения
cat <<'EOF' > .env
# Секретный ключ для авторизации API-запросов к вашему инстансу
TEST_API_KEY=fc_sec_syskit_live_token_77a94f
# Базовые сетевые порты (привязка строго к локальной петле 127.0.0.1)
PORT=3002
INTERNAL_PORT=3002
# Параметры очередей и параллелизма (оптимизировано под 2-4 vCPU / 4 ГБ RAM)
NUM_WORKERS_PER_QUEUE=4
CRAWL_CONCURRENT_REQUESTS=5
MAX_CONCURRENT_JOBS=3
BROWSER_POOL_SIZE=3
# Параметры подключения к внутренним базам данных стека
REDIS_URL=redis://redis:6379
POSTGRES_USER=firecrawl_admin
POSTGRES_PASSWORD=FireCrawl_Secure_Pass_2026!
POSTGRES_DB=firecrawl_db
POSTGRES_HOST=nuq-postgres
POSTGRES_PORT=5432
# Отключение внешней Supabase-аутентификации (автономный режим)
USE_DB_AUTHENTICATION=false
ENV=local
EOF
# Защищаем права доступа к файлу с паролями
chmod 600 .env
Боевой манифест docker-compose.yml с ограничением ресурсов
Создадим файл /opt/firecrawl/docker-compose.yml. Обратите внимание на ключевые инженерные решения безопасности:
- Порт API
3002проброшен строго на127.0.0.1:3002:3002. Это гарантирует, что сервис не торчит наружу и защищен от прямого обхода брандмауэра UFW. Доступ к нему будет осуществляться через обратный прокси Nginx с шифрованием SSL. - Для контейнеров установлены жесткие лимиты
mem_limitиcpus, что гарантирует стабильность всей операционной системы. - Используются стабильные предсобранные официальные образы ветки
v2.11.0из реестра GitHub Container Registry (GHCR).
cat <<'EOF' > docker-compose.yml
services:
playwright-service:
image: ghcr.io/firecrawl/playwright-service:v2.11.0
restart: unless-stopped
environment:
PORT: 3000
MAX_CONCURRENT_PAGES: ${CRAWL_CONCURRENT_REQUESTS:-5}
BLOCK_MEDIA: "true"
networks:
- firecrawl-internal
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
cpus: 1.5
mem_limit: 1536M
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
api:
image: ghcr.io/firecrawl/firecrawl:v2.11.0
restart: unless-stopped
environment:
REDIS_URL: ${REDIS_URL}
REDIS_RATE_LIMIT_URL: ${REDIS_URL}
PLAYWRIGHT_MICROSERVICE_URL: http://playwright-service:3000/scrape
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: ${POSTGRES_DB}
POSTGRES_HOST: ${POSTGRES_HOST}
POSTGRES_PORT: ${POSTGRES_PORT}
USE_DB_AUTHENTICATION: "false"
TEST_API_KEY: ${TEST_API_KEY}
NUM_WORKERS_PER_QUEUE: ${NUM_WORKERS_PER_QUEUE}
CRAWL_CONCURRENT_REQUESTS: ${CRAWL_CONCURRENT_REQUESTS}
MAX_CONCURRENT_JOBS: ${MAX_CONCURRENT_JOBS}
BROWSER_POOL_SIZE: ${BROWSER_POOL_SIZE}
HOST: "0.0.0.0"
PORT: 3002
EXTRACT_WORKER_PORT: 3004
WORKER_PORT: 3005
NUQ_RABBITMQ_URL: amqp://rabbitmq:5672
HARNESS_STARTUP_TIMEOUT_MS: 60000
ENV: local
depends_on:
redis:
condition: service_started
playwright-service:
condition: service_started
rabbitmq:
condition: service_healthy
nuq-postgres:
condition: service_healthy
ports:
# Защита портов: биндинг строго на 127.0.0.1
- "127.0.0.1:3002:3002"
command: node dist/src/harness.js --start-docker
cpus: 1.5
mem_limit: 1024M
networks:
- firecrawl-internal
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
redis:
image: redis:7-alpine
restart: unless-stopped
command: redis-server --save "" --appendonly no
mem_limit: 256M
networks:
- firecrawl-internal
logging:
driver: "json-file"
options:
max-size: "5m"
max-file: "2"
rabbitmq:
image: rabbitmq:3-management-alpine
restart: unless-stopped
healthcheck:
test: ["CMD", "rabbitmq-diagnostics", "-q", "check_running"]
interval: 10s
timeout: 5s
retries: 5
start_period: 15s
mem_limit: 512M
networks:
- firecrawl-internal
logging:
driver: "json-file"
options:
max-size: "5m"
max-file: "2"
nuq-postgres:
image: ghcr.io/firecrawl/nuq-postgres:latest
restart: unless-stopped
environment:
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: ${POSTGRES_DB}
volumes:
- nuq-pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
interval: 10s
timeout: 5s
retries: 5
start_period: 10s
mem_limit: 512M
networks:
- firecrawl-internal
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
networks:
firecrawl-internal:
driver: bridge
volumes:
nuq-pgdata:
EOF
Запуск контейнеров и диагностика готовности
Запустите стек в фоновом режиме и отслеживайте процесс инициализации очередей и миграций:
# Запуск стека в фоне
docker compose up -d
# Проверка статуса контейнеров (все сервисы должны быть Up / healthy)
docker compose ps
# Просмотр логов ядра API
docker compose logs -f api
После того как контейнер api выведет сообщение о готовности harness-воркеров, выполните тестовый запрос к локальному эндпоинту проверки здоровья:
# Проверка доступности локального API
curl -s http://127.0.0.1:3002/v1/health | jq .
В ответ вернется статус {"status": "ok"}. Сервисный стек готов к маршрутизации внешних запросов через Nginx.
Настройка Nginx Reverse Proxy и SSL-сертификата
Для безопасного взаимодействия с API из внешних скриптов настроим Nginx в качестве обратного прокси. Для глубоких операций краулинга (краулинг 20–50 страниц) время ответа может составлять десятки секунд, поэтому критически важно увеличить директивы proxy_read_timeout и proxy_connect_timeout до 600 секунд.
Установите Nginx и certbot, если они еще не установлены:
sudo apt install -y nginx certbot python3-certbot-nginx
Создайте файл конфигурации виртуального хоста /etc/nginx/sites-available/firecrawl.conf (замените firecrawl.example.com на ваш рабочий домен):
cat <<'EOF' | sudo tee /etc/nginx/sites-available/firecrawl.conf
server {
listen 80;
server_name firecrawl.example.com;
# Редирект на HTTPS
location / {
return 301 https://$host$request_uri;
}
}
server {
listen 443 ssl http2;
server_name firecrawl.example.com;
# Пути к сертификатам Let's Encrypt
ssl_certificate /etc/letsencrypt/live/firecrawl.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/firecrawl.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_prefer_server_ciphers on;
# Максимальный размер тела запроса (для передачи HTML/JSON)
client_max_body_size 50M;
location / {
proxy_pass http://127.0.0.1:3002;
proxy_http_version 1.1;
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;
# Критично для долгих задач краулинга (10 минут)
proxy_connect_timeout 600s;
proxy_send_timeout 600s;
proxy_read_timeout 600s;
# Отключение буферизации для SSE-стриминга результатов
proxy_buffering off;
proxy_cache off;
}
}
EOF
Активируйте сайт и выпустите бесплатный SSL-сертификат Let's Encrypt:
# Активируем конфигурацию
sudo ln -sf /etc/nginx/sites-available/firecrawl.conf /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
# Выпускаем SSL-сертификат с автоматическим редиректом
sudo certbot --nginx -d firecrawl.example.com --redirect
После выпуска сертификата проверьте корректность цепочки и протокола TLS через бесплатный онлайн SSL-чекер SysKit, а также убедитесь в отсутствии циклических перенаправлений с помощью утилиты проверки редиректов.
Практическая работа с API: скрапинг, краулинг и маппинг сайтов
Firecrawl предоставляет элегантный REST API v1 с тремя ключевыми методами:
1. Точечный скрапинг страницы в чистый Markdown (/v1/scrape)
Метод выполняет рендеринг страницы, удаляет мусор и возвращает очищенный Markdown с метаданными (заголовок, описание, OpenGraph):
curl -X POST https://firecrawl.example.com/v1/scrape \
-H "Authorization: Bearer fc_sec_syskit_live_token_77a94f" \
-H "Content-Type: application/json" \
-d '{
"url": "https://syskit.ru",
"formats": ["markdown"],
"onlyMainContent": true
}'
В ответе вернется структурированный JSON:
{
"success": true,
"data": {
"markdown": "# SysKit — Инженерные онлайн-утилиты для DevOps\n\nКомплекс сетевых инструментов...",
"metadata": {
"title": "SysKit — Диагностика сети, хостинга и генераторы конфигураций",
"description": "Бесплатные сетевые чекеры, DNS, SSL и калькуляторы для системных администраторов",
"statusCode": 200
}
}
}
2. Автоматическое составление карты ссылок сайта (/v1/map)
Метод /v1/map мгновенно обходит sitemap.xml и robots.txt, возвращая полный плоский список доступных URL без необходимости скачивать сами страницы. Это идеальный шаг перед организацией избирательного скрапинга:
curl -X POST https://firecrawl.example.com/v1/map \
-H "Authorization: Bearer fc_sec_syskit_live_token_77a94f" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"search": "docs"
}'
3. Асинхронный краулинг целого раздела или домена (/v1/crawl)
Для парсинга целых порталов запускается фоновое задание. API возвращает идентификатор задачи id, по которому опрашивается статус готовности:
# 1. Запуск задачи краулинга до 20 страниц
JOB_ID=$(curl -s -X POST https://firecrawl.example.com/v1/crawl \
-H "Authorization: Bearer fc_sec_syskit_live_token_77a94f" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/docs",
"limit": 20,
"scrapeOptions": {
"formats": ["markdown"],
"onlyMainContent": true
}
}' | jq -r .id)
echo "ID задачи краулинга: $JOB_ID"
# 2. Проверка статуса выполнения задачи
curl -s -X GET "https://firecrawl.example.com/v1/crawl/$JOB_ID" \
-H "Authorization: Bearer fc_sec_syskit_live_token_77a94f" | jq .status
Интеграция с Python, LangChain и локальными LLM
Официальная библиотека firecrawl-py поддерживает прямое указание адреса вашего собственного сервера через параметр api_url:
pip install firecrawl-py langchain-community langchain-text-splitters
Пример скрипта на Python, который загружает документацию через ваш self-hosted Firecrawl и нарезает её на чанки для векторной базы:
from firecrawl import FirecrawlApp
from langchain_text_splitters import MarkdownHeaderTextSplitter
# Инициализируем клиент с адресом вашего self-hosted VDS
app = FirecrawlApp(
api_key="fc_sec_syskit_live_token_77a94f",
api_url="https://firecrawl.example.com"
)
# Скрапим страницу в семантический Markdown
result = app.scrape_url(
'https://example.com/documentation/quickstart',
params={'formats': ['markdown'], 'onlyMainContent': True}
)
markdown_text = result['markdown']
print(f"Получено символов: {len(markdown_text)}")
# Интеллектуальное дробление по заголовкам H1, H2, H3
headers_to_split_on = [
("#", "Header 1"),
("##", "Header 2"),
("###", "Header 3"),
]
markdown_splitter = MarkdownHeaderTextSplitter(headers_to_split_on=headers_to_split_on)
docs = markdown_splitter.split_text(markdown_text)
print(f"Сформировано чанков для RAG: {len(docs)}")
for i, doc in enumerate(docs[:3]):
print(f"\n--- Чанк {i+1} ---")
print("Метаданные:", doc.metadata)
print("Текст:", doc.page_content[:150], "...")
Автоматизация резервного копирования и очистки кэша
Для сохранения конфигураций и истории очередей краулинга создадим автоматический скрипт резервного копирования /usr/local/bin/backup-firecrawl.sh. Скрипт сохраняет дамп базы данных PostgreSQL (где хранятся метаданные очередей NuQ), конфигурационный файл .env и упаковывает их в tar.gz-архив с ротацией за 7 дней.
Для создания универсальных скриптов резервного копирования других Docker-проектов используйте наш генератор bash-скриптов бэкапа Docker-томов.
cat <<'EOF' | sudo tee /usr/local/bin/backup-firecrawl.sh
#!/usr/bin/env bash
set -euo pipefail
BACKUP_DIR="/var/backups/firecrawl"
DATE=$(date +%Y%m%d_%H%M%S)
APP_DIR="/opt/firecrawl"
mkdir -p "$BACKUP_DIR"
echo "[$(date)] Запуск резервного копирования Firecrawl..."
# 1. Дамп базы данных очередей NuQ PostgreSQL
docker compose -f "$APP_DIR/docker-compose.yml" exec -T nuq-postgres \
pg_dump -U firecrawl_admin firecrawl_db | gzip > "$BACKUP_DIR/nuq_db_$DATE.sql.gz"
# 2. Архивирование файлов конфигурации и окружения
tar -czf "$BACKUP_DIR/config_$DATE.tar.gz" -C "$APP_DIR" .env docker-compose.yml
# 3. Удаление резервных копий старше 7 дней
find "$BACKUP_DIR" -type f -name "*.gz" -mtime +7 -delete
echo "[$(date)] Резервное копирование успешно завершено."
EOF
# Делаем скрипт исполняемым
sudo chmod +x /usr/local/bin/backup-firecrawl.sh
Добавьте запуск бэкапа в системный планировщик cron (ежедневно в 03:30 ночи):
# Добавляем задачу в crontab root
(sudo crontab -l 2>/dev/null; echo "30 3 * * * /usr/local/bin/backup-firecrawl.sh >> /var/log/firecrawl_backup.log 2>&1") | sudo crontab -
Так как Chromium активно использует временные кэши страниц, рекомендуется периодически очищать остановленные контейнеры и неиспользуемые Docker-образы:
# Очистка неиспользуемых слоев и временных данных Docker
docker system prune -af --volumes
Чек-лист готовности Firecrawl к промышленной эксплуатации
Перед запуском масштабного сбора данных для корпоративной RAG-системы сверьтесь с контрольным списком инженерных настроек:
| Компонент | Рекомендуемая настройка | Зачем это нужно |
|---|---|---|
| Сетевая изоляция | Порты 127.0.0.1:3002:3002 |
Исключает прямой доступ сканеров и ботов к API в обход брандмауэра UFW. |
| Авторизация API | Криптографический токен в TEST_API_KEY |
Защищает ваш сервер от несанкционированного расхода вычислительных ресурсов. |
| Лимиты ресурсов | mem_limit: 1536M на Playwright |
Защищает операционную систему сервера от падения по OOM Killer при рендеринге тяжелых сайтов. |
| Файл подкачки (Swap) | Минимум 2 ГБ Swap на NVMe | Амортизирует пиковые скачки потребления RAM во время параллельного запуска 5+ страниц Chromium. |
| Таймауты Nginx | proxy_read_timeout 600s; |
Предотвращает ошибки 504 Gateway Timeout при рекурсивном парсинге глубоких веток документации. |
| Логирование | json-file, max-size: 10m, max-file: 3 |
Предотвращает переполнение дискового пространства логами Playwright и API воркеров. |
Для дальнейшего расширения ИИ-стека на вашем VDS рекомендуем ознакомиться с нашими руководствами по развертыванию высокоскоростной векторной базы данных Qdrant в Docker Compose и серверного парсера PDF-документов Docling от IBM, а также воспользоваться генератором конфигураций Nginx Reverse Proxy для стандартизации инфраструктуры.
Рекомендуемые VDS-провайдеры
Отказоустойчивые сервера с быстрыми NVMe и каналом до 1 Гбит/с
Timeweb Cloud — Скоростные NVMe VDS для Firecrawl и Playwright
Высокоскоростные накопители NVMe, низкая задержка в РФ, защита от DDoS, сеть 1 Гбит/с и удобное S3-хранилище для бэкапов.
Selectel — Корпоративная инфраструктура и аттестация 152-ФЗ
Высокая отказоустойчивость Tier III, строгое соответствие 152-ФЗ УЗ-1, приватные подсети и моментальные снимки дисков.
Beget — Надежные VDS с удобным управлением и Docker
Посуточная тарификация без переплат, быстрый запуск готовых Docker-образов и отзывчивая круглосуточная поддержка.