Por que o n8n fica offline no seu VPS
Diferencie o aviso de websocket, o loop de reinício, o kill por falta de memória e o agendamento parado antes de mudar a configuração do n8n.
Por que o n8n fica offline: quatro falhas, um sintoma
“o n8n fica offline” é uma frase que abrange quatro falhas diferentes, e cada uma exige uma correção própria. O editor mostra um aviso de conexão perdida enquanto o container continua funcionando normalmente. O container reinicia sozinho. O kernel encerra o processo Node.js por usar memória em excesso. Ou não há nenhum problema com o processo, e um workflow ativo simplesmente nunca é executado. Altere a configuração errada e você passará o fim de semana resolvendo um problema que nunca existiu.
Por isso, identifique a falha antes de alterar qualquer configuração. O n8n executa um processo Node.js principal, normalmente dentro de um container Docker, atrás de um reverse proxy que faz a terminação TLS (transport layer security). Os Code nodes também usam processos task runner: o modo interno inicia um processo filho, enquanto o modo externo os executa separadamente, normalmente em um container sidecar. Cada uma dessas camadas falha de uma forma diferente, e o navegador informa falhas de conexão com a mesma mensagem.
Diagnostique nesta ordem
Execute estes comandos no VPS (virtual private server) e leia os valores apresentados pela sua própria máquina. Não os compare com números de uma publicação num fórum. Os valores relevantes descrevem o seu servidor, não o servidor de outra pessoa.
docker ps -a --filter name=n8n
docker logs --tail 200 --timestamps n8n
docker inspect n8n | grep -iE 'Status|Running|RestartCount|OOMKilled|ExitCode'
docker stats --no-streamA coluna STATUS de docker ps -a indica há quanto tempo o contentor está no estado atual. Compare esse valor com o momento em que o problema começou. Se o contentor estiver em execução desde muito antes de o banner aparecer, isso exclui um reinício do contentor nesse momento, mas não prova que o n8n tenha continuado disponível. Verifique /healthz quanto à acessibilidade e /healthz/readiness quanto a uma base de dados ligada e migrada antes de avançar para o caminho WebSocket abordado na secção seguinte.
RestartCount indica quantas vezes o Docker reiniciou este contentor. Anote o número, aguarde um minuto e leia-o novamente. Se o número aumentar enquanto observa, existe um ciclo de reinícios. As linhas do log imediatamente anteriores a cada reinício indicam o motivo.
OOMKilled é um indicador com valor verdadeiro ou falso. O valor True significa que o Docker registou uma terminação por falta de memória no contentor. Leia-o juntamente com os logs e as mensagens do kernel para determinar qual processo foi terminado e se a pressão veio do limite do contentor ou da máquina inteira.
ExitCode indica o código com que o contentor terminou na última vez. Não precisa de memorizar o significado de cada código. Leia o seu valor e, em seguida, leia o final de docker logs a partir do mesmo instante. O final do log e o indicador de falta de memória, em conjunto, mostram o que aconteceu. Isoladamente, qualquer um deles pode induzir em erro.
docker stats apresenta a utilização atual de memória junto ao limite aplicado. Deixe este comando em execução num segundo terminal, acione o workflow que provoca a falha e observe o comportamento do valor enquanto a falha ocorre.
O banner de ligação perdida normalmente é causado pelo seu reverse proxy
O editor do n8n mantém uma ligação push de longa duração aberta para o backend, para transmitir o progresso da execução para o canvas. Por predefinição, essa ligação é um WebSocket, selecionado por N8N_PUSH_BACKEND, e o seu valor predefinido é websocket. Um WebSocket começa como um pedido HTTP normal que transporta os cabeçalhos Connection: Upgrade e Upgrade: websocket. O servidor responde com 101 Switching Protocols e, a partir desse momento, ambos os lados usam o mesmo socket TCP nos dois sentidos.
Dois problemas no proxy interrompem essa ligação. O proxy comunica com o upstream através de HTTP/1.0 ou remove os cabeçalhos de upgrade. Nesse caso, o upgrade nunca ocorre e o editor tenta ligar-se novamente de forma contínua. Em alternativa, o upgrade é concluído, mas o proxy fecha posteriormente o socket por este permanecer inativo. Um WebSocket sem mensagens parece exatamente uma ligação inativa. O próprio n8n também rejeita ligações push quando falham a autenticação ou a validação do pedido, incluindo quando pushRef está em falta ou quando a origem é inválida. O banner indica que o browser perdeu o canal. Não prova que o container esteja saudável.
Confirme isto no browser antes de alterar qualquer configuração. Abra as ferramentas de programador, aceda ao separador Network, filtre por WS e recarregue o editor. O pedido push deve chegar a 101 Switching Protocols e permanecer aberto. Um pedido push que devolva um código de estado normal, ou que reapareça a cada poucos segundos, exige a verificação da resposta e dos logs do n8n para identificar erros de proxy, autenticação ou origem.
As configurações do nginx que mantêm o editor ligado
O nginx não encaminha uma atualização de protocolo a menos que isso seja configurado. Connection e Upgrade são cabeçalhos hop-by-hop que o nginx remove durante o encaminhamento, por isso é necessário voltar a defini-los. O protocolo usado entre o proxy e o upstream depende da versão do nginx: desde a 1.29.7 (março de 2026), proxy_pass comunica com o backend através de HTTP/1.1 por predefinição; antes disso, usava HTTP/1.0, que não consegue transportar uma atualização de protocolo. Execute nginx -v para verificar qual versão está instalada. A configuração abaixo mantém proxy_http_version 1.1 explícito para funcionar em ambas as versões. No nginx 1.29.7 ou posterior, essa linha apenas repete a predefinição. O bloco map deve ficar no contexto http, e não dentro de server. Se o restante do bloco de servidor abaixo não for familiar, o guia linha a linha de um bloco de servidor do nginx explica o que cada diretiva faz.
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}server {
listen 443 ssl;
http2 on;
server_name n8n.example.com;
location / {
proxy_pass http://127.0.0.1:5678;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
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;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_buffering off;
}
}proxy_read_timeout tem o valor predefinido de 60 segundos e também se aplica a um WebSocket atualizado, medido entre leituras do backend. O n8n envia pings de manutenção a cada 60 segundos, por isso uma instância de workflow sem atividade aparente não significa que o socket não esteja a transportar tráfego. Aumentar o timeout dá tempo para esses pings chegarem sem entrar em conflito com o timeout predefinido; os frames de ping periódicos também reiniciam o temporizador.
sudo nginx -t && sudo systemctl reload nginx
sudo nginx -T | grep -iE 'proxy_http_version|upgrade|proxy_read_timeout'nginx -T testa e mostra os ficheiros de configuração, incluindo os ficheiros incluídos, em vez de inspecionar a configuração já carregada pelo processo em execução. Confirme também se o reload foi concluído com sucesso. Se uma configuração estiver num ficheiro que nenhuma linha include inclui, a correção correta parecerá não produzir efeito.
Em seguida, informe o n8n de que está atrás de um proxy, porque ele cria URLs com base nestes valores.
environment:
- N8N_HOST=n8n.example.com
- N8N_PROTOCOL=https
- N8N_PORT=5678
- N8N_PROXY_HOPS=1
- N8N_WEBHOOK_URL=https://n8n.example.com/N8N_PROXY_HOPS tem o valor predefinido de 0. Isso faz com que o n8n trate o endereço da ligação como o endereço do cliente e ignore X-Forwarded-For. Defina-o como o número de proxies existentes à frente do container. Em outubro de 2026, N8N_WEBHOOK_URL é o nome atual, e o nome antigo WEBHOOK_URL continua a funcionar, embora mostre um aviso de descontinuação durante o arranque.
O Traefik encaminha WebSockets automaticamente
O Traefik encaminha uma atualização para WebSocket sem middleware nem labels adicionais. Os valores padrão dos timeouts HTTP não definem um timeout para um WebSocket depois da atualização. As opções abaixo pertencem ao entryPoint: em outubro de 2026, no Traefik v3, idleTimeout tem o valor padrão de 180 segundos para ligações HTTP keep-alive inativas e readTimeout tem o valor padrão de 60 segundos para a leitura do pedido, incluindo o corpo. O timeout de escrita da resposta exclui explicitamente as atualizações de protocolo. Este exemplo altera os timeouts HTTP; não é uma correção comprovada para um banner de WebSocket.
entryPoints:
websecure:
address: ":443"
transport:
respondingTimeouts:
readTimeout: 0
idleTimeout: 3600sO Caddy processa a atualização automaticamente em reverse_proxy e não precisa de nenhuma diretiva para isso. Se não puder alterar o proxy porque outra pessoa o administra, altere o canal de push com N8N_PUSH_BACKEND=sse. SSE (server-sent events) é uma resposta HTTP normal mantida aberta. Por isso, funciona através de um proxy que recusa atualizações, embora um timeout agressivo de inatividade também possa interrompê-la. A escolha do próprio proxy é uma decisão separada, e a comparação entre nginx, Caddy e Traefik explica o custo operacional de cada um.
Quando o contentor está realmente a reiniciar
Se RestartCount aumentar, o contentor está a falhar e o Docker está a iniciá-lo novamente. Compare os timestamps dos logs com cada reinício e leia o que aconteceu imediatamente antes. As causas comuns incluem um erro de configuração que impede o arranque, uma base de dados que o n8n não consegue alcançar, uma falha depois de o serviço arrancar e uma terminação por falta de memória.
Comece pelo volume, porque as permissões são uma causa silenciosa. A imagem oficial é executada com o utilizador sem privilégios node e guarda os dados em /home/node/.n8n. Se um bind mount não tiver permissões de escrita para esse utilizador, o processo falha quando tenta gravar os dados. Uma política de reinício pode transformar essa falha num ciclo.
docker compose config
docker run --rm -it --entrypoint sh docker.n8n.io/n8nio/n8n -c 'id'
docker exec n8n ls -ld /home/node/.n8nUm volume nomeado novo herda o proprietário do diretório da imagem quando o Docker o preenche. Um volume existente ainda precisa de ter as permissões verificadas. Se precisar de um bind mount, chown o diretório do host para o ID numérico do utilizador apresentado pelo comando id. Vale a pena compreender uma vez o mapeamento de proprietários entre o host e o contentor. A explicação sobre PUID e PGID mostra como estas imagens determinam quem grava os ficheiros.
A morte por falta de memória que parece uma falha
Existem dois limites de memória separados acima de um processo n8n, e eles falham de formas diferentes. O limite do grupo de controlo do contentor é aplicado pelo kernel: se o uso atingir o limite e não puder ser reduzido, o kernel invoca o OOM killer. O uso pode exceder temporariamente esse limite. Uma morte por OOM não dá ao processo terminado oportunidade de escrever uma entrada final no log, e o Docker regista o evento em OOMKilled. O limite do heap do V8 é aplicado dentro do Node.js: esgotá-lo produz um erro fatal do heap e termina o processo sem uma morte por OOM do kernel. No browser, estes problemas parecem idênticos. Leia docker inspect juntamente com os logs para os distinguir.
Defina o limite do heap do Node abaixo do limite do contentor. Deixe espaço para alocações nativas, buffers, outras regiões do heap e outros processos no contentor. Um limite de heap mais elevado aumenta o risco de uma morte por OOM do kernel antes de o V8 atingir o seu próprio limite, mas não a garante: a memória pode ser recuperada ou trocada, e a carga de trabalho pode nunca esgotar nenhum dos limites. Um limite de heap mais baixo também não garante um erro do heap antes de uma morte por OOM do contentor.
services:
n8n:
image: docker.n8n.io/n8nio/n8n
restart: unless-stopped
environment:
- NODE_OPTIONS=--max-old-space-size=<MiB, below the container limit>
deploy:
resources:
limits:
memory: <your container limit>Substitua o marcador do heap por um valor numérico em MiB, usando o formato --max-old-space-size=SIZE. Escolha ambos os números com base nos recursos efetivamente disponíveis no seu VPS e deixe espaço para a base de dados, o proxy e o sistema operativo. docker stats --no-stream apresenta o uso atual junto ao limite em vigor, para que possa confirmar que o limite que escreveu é o limite aplicado pelo Docker. Como são aplicados os limites de memória do Compose explica qual chave prevalece quando existem várias configurações.
Dados de execução: o que cresce sem que se perceba
Uma única execução contém a saída de cada nó enquanto a execução está em curso, e o n8n armazena esses dados de acordo com as definições de retenção de execuções. Daqui resultam duas consequências. A quantidade de dados e o trabalho realizado por cada nó afetam o pico de memória. Por isso, um workflow que processa dez mil linhas de uma vez é um programa diferente do mesmo workflow a processar duzentas de cada vez. Além disso, a cópia armazenada continua a crescer até ser eliminada.
A limpeza trata do segundo problema. Em outubro de 2026, os valores predefinidos são a limpeza ativada, EXECUTIONS_DATA_MAX_AGE em 336 horas (14 dias) e EXECUTIONS_DATA_PRUNE_MAX_COUNT em 10000. Estes valores são generosos para uma VPS pequena com SQLite, onde um único ficheiro contém tudo e o mesmo processo que disponibiliza o editor tem de o ler e escrever.
environment:
- EXECUTIONS_DATA_PRUNE=true
- EXECUTIONS_DATA_MAX_AGE=72
- EXECUTIONS_DATA_PRUNE_MAX_COUNT=1000
- EXECUTIONS_DATA_SAVE_ON_SUCCESS=none
- EXECUTIONS_DATA_SAVE_MANUAL_EXECUTIONS=falseEXECUTIONS_DATA_SAVE_ON_SUCCESS=none é a definição agressiva. Desativa o armazenamento de execuções bem-sucedidas. As execuções que falharam são mantidas se EXECUTIONS_DATA_SAVE_ON_ERROR continuar com o valor predefinido de all, e as definições individuais de cada workflow podem substituir estas opções. Tome essa decisão conscientemente, porque um workflow pode produzir uma saída incorreta sem gerar um erro e, nesse caso, não deixará nada para inspecionar. A limpeza também marca primeiro as linhas como eliminadas e só as remove numa passagem posterior. Além disso, o SQLite reutiliza as páginas libertadas em vez de as devolver ao sistema, por isso o ficheiro no disco não diminui imediatamente quando altera a definição.
Para reduzir o pico em vez do total armazenado, mova menos dados em cada execução. Divida os trabalhos grandes em sub-workflows que devolvam resultados pequenos ao workflow principal, use processamento em lotes com o nó Loop Over Items e mantenha conjuntos de dados completos fora do nó Code.
Ficheiros binários não devem passar pela memória
N8N_DEFAULT_BINARY_DATA_MODE assume default por predefinição, mantendo os dados binários na memória da execução em curso. Os ficheiros que um workflow descarrega aumentam esse consumo de memória. Um workflow que obtenha alguns anexos grandes pode fazer o processo ultrapassar um limite que operações normais com JSON nunca atingem. Por isso, a falha ocorre com um workflow específico e não em função do tempo.
environment:
- N8N_DEFAULT_BINARY_DATA_MODE=filesystemCom filesystem, os dados binários são gravados em N8N_BINARY_DATA_STORAGE_PATH. Por predefinição, esse caminho fica dentro da pasta de utilizador do n8n e, por isso, no mesmo volume que todo o resto. Confirme se o volume tem espaço suficiente antes de ativar esta opção. N8N_PAYLOAD_SIZE_MAX define o tamanho máximo do payload recebido por webhook em MiB (mebibytes) e assume 16 por predefinição. Aumentar este valor permite receber pedidos maiores, mas implica aceitar o respetivo custo de memória.
Tudo o que partilha o servidor compete pela mesma RAM. Se os processos OOM começaram depois de adicionar um contentor de base de dados, executar a base de dados no Docker ou no host é a decisão com essa consequência.
Política de reinício e recuperação após um reboot
Um contentor sem uma política de reinício permanece parado depois de terminar e depois de o host reiniciar. restart: unless-stopped volta a iniciá-lo em ambos os casos, mas respeita um contentor que tenha sido parado manualmente. restart: always também reinicia um contentor parado deliberadamente quando o Docker voltar a iniciar.
O n8n disponibiliza um endpoint de integridade, identificado por N8N_ENDPOINT_HEALTH, que por predefinição é healthz. Consulte-o primeiro a partir do host para confirmar que o caminho está correto na sua instância.
curl -fsS http://127.0.0.1:5678/healthz
docker exec n8n which wget curl
sudo systemctl is-enabled dockerUm healthcheck, por si só, não reinicia nada. O Compose marca o contentor como não saudável e não faz mais nada; uma política de reinício atua quando o contentor termina, enquanto é necessário um monitor externo para reiniciar um contentor especificamente por estar não saudável. Escrever um healthcheck que atua efetivamente e fazer o stack arrancar novamente depois de um reboot abrangem ambas as partes.
O workflow que nunca é executado enquanto o n8n funciona
Este não exibe nenhum banner nem reinicia. O contentor está ativo, o editor funciona e a execução esperada não aparece na lista de execuções. Verifique estes quatro pontos.
- O workflow não está publicado. Guarde e publique um workflow que use o Schedule Trigger para que a sua agenda de produção seja executada.
- O fuso horário não é o seu. O Schedule Trigger usa primeiro o fuso horário do workflow e, se nenhum estiver definido, usa o fuso horário da instância.
GENERIC_TIMEZONEusaAmerica/New_Yorkpor predefinição; defina o fuso horário do workflow ou altere o fuso horário predefinido da instância para o seu. - A execução ultrapassou o período de tolerância. O agendador persistente está ativado por predefinição a partir do n8n 2.45.0 e regista as próximas execuções na base de dados. As execuções registadas são iniciadas com atraso depois de um reinício dentro do respetivo período de tolerância; depois desse período, a política de execuções perdidas configurada decide se devem ser ignoradas ou se deve ser criada uma execução de recuperação. O agendador antigo, em memória, ignora as execuções previstas durante o período de indisponibilidade.
- O workflow foi desativado automaticamente.
N8N_WORKFLOW_AUTODEACTIVATION_ENABLEDestá desativado por predefinição. Quando está ativado, um workflow que continua a falhar deixa de ser publicado. Depois disso, comporta-se exatamente como um workflow que nunca foi ativado.
Abra a lista de execuções e filtre pelo workflow. Uma entrada com falha indica um problema no workflow. Se a execução falhou com um erro 429 contra outro serviço alojado no mesmo servidor, o limite pertence a esse serviço, não ao n8n. O guia sobre erros 429 do SearXNG mostra como distinguir o seu próprio limitador de taxa dos mecanismos que estão a bloquear o endereço IP do servidor. A ausência total de entradas também ocorre quando o armazenamento de execuções está desativado ou quando a limpeza automática removeu o registo. Verifique estas definições antes de considerar que o problema está no trigger.
O que mudar primeiro
- Leia
STATUS,RestartCounteOOMKilledno seu próprio contentor antes de editar qualquer ficheiro. - Se o contentor permaneceu ativo, verifique a acessibilidade do n8n e a disponibilidade da base de dados. Em seguida, analise a ligação push à procura de erros de proxy, autenticação, origem ou timeout.
- Se
OOMKilledfor verdadeiro, defina deliberadamente um limite para o contentor, deixe margem abaixo desse limite ao configurar o limite máximo de heap do Node e mude os dados binários parafilesystem. - Se nada tiver sido acionado, confirme se o workflow está publicado, se o fuso horário efetivo é o seu e se as definições do scheduler e de misfire correspondem às suas expectativas.
A maior parte desta configuração é definida uma vez e depois fica esquecida, sobre uma instalação funcional. Se ainda estiver a preparar essa instalação, o guia para executar o n8n no Docker com HTTPS é a base a que estas definições pertencem.
FAQ
Por que o editor do n8n mostra um aviso de ligação perdida quando o contentor está em execução?
O editor mantém um WebSocket aberto para transmitir o progresso da execução. Se o reverse proxy não encaminhar os cabeçalhos Connection: Upgrade e Upgrade: websocket, ou não usar HTTP/1.1 no upstream, a atualização nunca é concluída e o navegador tenta ligar-se novamente sem parar, enquanto o n8n continua saudável. No nginx, precisa das duas linhas proxy_set_header e de proxy_http_version 1.1 em releases anteriores à 1.29.7 (as mais recentes usam HTTP/1.1 por predefinição). Aumentar proxy_read_timeout acima do valor predefinido de 60 segundos dá tempo para os pings periódicos do n8n chegarem; os workflows silenciosos, por si só, não tornam a ligação inativa. O n8n também rejeita pedidos push inválidos e falhas de autenticação, por isso consulte a resposta e os logs da aplicação. Verifique os ficheiros de configuração com sudo nginx -T e confirme que o reload foi concluído com sucesso.
Como distingo uma terminação por falta de memória de um crash normal?
Execute docker inspect n8n | grep -iE 'OOMKilled|ExitCode|RestartCount' e leia a flag OOMKilled. O valor True significa que o Docker registou uma terminação por falta de memória; o processo afetado não tem oportunidade de escrever uma entrada final no log, embora os logs anteriores do contentor ainda possam ajudar. O valor False, juntamente com um erro fatal de heap no final de docker logs, indica que o Node.js esgotou o heap do V8. Defina NODE_OPTIONS=--max-old-space-size=SIZE com um tamanho numérico em MiB inferior ao limite do contentor, deixando espaço para outras utilizações de memória. Isto limita o old space do V8, mas não garante que ocorra um erro de heap antes de uma terminação por OOM do kernel.
A limpeza dos dados de execução liberta espaço em disco imediatamente?
Não. EXECUTIONS_DATA_PRUNE marca as execuções antigas para eliminação e uma passagem posterior remove-as, de acordo com o calendário definido por EXECUTIONS_DATA_PRUNE_HARD_DELETE_INTERVAL. Com SQLite, o ficheiro também reutiliza as páginas libertadas em vez de as devolver ao sistema de ficheiros, por isso o tamanho em disco mantém-se estável durante algum tempo depois de as linhas serem removidas. Defina EXECUTIONS_DATA_MAX_AGE e EXECUTIONS_DATA_PRUNE_MAX_COUNT com valores adequados ao seu servidor e verifique novamente no dia seguinte, em vez de verificar imediatamente.
Por que o meu workflow agendado não foi executado enquanto o n8n reiniciava?
O scheduler persistente, ativado por predefinição desde o n8n 2.45.0, guarda na base de dados as próximas execuções. As execuções registadas são iniciadas com atraso quando o n8n regressa dentro do respetivo período de tolerância. Depois desse período, a política de misfire do trigger decide se deve ignorar o backlog ou executar uma recuperação. Verifique a versão, a configuração do scheduler e as opções do Schedule Trigger. As instâncias que usam o scheduler antigo em memória ignoram as execuções previstas durante a indisponibilidade.
Um healthcheck reinicia o n8n quando este deixa de responder?
Não por si só. Um healthcheck do Compose apenas marca o contentor como saudável ou não saudável. Uma política de restart atua quando o contentor termina, por isso restart: unless-stopped volta a iniciá-lo depois de uma terminação e após um reboot do host, desde que não tenha sido parado deliberadamente e que o Docker arranque. Confirme isso com sudo systemctl is-enabled docker. Para agir especificamente quando o contentor está não saudável, precisa de um watcher externo ao Docker que leia o estado e reinicie o serviço.