Como fazer self-host do n8n em 2026: deploy, TLS, webhooks e backups

Um container do n8n pode estar funcionando enquanto o trabalho que realmente importa para os usuários está quebrado. No n8n, essa falha oculta geralmente significa que os links de webhook ainda apontam para localhost ou que os headers do proxy informam HTTP. Este guia considera como teste de aceitação “ativar um workflow com um webhook de produção, chamar esse webhook de fora do servidor e confirmar que a execução chega ao nó final” e estrutura o deployment de trás para frente a partir desse resultado.

O n8n tem um papel específico na stack: automação de workflows com mais de 400 integrações e um sistema de nós extensível. Portanto, a questão em produção não é se a porta 5678 responde uma vez, mas se o estado, as dependências e o endereço público continuam consistentes depois de um restart, update e restore.

Separe containers substituíveis dos dados persistentes

Defina o recovery point e o recovery time do n8n considerando o banco de dados, além dos dados de encriptação e configuração do .n8n. Monte /home/node/.n8n antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para comprovar que esse caminho é realmente persistente. Um named volume resolve a persistência entre redeploys; ele não resolve problemas de comprometimento nem a perda do servidor.

Crie um ambiente de restore limpo, use a mesma versão fixada da aplicação e comprove que as credenciais restauradas continuam sendo descriptografadas e que um workflow restaurado recebe a mesma URL pública de webhook. Registre os comandos, os ajustes de ownership e o tempo decorrido. O guia de backup é um padrão útil: um backup só é confiável depois do restore, não depois do upload.

Torne o startup do n8n reproduzível

Um comando mínimo é útil quando revela o que a plataforma gerenciará posteriormente.

docker run -d \
  --name n8n \
  --restart unless-stopped \
  -p 127.0.0.1:5678:5678 \
  -v n8n-data:/home/node/.n8n \
  -e N8N_ENCRYPTION_KEY=replace-with-a-long-random-value \
  docker.n8n.io/n8nio/n8n

Aqui, a porta 5678 continua privada no host e todos os caminhos necessários estão explícitos. Adicione as configurações de conexão revisadas para Postgres em um setup de produção durável e multiusuário; use nomes privados para serviços privados. Verifique o startup tanto pelos logs quanto pela validação específica da aplicação: ative um workflow com um webhook de produção, chame esse webhook de fora do servidor e confirme que a execução chega ao nó final. Depois da validação, fixe a versão da imagem para que uma substituição rotineira não altere o comportamento silenciosamente.

Portas, processos e serviços privados

Comece pelo namespace de rede do n8n: o listener web usa a porta 5678, não uma porta do host copiada de um tutorial para laptop. O contrato de rede do n8n é o Postgres para um setup de produção durável e multiusuário. Mantenha endpoints privados no DNS interno, permita apenas as chamadas de saída necessárias e forneça ao n8n uma credencial de serviço com escopo limitado.

Depois que o requisito for atendido, execute o cenário completo — ative um workflow com um webhook de produção, chame esse webhook de fora do servidor e confirme que a execução chega ao nó final. Registre logs e métricas de execução para concorrência de execuções, profundidade da fila, tamanho de payloads binários e nós de longa duração, em vez de visualizações das páginas do editor. Essas evidências se tornam a primeira arquitetura conhecida como funcional e permitem testar migrações futuras entre o compute da Dockup e um servidor conectado.

Evite que o sucesso do proxy mascare falhas da aplicação

A borda pública do n8n deve ser um único hostname canônico, com TLS automático e um único target interno na porta 5678. Defina WEBHOOK_URL como a URL HTTPS externa exata para que os clientes retornem a um endereço reconhecido pelo serviço.

Se a transação de aceitação falhar, classifique o primeiro erro. Problemas de DNS, certificado e 502 pertencem ao checklist de validação de TLS. A condição “os links de webhook continuam apontando para localhost ou os headers do proxy informam HTTP” pertence ao lado da aplicação, depois que uma requisição tiver chegado com sucesso ao n8n.

O que deve passar antes que dados reais do n8n cheguem

Transforme o smoke test do n8n em um comando de release reproduzível ou em um runbook curto. A saída deve demonstrar este resultado: ativar um workflow com um webhook de produção, chamar esse webhook de fora do servidor e confirmar que a execução chega ao nó final. Registre a versão da aplicação, o digest do container, o hostname da rota e o identificador dos dados de teste junto com o resultado.

Execute a mesma verificação depois de uma troca rotineira de container e após restaurar o banco de dados e os dados de encriptação e configuração do .n8n em outro local. O restore terá sido bem-sucedido quando as credenciais restauradas continuarem sendo descriptografadas e um workflow restaurado receber a mesma URL pública de webhook. Compare o tempo e o consumo relacionados à concorrência de execuções, à profundidade da fila, ao tamanho de payloads binários e aos nós de longa duração, em vez de visualizações das páginas do editor; uma grande alteração merece investigação mesmo quando a ação final continua passando.

Depois, simule uma falha segura: negue temporariamente à identidade de teste o acesso ao Postgres para um setup de produção durável e multiusuário. Confirme que o n8n expõe a falha e retorna ao funcionamento normal sem edições manuais destrutivas. Preserve apenas o trecho de log necessário e com dados redacted. Esse gate de quatro partes cobre startup, persistência, recuperação e tratamento de falhas.

Verificações de capacidade e upgrade

Crie dashboards com base na concorrência de execuções, na profundidade da fila, no tamanho de payloads binários e nos nós de longa duração, em vez de visualizações das páginas do editor. Um gráfico de CPU sem o contexto dessa carga não explica por que o n8n está lento. Adicione uma verificação sintética ou agendada que tente ativar um workflow com um webhook de produção, chamar esse webhook de fora do servidor e confirmar que a execução chega ao nó final usando dados de teste inofensivos.

Antes de fazer upgrade, considere este risco específico da aplicação: as migrações do banco de dados, a encriptação de credenciais e os community nodes instalados precisam permanecer compatíveis com a release de destino do n8n. Restaure um backup recente em um deployment isolado, execute as migrações nele e compare o comportamento. Se os links de webhook continuarem apontando para localhost ou os headers do proxy informarem HTTP, inspecione a fronteira envolvida — origem pública, armazenamento ou dependência — antes de alterar configurações não relacionadas.

Proteja o n8n depois do bootstrap

Não herde as premissas de segurança de um tutorial local. A preocupação específica do n8n é fazer a rotação de N8N_ENCRYPTION_KEY depois que as credenciais tiverem sido salvas. Por isso, em produção o editor deve continuar autenticado, enquanto apenas os caminhos de webhook de que as integrações realmente precisam devem ser expostos.

Gere N8N_ENCRYPTION_KEY uma única vez, mantenha-o fora do Git e preserve-o com o manifest de recuperação, porque alterá-lo pode invalidar o estado criptografado ou assinado da aplicação. Restrinja o acesso ao filesystem e à rede, proteja os endpoints de setup e defina limites de upload, requisições ou execuções com base na concorrência de execuções, na profundidade da fila, no tamanho de payloads binários e nos nós de longa duração, em vez de visualizações das páginas do editor.

Mantenha o n8n explícito enquanto a Dockup gerencia o roteamento

O deployment de n8n com um clique da Dockup deve tornar a substituição segura: a rota continua apontando para 5678, os secrets não são incorporados à imagem e os caminhos persistentes retornam no novo container. O mesmo deployment pode ser executado no compute da Dockup ou em uma máquina conectada.

Conclua o trabalho específico da aplicação conectando e testando o Postgres para um setup de produção durável e multiusuário, aplicando o endereço público canônico e executando esta verificação de aceitação: ative um workflow com um webhook de produção, chame esse webhook de fora do servidor e confirme que a execução chega ao nó final. Adicione o resultado do restore ao runbook antes da chegada dos usuários reais.

Perguntas frequentes

O que o n8n precisa para um deployment de produção?

Roteie o container do n8n na porta 5678 por meio de uma única origem HTTPS. O requisito de rede de suporte é o Postgres para um setup de produção durável e multiusuário. Não considere o n8n pronto até conseguir ativar um workflow com um webhook de produção, chamar esse webhook de fora do servidor e confirmar que a execução chega ao nó final.

Quais dados do n8n devem fazer parte de um backup?

Persista /home/node/.n8n e inclua o banco de dados, além dos dados de encriptação e configuração do .n8n, no mesmo manifest de recuperação. Um restore limpo do n8n só é aprovado quando as credenciais restauradas continuam sendo descriptografadas e um workflow restaurado recebe a mesma URL pública de webhook.

O n8n precisa de HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do n8n e mantenha a porta 5678 na rota interna. Aplique corretamente a configuração do n8n: defina WEBHOOK_URL como a URL HTTPS externa exata. Para o n8n, o HTTPS protege credenciais ou conteúdo de usuários em trânsito e mantém consistente o comportamento dos clientes sensível à origem.

Como testar um upgrade do n8n?

Restaure o estado atual do n8n em um deployment isolado, aplique a versão candidata e repita sua transação de aceitação. Preste atenção especial, pois as migrações do banco de dados, a encriptação de credenciais e os community nodes instalados precisam permanecer compatíveis com a release de destino do n8n. Mantenha a imagem anterior do n8n até entender os limites de migração de dados e rollback.