Рецепты CLI для автоматизации браузера: практические примеры команд

Введение

CLI-флаги BotBrowser обеспечивают детальный контроль над профилями отпечатков, маршрутизацией через прокси, настройками локали, конфигурацией рендеринга и поведением автоматизации. При наличии десятков доступных флагов знание того, какие из них комбинировать для конкретных сценариев, экономит значительное время на настройку.

Эта статья собирает готовые к использованию рецепты для типичных задач. Каждый рецепт включает точную команду, объяснение того, зачем включён каждый флаг, и примечания о том, когда его использовать или модифицировать. Все рецепты предполагают, что у вас есть бинарный файл BotBrowser и файлы профилей .enc со страницы релизов GitHub.

Зачем нужны рецепты CLI

Система конфигурации BotBrowser гибка по замыслу. Вы можете переопределять практически любую настройку профиля во время запуска, маршрутизировать трафик через прокси со встроенными учётными данными, управлять поведением рендеринга и запускать несколько экземпляров из командной строки. Эта гибкость означает множество допустимых конфигураций, и поиск правильной комбинации для вашего сценария может потребовать изучения полного справочника CLI-флагов.

Рецепты устраняют разрыв между пониманием отдельных флагов и их эффективной комбинацией. Они содержат проверенные конфигурации, учитывающие типичные краевые случаи, например, обеспечение собственного каталога пользовательских данных для каждого параллельного экземпляра или сочетание настроек прокси с корректными переопределениями локали.

Система приоритетов конфигурации делает CLI-рецепты особенно мощными. CLI-флаги --bot-config-* имеют наивысший приоритет, переопределяя настройки профиля без изменения зашифрованного файла профиля. Это означает, что вы можете поддерживать небольшой набор базовых профилей и настраивать их при запуске для разных сценариев.

Техническая база

Категории флагов

Флаги BotBrowser делятся на несколько категорий:

Основные флаги (--bot-profile, --bot-profile-dir) управляют загрузкой профиля отпечатков. Каждая сессия BotBrowser начинается с одного из них.

Флаги прокси (--proxy-server, --proxy-ip, --proxy-bypass-rgx) управляют маршрутизацией сети. BotBrowser расширяет стандартный флаг прокси Chromium, поддерживая встроенные учётные данные в URL.

Флаги переопределения конфигурации (--bot-config-*) переопределяют конкретные значения из загруженного профиля. Часовой пояс, локаль, языки, бренд браузера, размеры экрана и настройки рендеринга - всё это настраиваемо.

Переключатели поведения (--bot-disable-debugger, --bot-always-active, --bot-inject-random-history и др.) управляют поведением во время выполнения, не привязанным к конкретному значению профиля.

Флаги кастомизации (--bot-title, --bot-cookies, --bot-bookmarks, --bot-script) добавляют данные, специфичные для сессии, или скрипты автоматизации.

Автоопределение

BotBrowser автоматически определяет часовой пояс, локаль и языковые настройки по IP-адресу вашего прокси. В большинстве рецептов вам не нужно указывать эти значения вручную. Переопределяйте только тогда, когда вам нужна конфигурация, отличающаяся от той, что определена по IP.

Стандартные флаги Chromium

BotBrowser также поддерживает все стандартные флаги Chromium. К часто используемым относятся --headless, --user-data-dir, --remote-debugging-port и --window-size. Они документированы в справочнике командной строки Chromium.

Рецепты

Рецепт 1: Минимальный запуск

Простейшая конфигурация BotBrowser:

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --headless

Это загружает профиль и запускает браузер в headless-режиме. Часовой пояс, локаль и языки автоматически определяются по IP вашей машины. Используйте это для локального тестирования и разработки.

Рецепт 2: Продакшен-запуск с прокси

chromium-browser \
  --bot-profile="/opt/profiles/windows-chrome-131.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --user-data-dir="/tmp/bb-session-$(date +%s)" \
  --remote-debugging-port=9222 \
  --headless

Прокси обеспечивает гео-маршрутизацию, а BotBrowser автоматически определяет часовой пояс и локаль по выходному IP прокси. Уникальный --user-data-dir предотвращает конфликты с другими экземплярами. Порт отладки позволяет программное управление через CDP.

Рецепт 3: Явная локаль и часовой пояс

Когда вам нужны конкретные региональные настройки независимо от расположения прокси:

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --bot-config-timezone="Europe/Berlin" \
  --bot-config-locale="de-DE" \
  --bot-config-languages="de-DE,de,en-US" \
  --bot-config-location="52.5200,13.4050" \
  --headless

Это переопределяет автоматически определённые значения явной немецкой конфигурацией. Полезно, когда IP вашего прокси не точно отражает нужный регион.

Рецепт 4: Многоэкземплярное развёртывание

#!/bin/bash
PROFILES_DIR="/opt/profiles/windows-chrome"
BASE_PORT=9222

for i in $(seq 1 5); do
  chromium-browser \
    --bot-profile-dir="${PROFILES_DIR}" \
    --bot-title="Worker ${i}" \
    --user-data-dir="/tmp/bb-worker-${i}" \
    --remote-debugging-port=$((BASE_PORT + i)) \
    --proxy-server=socks5://user:pass@proxy.example.com:1080 \
    --headless &
done

Каждый экземпляр получает случайный профиль из каталога, собственный каталог пользовательских данных, уникальный порт отладки и описательный заголовок для идентификации. --bot-title отображается в заголовке окна и панели задач, что упрощает идентификацию конкретных экземпляров.

Рецепт 5: Переключение бренда браузера

Представиться как Microsoft Edge вместо Chrome:

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-config-browser-brand="edge" \
  --headless

Доступные значения бренда: chrome, chromium, edge, brave, opera, webview. BotBrowser подстраивает User-Agent, заголовки Client Hints и связанные значения API под выбранный бренд.

Рецепт 6: Сессия с куки и историей

Предзаполнение браузера данными сессии:

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-cookies='[{"name":"session_id","value":"abc123","domain":".example.com"},{"name":"pref","value":"dark","domain":".example.com"}]' \
  --bot-bookmarks='[{"title":"Dashboard","type":"url","url":"https://example.com/dashboard"}]' \
  --bot-inject-random-history \
  --bot-always-active \
  --user-data-dir="/data/persistent-session" \
  --headless

--bot-cookies устанавливает начальные куки. --bot-bookmarks добавляет закладки. --bot-inject-random-history создаёт синтетическую историю просмотров для аутентичности сессии. --bot-always-active поддерживает окна активными даже при потере фокуса.

Рецепт 7: Загрузка куки из файла

Для больших наборов куки загрузка из JSON-файла:

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-cookies="@/opt/data/cookies.json" \
  --headless

Префикс @ указывает BotBrowser читать куки из указанного файла вместо разбора значения как встроенного JSON.

Рецепт 8: Детерминированный шум для воспроизводимости

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-noise-seed=42 \
  --bot-time-seed=42 \
  --bot-time-scale=0.92 \
  --headless

--bot-noise-seed делает шум Canvas, WebGL, аудио, метрик текста и ClientRect детерминированным. Один и тот же seed всегда даёт один и тот же хеш отпечатка. --bot-time-seed обеспечивает детерминированное разнообразие тайминга выполнения для операций браузера. --bot-time-scale сжимает интервалы performance.now() для снижения сигналов отслеживания на основе времени.

Рецепт 9: Запись Canvas для анализа

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-canvas-record-file="/tmp/canvas-capture.jsonl" \
  --bot-noise-seed=12345 \
  --headless

Записывает все вызовы API Canvas 2D, WebGL и WebGL2 в файл JSONL. Seed шума зафиксирован, поэтому записанный вывод воспроизводим. Используйте это для криминалистического анализа и отладки поведения отпечатков Canvas.

Рецепт 10: Автоматизация без фреймворка

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-script="/opt/scripts/automation.js" \
  --bot-disable-debugger \
  --bot-disable-console-message \
  --headless

Запускает JavaScript-файл с прямым доступом к CDP через chrome.debugger. Node.js и npm не требуются. --bot-disable-debugger предотвращает приостановку выполнения страниц инструкциями debugger. --bot-disable-console-message подавляет вывод консоли через CDP.

Рецепт 11: Headless с определённым размером окна

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-config-window="1920x1080" \
  --bot-config-screen="2560x1440" \
  --window-size=1920,1080 \
  --headless

Устанавливает как размеры окна/экрана на уровне профиля, так и размер окна Chromium. Флаги --bot-config-window и --bot-config-screen управляют тем, что сообщают JavaScript API, тогда как --window-size задаёт фактический viewport.

Рецепт 12: Приватность WebRTC с пользовательским STUN

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --bot-webrtc-ice="google" \
  --bot-local-dns \
  --headless

--bot-webrtc-ice управляет тем, какие конечные точки STUN/TURN доступны через WebRTC, предотвращая утечку локального IP. --bot-local-dns обеспечивает локальное разрешение DNS вместо использования DNS провайдера прокси.

Рецепт 13: Пользовательские HTTP-заголовки

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-custom-headers='{"X-Requested-With":"com.example.app","X-Custom-Auth":"token123"}' \
  --headless

Внедряет пользовательские заголовки во все исходящие HTTP-запросы. Полезно для аутентификации API и маршрутизации запросов.

Рецепт 14: Защита портов

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-port-protection \
  --headless

Предотвращает обнаружение удалёнными страницами работающих сервисов на localhost, блокируя сканирование портов по распространённым портам разработки и удалённого доступа.

Рецепт 15: Отладка и устранение неполадок

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-internal --v=1 \
  --enable-logging=stderr \
  --headless

Включает внутреннее логирование BotBrowser (--bot-internal --v=1) и логирование Chromium в stderr для детального диагностического вывода. Используйте при устранении проблем с конфигурацией.

Проверка

После применения любого рецепта проверьте результат, перейдя на инструмент тестирования отпечатков:

# Быстрая проверка с тестовым URL
chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --bot-noise-seed=42 \
  --remote-debugging-port=9222 \
  --headless

Затем подключитесь через CDP и перейдите на CreepJS или BrowserLeaks, чтобы убедиться, что ваша конфигурация создаёт согласованный, реалистичный отпечаток. Подробную методику тестирования смотрите в статье Как проверить защиту отпечатков браузера.

Лучшие практики

Начинайте с минимума, добавляйте флаги по мере необходимости. Начните с рецепта 1 и добавляйте флаги только при наличии конкретного требования. Ненужные флаги увеличивают сложность без пользы.

Позвольте автоопределению работать. Если вы используете прокси, BotBrowser обрабатывает часовой пояс, локаль и язык автоматически. Переопределяйте только когда автоматически определённые значения не соответствуют вашим потребностям.

Используйте --user-data-dir для каждого параллельного экземпляра. Без отдельных каталогов данных экземпляры разделяют куки, кеш и данные профиля, что приводит к непредсказуемому поведению.

Используйте --bot-title для идентификации. При запуске нескольких экземпляров заголовок упрощает определение конкретного экземпляра в логах и списках процессов.

Предпочитайте --bot-config-* вместо редактирования профиля. CLI-флаги имеют наивысший приоритет и не требуют изменения зашифрованных файлов.

Логируйте всё при разработке. Используйте --bot-internal --v=1 во время разработки и тестирования. Отключайте подробное логирование в продакшене для повышения производительности.

Часто задаваемые вопросы

Можно ли совмещать --bot-profile и --bot-profile-dir?

Нет. Если указаны оба, --bot-profile-dir имеет приоритет. Используйте --bot-profile для постоянных идентичностей и --bot-profile-dir для случайной ротации.

Что произойдёт при указании конфликтующих флагов?

CLI-флаги имеют наивысший приоритет. Если флаг противоречит значению профиля, флаг побеждает. Если два флага конфликтуют друг с другом, обычно действует последний указанный.

Как узнать, какие флаги поддерживает мой уровень лицензии?

Флаги, требующие определённого уровня, отмечены в справочнике CLI-флагов метками вроде (PRO), (ENT Tier1), (ENT Tier2) и т.д. Использование флага без необходимого уровня не имеет эффекта.

Можно ли сохранить комбинации флагов в файл?

Да. Создайте shell-скрипт или конфигурационный файл с вашими комбинациями флагов. Для Playwright/Puppeteer определите массив args в общем конфигурационном модуле.

Есть ли максимальное количество флагов?

Практического ограничения на количество флагов нет. Однако держите конфигурацию как можно проще. Каждый ненужный флаг - потенциальная точка путаницы при отладке.

Как сбросить настройки до значений по умолчанию?

Запустите без каких-либо флагов --bot-config-* для использования значений профиля по умолчанию. Запустите без --bot-profile для работы как обычный Chromium.

Эти рецепты кроссплатформенные?

Да. Одни и те же флаги работают на Windows, macOS и Linux. Подстройте имя бинарного файла (chromium-browser, chrome, chrome.exe) и формат путей для вашей платформы.

Итоги

Эти рецепты охватывают наиболее типичные конфигурации BotBrowser, от минимальных запусков для разработки до многоэкземплярных продакшен-развёртываний. Начните с простейшего рецепта, удовлетворяющего ваши потребности, и добавляйте флаги постепенно по мере роста требований.

Для более глубокого изучения конкретных тем смотрите Управление профилями для организации профилей, Настройка headless-сервера для конфигурации сервера Ubuntu, Руководство по развёртыванию в Docker для контейнерных развёртываний и Автоматизация Bot Script для автоматизации без фреймворка.