SSD Nodes Learn Hosting plans →
Руководства Matt ConnorАвтор: Matt Connor

Запуск headless-браузера на VPS для AI-агентов

Настройка Chromium на сервере часто вызывает ошибки из-за нехватки /dev/shm, проблем с песочницей и отсутствия шрифтов. Узнайте, как правильно сконфигурировать среду для агентов.

Что вы запускаете

Headless-браузер на VPS — это Chromium без окна, которым управляет ваш код, а не пользователь. На сервере это долгоживущая иерархия процессов, с которой ваш агент взаимодействует через локальный сокет. Установка выполняется одной командой. Основная работа начинается после этого. Вы ограничиваете ресурсы, которые браузер может использовать на машине, и не выставляете его управляющую конечную точку в публичный Интернет.

В этом руководстве предполагается, что выбор инструмента уже сделан и теперь его нужно эксплуатировать. Если вы ещё сравниваете краулеры и средства извлечения данных, начните с самостоятельно размещаемых альтернатив Firecrawl, а затем вернитесь к этому руководству. Ниже используется Chromium из Playwright, поскольку Playwright поставляется со своей сборкой браузера и собственным установщиком зависимостей. Поэтому одни и те же команды работают на чистом Ubuntu VPS и внутри контейнера. В командах зафиксирована версия Playwright 1.62 — это был актуальный релиз в августе 2026 года.

Установка Chromium без догадок о зависимостях

npm i -D playwright@1.62.0
npx playwright install --with-deps chromium

--with-deps запускает apt для общих библиотек и шрифтов, необходимых Chromium, и запрашивает права root на этом этапе. Сам браузер загружается в ~/.cache/ms-playwright для пользователя, который выполнил команду. На сервере это важно, потому что пользователь сервиса обычно отличается от пользователя, под которым вы входите в систему. Один раз установите системные пакеты с правами администратора с помощью sudo npx playwright install-deps chromium, затем задайте PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers и в команде установки, и в юните сервиса, чтобы использовать одну общую копию. Если сервис не может получить доступ к браузеру, при запуске он завершается с сообщением, в котором указан путь, по которому выполнялся поиск.

Зафиксируйте версию Playwright. Каждый выпуск связан с одной сборкой браузера, поэтому незакреплённый npm update может заменить браузер у работающего сервиса. В августе 2026 актуальной была версия Playwright 1.62. По состоянию на 17 октября 2026 последний выпуск — 1.64.1, поэтому перед изменением зафиксированной версии прочитайте примечания к выпуску. На серверах ARM64 обратите внимание, что в версии 1.63 были переименованы каталоги браузеров. Это важно для профиля AppArmor, который рассматривается ниже.

Существуют две сборки Chromium, и это разные программы. В headless-режиме Playwright по умолчанию использует headless shell — двоичный файл меньшего размера, который работает только без графического интерфейса. Обычная установка загружает его рядом с полной версией браузера, а npx playwright install --with-deps --only-shell устанавливает только shell. Полную версию браузера устанавливает канал chromium. В документации Playwright по браузерам он назван «настоящим браузером Chrome, поэтому он более аутентичен, надёжен и предоставляет больше возможностей». Используйте shell для массовой загрузки данных. Используйте полную версию браузера, если сайт ведёт себя иначе и нужно выяснить причину.

Почему headless-браузер завершается с ошибкой в контейнере

Docker выделяет каждому контейнеру 64 MB /dev/shm. В документации Docker это указано явно: «Если размер не задан, система использует значение 64m». Chromium передаёт отображаемое содержимое между своими процессами через эту область shared memory, поэтому одна тяжёлая страница может полностью её заполнить. После этого процесс renderer завершается, а клиент сообщает о сбое target на странице, которая нормально работает на вашем ноутбуке. Перед изменением настроек проверьте размер изнутри контейнера.

df -h /dev/shm

Есть два рабочих исправления. Это альтернативы, а не настройки, которые нужно применять одновременно. --ipc=host помещает контейнер в IPC namespace хоста, поэтому он использует /dev/shm хоста, размер которого обычно составляет половину RAM. В руководстве Playwright по Docker рекомендуется этот вариант, поскольку без него «Chromium может исчерпать память и завершиться с ошибкой». Недостаток заключается в отказе от IPC isolation между контейнером и хостом. --shm-size=1g сохраняет private namespace и просто увеличивает размер mount.

docker run --rm -it --init --ipc=host --user pwuser mcr.microsoft.com/playwright:v1.62.0-noble /bin/bash

Флаг --disable-dev-shm-usage — это решение, которое вы найдёте в большинстве результатов поиска. Но он выполняет другую задачу: переносит эти файлы из /dev/shm во временный каталог. Если /tmp находится на диске, сбой заменяется более медленным рендерингом и операциями записи на диск. Если /tmp — это tmpfs, данные снова хранятся в RAM. Их размер ограничен только лимитом tmpfs, который документация kernel по умолчанию устанавливает равным половине физической RAM. Страницы tmpfs также могут быть выгружены в swap. Так browser может быстро исчерпать память небольшого VPS. Вместо этого правильно задайте размер /dev/shm.

Что на самом деле означает --no-sandbox

Chromium изолирует каждый renderer в sandbox, созданной на основе Linux user namespaces. Эта sandbox является границей между вредоносной страницей и сервером. Если sandbox не запускается, Chromium отказывается работать, а в журнале появляется строка вроде этой:

Failed to move to new namespace: PID namespaces supported, Network namespace supported, but failed: errno = Operation not permitted

Обычно советуют --no-sandbox. На собственных страницах Chromium, посвящённых безопасности, прямо указана цена такого решения: «Мы не рекомендуем это делать, поскольку это значительно снизит уровень безопасности и может помешать нормальной работе Chromium». Агент, переходящий по ссылкам, по определению просматривает открытый Интернет. Именно там проверяется это снижение уровня безопасности. Найдите настоящую причину.

Почти все случаи объясняются двумя причинами. Запуск браузера от имени root отключает sandbox, поскольку процесс не может сбросить уже имеющиеся у него привилегии. Поэтому образ Playwright содержит обычного пользователя с именем pwuser. В Ubuntu 24.04 и более новых версиях AppArmor ограничивает непривилегированные user namespaces, а бинарный файл Chromium по пути, который не покрывает ни один поставляемый профиль, блокируется. Загрузка Playwright в ~/.cache/ms-playwright использует именно такой путь. Проверьте оба условия:

id -u
sysctl kernel.apparmor_restrict_unprivileged_userns
sudo dmesg | grep -i userns_create

Значение 1 в sysctl вместе со строкой ядра, содержащей apparmor="DENIED" operation="userns_create", подтверждает вторую причину. Разрешите этот бинарный файл в /etc/apparmor.d/pw-chromium. Ограничение сохранится для всех остальных компонентов системы:

abi <abi/4.0>,
include <tunables/global>

profile pw-chromium /{home/*/.cache/ms-playwright,opt/pw-browsers}/*/chrome-*/{chrome,headless_shell,chrome-headless-shell} flags=(unconfined) {
  userns,
}

Загрузите правило командой sudo apparmor_parser -r /etc/apparmor.d/pw-chromium. В x86-64 Playwright размещает полный браузер в chrome-linux64/chrome, а shell — в chrome-headless-shell-linux64/chrome-headless-shell. В ARM64 версии Playwright 1.62 и более ранние использовали один каталог chrome-linux, содержащий chrome и headless_shell. Начиная с версии 1.63 ARM64 использует схему x86-64 с chrome-linux-arm64/chrome и chrome-headless-shell-linux-arm64/chrome-headless-shell. Шаблон chrome-* охватывает все эти варианты размещения, а ветка /opt/pw-browsers — общую установку, выполненную с помощью PLAYWRIGHT_BROWSERS_PATH. Путь также содержит ревизию браузера, поэтому он меняется при каждом обновлении Playwright. Указанные выше шаблоны переживают такие изменения. Профиль, созданный для одного точного пути, перестаёт ему соответствовать без явного сообщения, и после обновления, которое казалось не связанным с этой проблемой, браузер снова перестаёт запускаться.

Почему скриншоты получаются пустыми или заполненными квадратами

Пустой скриншот или изображение, заполненное пустыми прямоугольниками, обычно указывает на проблему со шрифтами, а не на ошибку отрисовки. install-deps подтягивает базовый набор: fonts-liberation, fonts-freefont-ttf, fonts-noto-color-emoji, fonts-unifont, fonts-ipafont-gothic для японского языка, fonts-wqy-zenhei для китайского, fonts-tlwg-loma-otf для тайского. В этом наборе нет Noto CJK, поэтому для корейского и ряда других языков система использует любой шрифт, который удается найти через fontconfig. Вместо догадок запросите информацию у fontconfig:

fc-match "sans-serif:lang=ko"
fc-match "sans-serif:lang=ar"
fc-list | wc -l

Если для нужного вам языка возвращается unifont или резервный шрифт без реальных глифов, установите fonts-noto-core и fonts-noto-cjk, а затем повторите проверку. Fontconfig кэширует результаты, поэтому после установки шрифтов перезапустите браузер. В минималистичном образе без установленных шрифтов при запуске записывается ошибка Fontconfig error: Cannot load default config file, и все страницы отображаются пустыми.

Локаль и часовой пояс не связаны со шрифтами напрямую; они влияют на содержимое страницы, а не только на её внешний вид. В контейнере переменная LANG обычно не задана, а TZ установлена в UTC, поэтому сайты отображают английский язык и временные метки в UTC, а ваш агент сообщает время, которое не совпадает с тем, что видит пользователь в конкретном регионе. Устанавливайте эти параметры для каждого контекста браузера отдельно, а не для всей системы, чтобы один браузер мог выполнять задачи для разных регионов.

const context = await browser.newContext({
  locale: 'en-GB',
  timezoneId: 'Europe/Paris',
});

Почему утечки процессов браузера приводят к своппингу системы

Две разные проблемы носят название «зомби». Настоящий зомби — это завершившийся процесс, чей родитель не вызвал wait(). Он занимает только запись в таблице PID и не потребляет память. Такие процессы возникают, когда браузер запускается как PID 1 в контейнере, так как PID 1 не имеет встроенного механизма сбора завершившихся процессов (reaper). Флаг --init в Docker решает именно эту задачу, запуская небольшой init-процесс, который «пересылает сигналы и собирает процессы». В Compose за это отвечает init: true.

Утечка, которая действительно вызывает своппинг системы, имеет другую природу: это активные процессы Chromium, которые никто не закрыл. Это происходит, когда задача прерывается между newContext() и close() или когда управляющий скрипт завершается принудительно, оставляя дерево процессов браузера «сиротами». Худший вариант — код, который запускает новый экземпляр браузера для каждого запроса. Проверьте их количество:

pgrep -c -f 'headless_shell|chrome'
ps -eo pid,ppid,rss,etime,comm --sort=-rss | head -20

Это число должно возвращаться к значению в режиме ожидания после завершения задач. Если оно растёт в течение дня, проблему нужно искать в коде, а не в флагах запуска: закрывайте контекст в блоке finally, закрывайте браузер по SIGTERM и перезапускайте браузер после выполнения фиксированного количества задач, вместо того чтобы держать один экземпляр запущенным месяцами. В systemd остановка или перезапуск юнита завершает все процессы в его cgroup, поэтому sudo systemctl restart browser.service является надежным способом сброса. Браузер, запущенный вручную внутри терминального мультиплексора, таких гарантий не имеет, и его «сироты» продолжают работать после завершения сессии.

Сколько RAM требуется одному browser context

Формулируйте вопрос точно: «один browser» — это не один процесс. Chromium запускает browser process, GPU process, utility processes и по одному renderer process для каждого сайта. При включённой изоляции сайтов cross-site iframe также получает собственный renderer. BrowserContext — это отдельный cookie jar и отдельная область хранения внутри того же дерева процессов, поэтому второй context требует немного ресурсов. Вторая page — нет: для неё запускаются renderer processes, а страница с большим количеством рекламы запускает несколько таких процессов.

Измерять нужно пиковое потребление памяти всем деревом процессов в вашей рабочей нагрузке. Число из чужого блога здесь бесполезно: ответ определяется страницами, которые открывает ваш агент. Выполняйте измерение на той машине, которую будете использовать, и на тех сайтах, которые будете посещать:

sudo systemd-run --unit=browser-probe -p MemoryMax=2G -p MemorySwapMax=0 -p WorkingDirectory=/srv/agent /usr/bin/node worker.js
systemctl status browser-probe

В Ubuntu 24.04 строка Memory: в этом выводе показывает текущее и пиковое потребление unit. Запустите worker с одной page за раз и запишите пиковое значение. Затем повторите измерение с двумя открытыми page, чтобы определить фактическую стоимость второй page. После этого concurrency рассчитывается арифметически: из общего объёма RAM вычтите ресурсы, необходимые остальной системе, оставьте запас в несколько сотен MB и разделите результат на измеренное пиковое потребление одного worker. Для расчёта ресурсов самой машины см. сколько RAM и CPU требуется agent VPS.

Ограничьте это число в двух местах. В коде используйте фиксированный worker pool или semaphore, чтобы всплеск запросов к agent ставил задачи в очередь, а не запускал дополнительные browser. На уровне ОС используйте cgroup limit, чтобы ошибка в очереди не привела к отказу всей машины:

[Service]
MemoryMax=2G
MemorySwapMax=0
TasksMax=512
Restart=always

MemorySwapMax=0 важнее, чем кажется. Без этого параметра cgroup может перемещать страницы памяти в swap при приближении к лимиту. Поэтому машина часто продолжает работать, но каждый запрос начинает выполняться медленно. Это сложнее диагностировать, чем явный отказ. Swap только откладывает проблему: документация systemd указывает, что если использование памяти «cannot be contained under the limit, out-of-memory killer is invoked inside the unit». Если ограничить swap нулём, это происходит сразу после того, как дерево browser достигает MemoryMax. Затем systemd перезапускает unit, а sshd сохраняется. В Compose этим параметрам соответствуют mem_limit, shm_size и init. Они рассмотрены в разделе как задать ограничения памяти в Docker Compose.

Ограничьте доступ к конечной точке браузера из публичной сети

Playwright может запускать браузер в режиме сервера и предоставлять вашему агенту WebSocket URL:

const { chromium } = require('playwright');
const server = await chromium.launchServer({ port: 3000 });
console.log(server.wsEndpoint());

У этой конечной точки нет авторизации. Документация API Playwright прямо указывает: «Любой процесс или веб-страница (включая те, что запущены внутри Playwright), знающие wsPath, могут получить контроль над пользователем ОС». По умолчанию используется хост localhost, «принимающий соединения только через интерфейс loopback», а документация предупреждает, что указание явного адреса, например 0.0.0.0, «открывает RPC браузера для любого устройства, имеющего доступ к прослушиваемому порту». Собственный --remote-debugging-port в Chrome ещё опаснее. Протокол DevTools не имеет никакой аутентификации и полностью полагается на привязку к loopback.

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

ss -ltnp

Любой браузерный порт, привязанный к 0.0.0.0, является уязвимостью. Помните, что большинство провайдеров используют отдельный сетевой файрвол в панели управления, о котором ваши правила ufw ничего не знают. Вместо этого подключайтесь к конечной точке с другого компьютера через SSH-туннель или частную VPN:

ssh -N -L 3000:127.0.0.1:3000 you@your-vps

Риск здесь гораздо выше, чем просто кража ресурсов браузера. Браузер, которым можно управлять извне, — это инструмент для подделки запросов (request forgery), находящийся внутри вашей сети. Любой, кто получит доступ к этому сокету, может заставить его обратиться к http://127.0.0.1:8080, странице администратора вашей базы данных или адресу метаданных облака 169.254.169.254, а затем прочитать ответ со страницы. Ваш файрвол будет видеть запрос, исходящий от самого VPS, что разрешено. Относитесь к управляющей конечной точке как к полноценному доступу к оболочке (shell) на этом сервере.

Серверы MCP имеют аналогичную архитектуру. npx @playwright/mcp@latest --headless --port 8931 работает по HTTP через localhost, а --host 0.0.0.0 — это флаг, который превращает локальный инструмент в публичный. В README проекта прямо сказано, что Playwright MCP «не является границей безопасности». Оставляйте порт на loopback и позволяйте агенту подключаться к нему через тот же туннель.

Страницы, которые читает ваш агент, являются недоверенным вводом

Агент, который просматривает открытый веб, передает текст, написанный посторонними лицами, в модель, содержащую также ваши инструкции. Страница может содержать текст, адресованный этой модели, с указанием отказаться от выполнения задачи, вызвать инструмент или отправить данные на URL. Модель получает оба потока как обычный текст, поэтому у нее нет надежного способа отличить слова со страницы от ваших собственных. Спроектируйте систему так, чтобы у вредоносной страницы было как можно меньше возможностей для воздействия.

  • Запускайте браузер от имени отдельного пользователя ОС, без SSH-ключей и облачных учетных данных в его окружении.
  • Используйте новый контекст для каждой задачи и --isolated с Playwright MCP, чтобы сессия на одном сайте была недоступна для следующей страницы.
  • Поддерживайте список разрешенных источников (allowlist), если задача это позволяет. Playwright MCP принимает --allowed-origins и --blocked-origins в виде списков, разделенных точкой с запятой.
  • Требуйте подтверждения человеком перед любым действием, которое изменяет состояние, например, перед отправкой почты или расходованием средств.

Еще лучше держать весь браузер на машине, которую можно удалить и развернуть заново; это тот же аргумент, что и в запуске агентов для написания кода в одноразовой VM. Если основная задача агента — поиск, а не произвольный просмотр веб-страниц, более узкоспециализированный инструмент будет безопаснее, чем полноценный браузер: инструмент поиска на базе вашего собственного SearXNG возвращает результаты, не загружая вредоносную страницу целиком.

FAQ

Почему Chromium падает в Docker, хотя на том же VPS работает нормально?

Потому что контейнер по умолчанию получает /dev/shm объемом 64 МБ, тогда как на хосте этот показатель значительно выше. Chromium передает отрисованный контент через эту область разделяемой памяти, поэтому тяжелая страница переполняет ее, и процесс рендеринга завершается. Выполните df -h /dev/shm внутри контейнера для проверки, а затем запустите его либо с параметром --ipc=host, который использует разделяемую память хоста, либо с --shm-size=1g, который увеличивает объем памяти самого контейнера. --disable-dev-shm-usage лишь переносит проблему в /tmp.

Безопасно ли использовать --no-sandbox, если на VPS больше ничего нет?

Нет. Песочница предотвращает доступ вредоносной страницы к остальной части системы. В документации по безопасности Chromium об этом флаге сказано: «Мы не рекомендуем это, так как это значительно снижает уровень безопасности и может привести к некорректной работе Chromium». Агент, переходящий по ссылкам, работает в открытом вебе. Устраните причину: не запускайте браузер от имени root, а в Ubuntu 24.04 добавьте профиль AppArmor с userns, для пути к бинарному файлу браузера, чтобы разрешить использование пространств имен непривилегированных пользователей для этой программы.

Сколько браузеров можно запустить на маленьком VPS?

Измерьте это, не копируйте число. Chromium запускает по одному процессу рендеринга на каждый сайт, поэтому ответ зависит от открываемых страниц. Запустите один воркер с systemd-run и установленным MemoryMax, считайте пиковое значение из строки Memory: в systemctl status, затем разделите объем свободной оперативной памяти на этот пик и оставьте запас. Примените полученный результат, используя очередь в коде и MemoryMax в юнит-файле, чтобы при всплеске запросов они ожидали своей очереди, а не вызывали своппинг системы.

Может ли мой агент подключаться к браузеру с другой машины?

Да, но никогда не привязывайте порт к 0.0.0.0. Конечная точка сервера Playwright и порт Chrome DevTools принимают любого клиента, который может к ним обратиться, без пароля. Оставьте слушающий сокет на 127.0.0.1 и передавайте соединение через SSH-туннель или частную VPN. Проверьте состояние с помощью ss -ltnp на сервере и выполните проверку порта снаружи; также проверьте настройки сетевого файрвола у вашего провайдера.

Почему мои скриншоты пустые, хотя страница явно загрузилась?

Отсутствуют шрифты. Если нет шрифта, поддерживающего скрипт страницы, текст отображается как пустые квадраты или не отображается вовсе, поэтому страница с малым количеством изображений выглядит пустой. Выполните fc-match "sans-serif:lang=ko" для каждого языка, который вы парсите, установите fonts-noto-core и fonts-noto-cjk, если ответом является общий запасной вариант (fallback), и перезапустите браузер, чтобы fontconfig обновил свой кэш. Контейнер, в котором вообще нет шрифтов, при запуске записывает в лог Fontconfig error: Cannot load default config file.

Была ли эта статья полезной?