SSD Nodes Learn Hosting plans →
Посібники Matt ConnorВід Matt Connor

Як запустити headless Chromium для AI-агента на VPS

Headless Chromium на VPS ламається через малий /dev/shm, sandbox, відсутні шрифти та процеси, що не завершуються. Налаштуйте ліміти заздалегідь.

Що саме ви запускаєте

Headless-браузер на VPS — це Chromium без вікна, яким керує ваш код, а не користувач. На сервері це довготривале дерево процесів, з яким ваш агент взаємодіє через локальний сокет. Для встановлення потрібна одна команда. Уся робота починається після цього. Ви обмежуєте ресурси, які браузер може використовувати на машині, і не відкриваєте його endpoint керування для публічного інтернету.

Цей посібник передбачає, що інструмент уже обрано і тепер його потрібно експлуатувати. Якщо ви ще порівнюєте краулери та екстрактори, почніть із self-hosted альтернатив Firecrawl, а потім поверніться до цього розділу. Нижче використовується Chromium у складі Playwright, оскільки Playwright постачається із власною збіркою браузера та власним інсталятором залежностей. Тому ті самі команди працюють на чистому Ubuntu VPS і всередині контейнера. У командах зафіксовано Playwright 1.62.

Встановлення 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 і в команді встановлення, і в unit сервісу, щоб використовувалася одна спільна копія. Сервіс, який не бачить свого браузера, завершується під час запуску з повідомленням про шлях, який він перевіряв.

Зафіксуйте версію Playwright. Кожен реліз пов’язаний з однією збіркою браузера, тому незафіксований npm update може замінити браузер під час роботи сервісу. Станом на November 16, 2026 останнім релізом є 1.65.1, тому перед зміною зафіксованої версії ознайомтеся з примітками до релізу. На серверах ARM64 врахуйте, що у версії 1.63 було перейменовано каталоги браузерів. Це важливо для профілю AppArmor, описаного нижче.

Існує дві збірки Chromium, і це не одна й та сама програма. У headless-режимі Playwright типово використовує headless shell — менший бінарний файл, який працює лише без графічного інтерфейсу. Звичайне встановлення завантажує його поруч із повною версією браузера, а npx playwright install --with-deps --only-shell встановлює лише shell. Повний браузер встановлюється за допомогою каналу chromium, який документація браузерів Playwright називає "the real Chrome browser, and is thus more authentic, reliable, and offers more features". Використовуйте shell для масового завантаження даних. Повний браузер потрібен, коли сайт поводиться інакше й необхідно з’ясувати причину.

Чому headless browser завершує роботу з помилкою в контейнері

Docker виділяє кожному контейнеру 64 MB /dev/shm. У документації Docker прямо зазначено: "If you omit the size entirely, the system uses 64m". Chromium передає відрендерений вміст між своїми процесами через цю shared memory area, тому одна важка сторінка може її заповнити. Після цього renderer завершує роботу, а клієнт повідомляє про збій target на сторінці, яка без проблем працює на вашому ноутбуці. Перш ніж щось змінювати, перевірте розмір зсередини контейнера.

df -h /dev/shm

Є два правильні способи виправлення. Це альтернативи, а не налаштування, які потрібно застосовувати разом. --ipc=host підключає контейнер до IPC namespace хоста, тому він використовує /dev/shm хоста, розмір якого зазвичай становить половину RAM. У посібнику Playwright для Docker цей спосіб рекомендовано, оскільки без нього "Chromium can run out of memory and crash". Недолік полягає у втраті IPC isolation між контейнером і хостом. --shm-size=1g зберігає приватний 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. Документація ядра за замовчуванням встановлює цей ліміт на рівні половини фізичної RAM, а сторінки tmpfs можуть бути переміщені до swap. Це один зі способів, у який browser може швидко використати RAM невеликого VPS. Playwright 1.62 за замовчуванням передає --disable-dev-shm-usage. Щоб використовувати /dev/shm, розмір якого ви встановили, видаліть цей аргумент за допомогою ignoreDefaultArgs: ['--disable-dev-shm-usage'] у параметрах запуску.

Що насправді коштує параметр --no-sandbox

Chromium ізолює кожен renderer у sandbox, побудованому на Linux user namespaces. Цей sandbox є межею між шкідливою вебсторінкою та сервером. Playwright типово вимикає sandbox Chromium, тому увімкніть його за допомогою chromiumSandbox: true у параметрах запуску. Якщо увімкнений 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 і заблоковані user namespaces. Sandbox Chromium недоступний під час запуску від імені root, тому образ Playwright містить звичайного користувача з іменем pwuser. У Docker Playwright також рекомендує профіль seccomp, який дозволяє clone, setns і unshare для роботи sandbox. В 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 встановлював їх в окремі каталоги: chromium-<revision>/chrome-linux/chrome і chromium_headless_shell-<revision>/chrome-linux/headless_shell. Починаючи з 1.63, ARM64 використовує схему x86-64 з chrome-linux-arm64/chrome і chrome-headless-shell-linux-arm64/chrome-headless-shell. Glob chrome-* охоплює всі ці варіанти структури каталогів, а гілка /opt/pw-browsers — спільне встановлення, виконане за допомогою PLAYWRIGHT_BROWSERS_PATH. Шлях також містить revision браузера, тому він змінюється після кожного оновлення Playwright. Наведені вище globs не залежать від цього. Профіль, створений для одного точного шляху, непомітно перестає відповідати й браузер знову починає завершуватися з помилкою після оновлення, яке здавалося не пов’язаним із цією проблемою.

Чому знімки екрана виходять порожніми або заповненими прямокутниками

Порожній знімок екрана або знімок, заповнений порожніми прямокутниками, зазвичай свідчить про проблему зі шрифтами, а не про помилку рендерингу. 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, і всі сторінки відображаються порожніми.

Локаль і часовий пояс не залежать від шрифтів. Вони змінюють текст на сторінці, а не лише її вигляд. Локаль і часовий пояс контексту Playwright за замовчуванням беруться із системних налаштувань. Тому перевірте конфігурацію образу, а не припускайте, що LANG не встановлено або що часовий пояс — UTC. Встановлюйте їх для кожного контексту браузера, а не для всієї машини. Так один браузер зможе виконувати завдання для різних регіонів.

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

Як витоки процесів браузера змушують сервер використовувати swap

Дві різні проблеми називають словом «zombie». Справжній zombie — це завершений процес, батьківський процес якого не викликав wait(). Він утримує лише запис PID і більше нічого, тому не споживає пам’ять. Такі процеси накопичуються, коли браузер працює як PID 1 у контейнері, оскільки PID 1 за замовчуванням не виконує роль reaper. Прапорець --init у Docker виправляє саме це: він запускає невеликий init, який «пересилає сигнали та збирає завершені процеси». У Compose для цього використовується init: true.

Витік, через який сервер фактично починає використовувати swap, має іншу причину: це активні процеси Chromium, які ніхто не завершив. Таке трапляється, коли завдання завершується з помилкою між newContext() і close() або коли керівний скрипт примусово завершується й залишає своє дерево процесів браузера без батьківського процесу. Найгірший варіант — код, який запускає новий браузер для кожного запиту. Порахуйте їх:

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

Між завданнями це число має повертатися до значення в режимі простою. Якщо протягом дня воно зростає, проблему потрібно виправляти в коді, а не в параметрах запуску: закривайте context у блоці finally, закривайте браузер у SIGTERM і перезапускайте браузер після фіксованої кількості завдань, а не залишайте один процес працювати місяць. У systemd зупинка або перезапуск завершує всі процеси в cgroup цього unit, тому sudo systemctl restart browser.service є надійним способом скидання стану. Браузер, запущений вручну в terminal multiplexer, не має такої гарантії, і його дочірні процеси можуть працювати після завершення сесії.

Скільки RAM потребує один browser context

Сформулюйте запитання точно, оскільки «один browser» — це не один процес. Chromium запускає browser process, GPU process, utility processes і по одному renderer process для кожного сайту. Site isolation також надає iframe з іншого сайту власний renderer process. BrowserContext — це окреме сховище cookies і даних усередині того самого дерева процесів, тому другий 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 з однією сторінкою, зафіксуйте пікове значення, а потім повторіть вимірювання з двома відкритими сторінками, щоб визначити фактичну вартість другої сторінки. Далі кількість паралельних worker обчислюється просто: від загального обсягу RAM відніміть ресурси, потрібні решті системи, залиште запас у кілька сотень MB і поділіть результат на виміряне пікове споживання одного worker. Для розрахунку параметрів базової машини див. скільки RAM і CPU потребує VPS для агента.

Обмежте це число у двох місцях. У коді використовуйте фіксований пул worker або semaphore, щоб сплеск запитів агента ставив запити в чергу, а не запускав нові browser. В ОС використовуйте обмеження cgroup, щоб помилка в черзі не призвела до відмови всієї машини:

[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 на нуль, unit не зможе використовувати swap. Досягнення MemoryMax запускає reclaim до OOM kill, якщо reclaim не може втримати споживання в межах ліміту. Restart=always перезапускає service, коли завершується його main process, але OOM kill лише renderer process не гарантує перезапуску. Відповідні параметри в Compose — mem_limit, shm_size і init. Їх описано в розділі налаштування обмежень пам’яті в Docker Compose.

Не виставляйте браузерний endpoint у публічний інтернет

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

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

Цей endpoint не має автентифікації. В API-документації Playwright це зазначено безпосередньо: «Будь-який процес або вебсторінка (зокрема ті, що працюють у Playwright), яким відомий wsPath, можуть отримати контроль над користувачем ОС». Типове значення host — localhost, що «приймає з’єднання лише з loopback-інтерфейсу», а документація попереджає, що передавання явної адреси, наприклад 0.0.0.0, «відкриває browser RPC для всіх, хто може досягти порту, на якому він прослуховується». Власний --remote-debugging-port у Chrome ще небезпечніший. Протокол DevTools не має жодної автентифікації та повністю залежить від прив’язки до loopback.

Перевірте, що саме ви опублікували, а також виконайте перевірку з іншої машини, не лише з VPS:

ss -ltnp

Будь-який браузерний порт, прив’язаний до 0.0.0.0, є проблемою безпеки. Пам’ятайте, що більшість провайдерів мають окремий мережевий firewall у панелі керування. Ваші правила ufw про нього нічого не знають. Отримуйте доступ до endpoint з іншої машини через SSH-тунель або приватний VPN:

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

Ризик тут не обмежується викраденням часу роботи браузера. Браузер, яким можна керувати, — це механізм підроблення запитів усередині вашої мережі. Той, хто отримає доступ до цього сокета, зможе змусити браузер запитати http://127.0.0.1:8080, сторінку адміністрування бази даних або адресу хмарних метаданих 169.254.169.254, а потім прочитати відповідь зі сторінки. Ваш firewall бачить запит, що надходить із самого VPS, а такий запит дозволений. Вважайте endpoint керування еквівалентним доступу до shell на цьому сервері.

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

Сторінки, які читає ваш агент, є ненадійними вхідними даними

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

  • Запускайте браузер під окремим користувачем ОС. Не надавайте йому SSH-ключі та хмарні облікові дані в середовищі.
  • Використовуйте новий context для кожного завдання та --isolated з Playwright MCP. Закривайте браузер MCP між завданнями, щоб видалити сховище цього сеансу.
  • Використовуйте allowlist доменів, якщо це передбачено завданням. Playwright MCP приймає --allowed-origins і --blocked-origins як списки, розділені крапками з комою. Ці фільтри не поширюються на редиректи та не є межею безпеки.
  • Вимагайте підтвердження людини перед будь-якою дією, яка змінює стан, наприклад перед надсиланням пошти або витрачанням коштів.

Ще краще розмістити весь браузер на машині, яку можна видалити й відновити. Це той самий аргумент, що й запуск coding agents у disposable VM. Якщо фактичне завдання агента — пошук, а не довільний перегляд вебу, вузькоспеціалізований інструмент безпечніший за повноцінний браузер: search skill на основі власного SearXNG повертає результати, не завантажуючи шкідливу сторінку.

FAQ

Чому Chromium аварійно завершує роботу в Docker, але нормально працює безпосередньо на тому самому VPS?

Тому що контейнер за замовчуванням отримує /dev/shm розміром 64 MB, тоді як на хості він значно більший. Chromium передає відрендерений вміст через цю спільну область пам’яті. Тому велика сторінка заповнює її, і renderer аварійно завершує роботу. Виконайте в контейнері df -h /dev/shm, щоб це підтвердити. Потім запустіть браузер із --ipc=host, що використовує shared memory хоста, або з --shm-size=1g, що збільшує власну shared memory контейнера. --disable-dev-shm-usage лише переносить проблему до /tmp. Playwright 1.62 передає цей прапорець за замовчуванням. Використовуйте ignoreDefaultArgs: ['--disable-dev-shm-usage'], щоб Chromium використовував налаштований вами розмір shared memory.

Чи безпечно використовувати --no-sandbox, якщо на VPS більше нічого не запущено?

Ні. Sandbox не дає шкідливій сторінці отримати доступ до решти системи. На сторінках безпеки Chromium щодо цього прапорця зазначено: «Ми не рекомендуємо цього, оскільки це суттєво знизить рівень безпеки та може перешкодити Chromium працювати належним чином». Агент, який переходить за посиланнями, переглядає відкритий веб. Усуньте причину: не запускайте браузер від імені root. В Ubuntu 24.04 додайте профіль AppArmor із userns, для шляху до бінарного файла браузера, щоб дозволити unprivileged user namespaces лише для цієї програми. Явно увімкніть sandboxing за допомогою chromiumSandbox: true. У Docker також використовуйте seccomp profile, рекомендований Playwright.

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

Виміряйте це значення, а не копіюйте готове число. Chromium запускає окремий renderer process для кожного сайту, тому відповідь залежить від відкритих сторінок. Запустіть один worker із MemoryMax і параметром systemd-run, зчитайте пікове значення з рядка Memory: у systemctl status, потім поділіть доступний обсяг RAM на це пікове значення та залиште запас. Обмежте результат двома способами: використайте queue у коді та MemoryMax у unit file. Тоді під час сплеску запитів вони очікуватимуть, а не спричинятимуть swapping системи.

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

Так, але ніколи не прив’язуйте порт до 0.0.0.0. Playwright server endpoint і Chrome DevTools port приймають підключення від будь-якого клієнта, який може до них дістатися, без пароля. Залиште listener на 127.0.0.1 і передавайте з’єднання через SSH tunnel або private VPN. Перевірте це за допомогою ss -ltnp на сервері та перевіркою порту ззовні. Також перевірте окремий network firewall у вашого провайдера.

Чому мої знімки екрана порожні, хоча сторінка явно завантажилася?

Відсутні шрифти. Якщо немає шрифту, який підтримує систему письма сторінки, текст відображається порожніми блоками або не відображається взагалі. Тому сторінка з малою кількістю зображень у знімку виглядає порожньою. Виконайте fc-match "sans-serif:lang=ko" для кожної мови, дані якої ви збираєте. Якщо результатом є generic fallback, встановіть fonts-noto-core і fonts-noto-cjk. Потім перезапустіть браузер, щоб fontconfig повторно завантажив свій кеш. Контейнер без жодного шрифту записує Fontconfig error: Cannot load default config file під час запуску.

Чи була ця стаття корисною?

#headless-browser#playwright#chromium#ai-agents#automation