SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

Como rodar Chromium headless para agentes de IA em VPS

Evite falhas do Chromium headless no VPS por /dev/shm pequeno, sandbox, fontes ausentes e processos órfãos. Defina limites e proteja o socket local.

O que está a executar

Um browser headless num VPS é o Chromium sem janela, controlado pelo seu código em vez de uma pessoa. Num servidor, é uma árvore de processos de longa duração com a qual o seu agente comunica através de um socket local. A instalação requer um comando. O trabalho está em tudo o que vem depois. Limite os recursos que o browser pode consumir da máquina e mantenha o endpoint de controlo fora da Internet pública.

Este guia parte do princípio de que a ferramenta já foi escolhida e que agora precisa de a operar. Se ainda estiver a comparar crawlers e extractors, comece por as alternativas self-hosted ao Firecrawl e volte depois. Tudo o que se segue usa o Chromium do Playwright, porque o Playwright inclui a sua própria build do browser e o seu próprio instalador de dependências. Assim, os mesmos comandos funcionam num VPS Ubuntu básico e dentro de um contentor. Os comandos fixam o Playwright em 1.62.

Instale o Chromium sem adivinhar dependências

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

--with-deps instala apt para obter as bibliotecas partilhadas e os tipos de letra necessários ao Chromium, e pede acesso root quando chega a essa etapa. A compilação do browser é descarregada para ~/.cache/ms-playwright do utilizador que executou o comando. Isto é importante num servidor, porque o utilizador do serviço normalmente não é o utilizador com que inicia sessão. Instale os pacotes do sistema uma vez como administrador com sudo npx playwright install-deps chromium. Depois, defina PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers tanto no comando de instalação como na unidade do serviço, para que seja utilizada uma única cópia. Um serviço que não consiga ver o browser falha no arranque com uma mensagem que indica o caminho pesquisado.

Fixe a versão do Playwright. Cada release está associada a uma compilação específica do browser, por isso um npm update sem versão fixa pode substituir o browser enquanto o serviço está em execução. Em 16 de novembro de 2026, a release mais recente é 1.65.1. Consulte as notas da release antes de atualizar a versão fixa. Em servidores ARM64, tenha em atenção que a versão 1.63 mudou o nome das pastas do browser. Isto é importante para o perfil do AppArmor apresentado mais adiante.

Existem duas compilações do Chromium, e não são o mesmo programa. No modo headless, o Playwright utiliza por predefinição o headless shell, um binário mais pequeno que executa apenas em modo headless. Uma instalação normal descarrega-o juntamente com o browser completo, enquanto npx playwright install --with-deps --only-shell instala apenas o shell. O browser completo é obtido com o canal chromium. A documentação de browsers do Playwright chama-lhe "the real Chrome browser, and is thus more authentic, reliable, and offers more features". Use o shell para recolhas em massa. Use o browser completo quando um site se comportar de forma diferente e precisar de determinar a causa.

Por que um navegador headless falha num contentor

O Docker atribui a cada contentor um /dev/shm de 64 MB. A documentação do Docker é explícita: "Se omitir totalmente o tamanho, o sistema usa 64m". O Chromium passa conteúdo renderizado entre os seus processos através dessa área de memória partilhada, por isso uma página pesada pode preenchê-la. O processo renderer termina e o seu cliente comunica que o destino falhou, numa página que funciona normalmente no seu portátil. Confirme o tamanho a partir do interior do contentor antes de alterar qualquer coisa.

df -h /dev/shm

Existem duas correções reais, que são alternativas e não devem ser combinadas. --ipc=host coloca o contentor no namespace IPC do host, fazendo com que use o /dev/shm do host, que normalmente corresponde a metade da RAM. O guia do Docker do Playwright recomenda esta opção, porque, sem ela, "o Chromium pode ficar sem memória e falhar". O custo é perder o isolamento IPC entre o contentor e o host. --shm-size=1g mantém o namespace privado e simplesmente aumenta o tamanho da montagem.

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

A flag --disable-dev-shm-usage é a solução que encontrará na maioria dos resultados de pesquisa, mas faz algo diferente: move esses ficheiros de /dev/shm para um diretório temporário. Se /tmp estiver num disco, troca uma falha por uma renderização mais lenta e escritas no disco. Se /tmp for um tmpfs, os dados continuam na RAM, limitados apenas pelo tamanho máximo do tmpfs, que a documentação do kernel define por predefinição como metade da RAM física; as páginas do tmpfs também podem ser movidas para a swap. Esta é uma forma de um navegador consumir a memória de um VPS pequeno. O Playwright 1.62 passa --disable-dev-shm-usage por predefinição; para usar o /dev/shm que dimensionou, remova esse argumento com ignoreDefaultArgs: ['--disable-dev-shm-usage'] nas opções de arranque.

O custo real de --no-sandbox

O Chromium isola cada renderer numa sandbox baseada em user namespaces do Linux. Essa sandbox é a fronteira entre uma página hostil e o seu servidor. O Playwright desativa a sandbox do Chromium por predefinição, por isso ative-a com chromiumSandbox: true nas opções de arranque. Quando a sandbox ativada não consegue iniciar, o Chromium recusa-se a executar e o log contém uma linha semelhante a esta:

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

A recomendação habitual é --no-sandbox. As páginas de segurança do próprio Chromium são claras sobre o custo: "Não recomendamos isto, porque reduzirá significativamente a sua segurança e poderá impedir o funcionamento correto do Chromium." Um agente que segue ligações está, por definição, a navegar na web aberta. É exatamente aí que essa segurança reduzida é posta à prova. Encontre a causa real.

Executar como root e ter user namespaces bloqueados são duas causas a verificar. A sandbox do Chromium não está disponível quando o processo é executado como root. É por isso que a imagem do Playwright inclui um utilizador comum chamado pwuser. No Docker, o Playwright também recomenda um perfil seccomp que permita clone, setns e unshare para navegação com sandbox. No Ubuntu 24.04 e posteriores, o AppArmor restringe os user namespaces não privilegiados, e um binário do Chromium num caminho que não seja abrangido por nenhum perfil fornecido é bloqueado. O download do Playwright em ~/.cache/ms-playwright está exatamente nesse caso. Verifique ambos:

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

Um 1 proveniente do sysctl, juntamente com uma linha do kernel que contenha apparmor="DENIED" operation="userns_create", confirma a segunda causa. Autorize esse binário em /etc/apparmor.d/pw-chromium. A restrição continuará aplicada a todo o resto do sistema:

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,
}

Carregue-o com sudo apparmor_parser -r /etc/apparmor.d/pw-chromium. Em x86-64, o Playwright coloca o browser completo em chrome-linux64/chrome e a shell em chrome-headless-shell-linux64/chrome-headless-shell. Em ARM64, o Playwright 1.62 instalava-os em diretórios separados: chromium-<revision>/chrome-linux/chrome e chromium_headless_shell-<revision>/chrome-linux/headless_shell. Desde a versão 1.63, o ARM64 segue o padrão x86-64, com chrome-linux-arm64/chrome e chrome-headless-shell-linux-arm64/chrome-headless-shell. O glob chrome-* abrange todos estes layouts, e o ramo /opt/pw-browsers abrange uma instalação partilhada criada com PLAYWRIGHT_BROWSERS_PATH. O caminho também contém a revisão do browser, por isso muda a cada atualização do Playwright. Os globs acima continuam a funcionar apesar dessa alteração. Um perfil escrito para um caminho exato deixa silenciosamente de corresponder, e o browser volta a falhar depois de uma atualização que parecia não estar relacionada.

Por que as capturas de ecrã aparecem vazias ou cheias de quadrados

Uma captura de ecrã vazia, ou cheia de retângulos vazios, normalmente indica um problema de fontes e não um erro de renderização. install-deps obtém uma base funcional: fonts-liberation, fonts-freefont-ttf, fonts-noto-color-emoji, fonts-unifont, fonts-ipafont-gothic para japonês, fonts-wqy-zenhei para chinês e fonts-tlwg-loma-otf para tailandês. Esse conjunto não inclui Noto CJK, por isso o coreano e vários outros scripts usam como fallback qualquer fonte que o fontconfig encontre. Consulte o fontconfig em vez de presumir:

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

Se um idioma necessário for resolvido para unifont ou para um fallback sem glifos reais, instale fonts-noto-core e fonts-noto-cjk e execute a verificação novamente. O fontconfig coloca os resultados em cache, por isso reinicie o browser depois de instalar as fontes. Uma imagem reduzida sem fontes regista Fontconfig error: Cannot load default config file no arranque e renderiza todas as páginas vazias.

O locale e o fuso horário são independentes das fontes. Eles alteram o conteúdo apresentado pela página, e não apenas o seu aspeto. O locale e o fuso horário do contexto do Playwright usam por predefinição as definições do sistema. Por isso, verifique a configuração da imagem em vez de assumir que LANG não está definido ou que o fuso horário é UTC. Defina-os por contexto do browser e não por máquina. Assim, um único browser pode executar tarefas para diferentes regiões.

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

Como processos do browser abandonados fazem o servidor usar swap

Dois problemas diferentes partilham o nome "zombie". Um zombie verdadeiro é um processo terminado cujo processo pai nunca chamou wait(). Mantém uma entrada de PID e nada mais, por isso não consome memória. Estes processos acumulam-se quando o browser é executado como PID 1 num contentor, porque o PID 1 não tem um reaper predefinido. A opção --init do Docker corrige exatamente isso, executando um init pequeno que "encaminha sinais e recolhe processos". No Compose, o equivalente é init: true.

A fuga que realmente faz o servidor usar swap é diferente: são processos Chromium ativos que ninguém encerrou. Isto acontece quando uma tarefa lança uma exceção entre newContext() e close(), ou quando o script de controlo é terminado e deixa a árvore de processos do browser órfã. A pior variante é o código que inicia um browser novo para cada pedido. Conte-os:

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

Essa contagem deve voltar ao valor em inatividade entre tarefas. Se aumentar ao longo de um dia, a correção está no código, não nas opções de arranque: feche o contexto num bloco finally, feche o browser em SIGTERM e recicle o browser depois de um número fixo de tarefas, em vez de o manter em execução durante um mês. No systemd, uma paragem ou reinício termina tudo no cgroup da unidade, por isso sudo systemctl restart browser.service é uma reposição fiável. Um browser iniciado manualmente dentro de um multiplexador de terminal não tem essa garantia, e os seus processos órfãos continuam ativos depois de a sessão terminar.

De quanta RAM precisa um contexto de browser

Faça a pergunta com precisão, porque "um browser" não corresponde a um único processo. O Chromium executa um processo do browser, um processo de GPU, processos de utilitários e um processo de renderização por site. O isolamento de sites também atribui um processo de renderização próprio aos iframes de sites diferentes. Um BrowserContext é um armazenamento separado para cookies e dados dentro dessa mesma árvore, por isso um segundo contexto tem um custo reduzido. Uma segunda página não tem o mesmo comportamento, porque inicia processos de renderização. Uma página com muita publicidade pode iniciar vários.

Por isso, o valor a medir é o pico de memória de toda a árvore durante a sua própria carga de trabalho. Um valor publicado no blog de outra pessoa não é útil neste caso, porque são as páginas abertas pelo seu agente que determinam o resultado. Faça a medição na máquina que vai utilizar, nos sites que vai visitar:

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

No Ubuntu 24.04, a linha Memory: nessa saída mostra o consumo atual e o pico de utilização da unidade. Execute o worker com uma página de cada vez, registe o pico e repita com duas páginas abertas para verificar qual é o custo real de uma segunda página. A concorrência é então uma operação aritmética: subtraia da RAM total o que o restante sistema precisa, mantenha algumas centenas de MB de margem e divida o resultado pelo pico medido por worker. Para dimensionar a máquina subjacente, consulte quanta RAM e CPU um VPS de agente precisa.

Imponha esse limite em dois locais. No código, use um pool fixo de workers ou um semáforo, para que uma rajada de pedidos do agente entre numa fila em vez de iniciar vários browsers. No sistema operativo, use um limite de cgroup, para que um erro na fila não derrube a máquina:

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

MemorySwapMax=0 é mais importante do que parece. Sem esse limite, o cgroup pode transferir páginas para swap quando se aproxima do limite. Assim, a máquina continua frequentemente ativa, mas todos os pedidos ficam lentos. Isso é mais difícil de diagnosticar do que uma falha limpa. A swap apenas adia o problema: a documentação do systemd indica que, se a utilização "cannot be contained under the limit, out-of-memory killer is invoked inside the unit". Com a swap limitada a zero, a unidade não pode utilizar swap. Ao atingir MemoryMax, é feita recuperação de memória antes de um OOM kill, caso essa recuperação não consiga conter a utilização. Restart=always reinicia o serviço quando o processo principal termina, mas o OOM kill isolado de um renderer não garante um reinício. No Compose, os mesmos controlos são mem_limit, shm_size e init. Consulte definir limites de memória no Docker Compose para obter mais informações.

Mantenha o endpoint do navegador fora da Internet pública

O Playwright pode executar o navegador como um servidor e fornecer ao seu agente uma URL WebSocket:

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

Esse endpoint não tem autenticação. A documentação da API do Playwright afirma isso diretamente: "Qualquer processo ou página Web (incluindo os que são executados no Playwright) que conheça o wsPath pode assumir o controlo do utilizador do sistema operativo." O host predefinido é localhost, "aceitando ligações apenas através da interface de loopback", e a documentação avisa que passar um endereço explícito, como 0.0.0.0, "expõe o RPC do navegador a qualquer entidade que consiga alcançar a porta em escuta". O próprio --remote-debugging-port do Chrome é ainda pior. O protocolo DevTools não tem qualquer tipo de autenticação e depende totalmente de estar associado à interface de loopback.

Verifique o que publicou efetivamente e faça também a verificação a partir de uma segunda máquina, além da VPS:

ss -ltnp

Qualquer serviço num browser port associado a 0.0.0.0 é um problema de segurança. Lembre-se de que a maioria dos fornecedores executa uma firewall de rede separada no respetivo painel de controlo. As regras de ufw não têm conhecimento dessa firewall. Aceda ao endpoint a partir de outra máquina através de um túnel SSH ou de uma VPN privada:

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

O risco é maior do que alguém utilizar o navegador indevidamente. Um navegador que pode controlar é uma máquina de falsificação de pedidos alojada dentro da sua rede. Quem alcançar esse socket pode fazê-lo aceder a http://127.0.0.1:8080, à página de administração da sua base de dados ou ao endereço de metadados da cloud em 169.254.169.254 e, em seguida, ler a resposta a partir da página. A firewall vê um pedido proveniente da própria VPS, que é permitido. Trate o endpoint de controlo como equivalente ao acesso shell a essa máquina.

Os servidores MCP têm a mesma estrutura. npx @playwright/mcp@latest --headless --port 8931 disponibiliza serviço HTTP em localhost, e --host 0.0.0.0 é a flag que transforma uma ferramenta local numa ferramenta pública. O README do projeto afirma claramente que o Playwright MCP "não é um limite de segurança". Mantenha a porta na interface de loopback e permita que o agente a alcance através do mesmo túnel.

As páginas que o seu agente lê são entradas não confiáveis

Um agente que navega na Web aberta fornece ao modelo texto escrito por terceiros, enquanto o modelo também recebe as suas instruções. Uma página pode conter texto dirigido ao modelo, instruindo-o a abandonar a tarefa, chamar uma ferramenta ou publicar dados num URL. O modelo recebe ambos como texto, por isso não tem uma forma fiável de distinguir as palavras da página das suas instruções. Configure o ambiente para que uma página hostil tenha pouco acesso a recursos úteis.

  • Execute o navegador com um utilizador próprio do sistema operativo, sem chaves SSH e sem credenciais de cloud no ambiente.
  • Use um contexto novo por tarefa e --isolated com Playwright MCP; feche o navegador MCP entre tarefas para descartar o armazenamento dessa sessão.
  • Mantenha uma lista de permissões de origens quando a tarefa permitir. O Playwright MCP aceita --allowed-origins e --blocked-origins como listas separadas por ponto e vírgula. Estes filtros não afetam redirecionamentos e não constituem uma fronteira de segurança.
  • Exija uma etapa de aprovação humana antes de qualquer ação que altere o estado, como enviar correio ou gastar dinheiro.

Melhor ainda, mantenha todo o navegador numa máquina que possa eliminar e reconstruir. O mesmo princípio aplica-se a executar agentes de programação numa VM descartável. Se a tarefa real do agente for pesquisar, e não navegar livremente, uma ferramenta mais restrita é mais segura do que um navegador completo: uma skill de pesquisa suportada pelo seu próprio SearXNG devolve resultados sem nunca carregar a página hostil.

FAQ

Por que o Chromium falha no Docker, mas funciona normalmente no mesmo VPS fora do contentor?

Porque o contentor recebe, por predefinição, um /dev/shm de 64 MB, enquanto o host tem um valor muito maior. O Chromium passa o conteúdo renderizado por essa área de memória partilhada. Por isso, uma página pesada pode preenchê-la e fazer o processo de renderização terminar. Execute df -h /dev/shm dentro do contentor para confirmar. Depois, inicie-o com --ipc=host, que usa a memória partilhada do host, ou com --shm-size=1g, que aumenta a memória própria do contentor. --disable-dev-shm-usage apenas desloca o problema para /tmp. O Playwright 1.62 passa essa opção por predefinição. Use ignoreDefaultArgs: ['--disable-dev-shm-usage'] para fazer o Chromium usar a memória partilhada que dimensionou.

É seguro usar --no-sandbox se o VPS não executar mais nada?

Não. O sandbox impede que uma página maliciosa aceda ao restante sistema. As páginas de segurança do Chromium dizem o seguinte sobre essa opção: "We do not encourage this as it will significantly reduce your security, and may prevent Chromium from working properly." Um agente que segue ligações está a navegar na Web pública. Corrija a causa. Não execute o navegador como root. No Ubuntu 24.04, adicione um perfil AppArmor que contenha userns, para o caminho do binário do navegador. Assim, os user namespaces sem privilégios são permitidos apenas para esse programa. Ative explicitamente o sandbox com chromiumSandbox: true. No Docker, use também o perfil seccomp recomendado pelo Playwright.

Quantos navegadores posso executar num VPS pequeno?

Meça esse valor. Não copie um número genérico. O Chromium inicia um processo de renderização por site. Portanto, a resposta depende das páginas que abrir. Execute um worker com systemd-run e defina MemoryMax. Leia o pico na linha Memory: de systemctl status. Depois, divida a RAM livre por esse pico e mantenha margem de segurança. Aplique o limite duas vezes: use uma fila no código e um MemoryMax no ficheiro da unidade. Assim, uma rajada de pedidos fica em espera em vez de provocar swapping no sistema.

O meu agente pode ligar-se ao navegador a partir de outra máquina?

Sim, mas nunca associe a porta a 0.0.0.0. O endpoint do servidor Playwright e a porta Chrome DevTools aceitam qualquer cliente que consiga aceder-lhes, sem palavra-passe. Mantenha o listener em 127.0.0.1 e transporte a ligação através de um túnel SSH ou de uma VPN privada. Verifique com ss -ltnp no servidor e faça um teste à porta a partir do exterior. Consulte também a firewall de rede separada do seu fornecedor.

Por que as minhas capturas de ecrã ficam vazias quando a página foi claramente carregada?

Faltam fontes. Sem uma fonte que contenha os caracteres usados pela página, o texto é renderizado como caixas vazias ou não é renderizado. Por isso, uma página com poucas imagens pode parecer vazia. Execute fc-match "sans-serif:lang=ko" para cada idioma que recolhe. Instale fonts-noto-core e fonts-noto-cjk quando o resultado for uma fonte genérica de fallback. Depois, reinicie o navegador para que o fontconfig recarregue a cache. Um contentor sem fontes regista Fontconfig error: Cannot load default config file no arranque.

Este artigo foi útil?