n8n 3.0 exige Docker: por que sua instalação self-hosted vai precisar de uma migração (e não de um update)

A n8n publicou a lista de mudanças que chegam com a versão 3.0, prevista para outubro de 2026. Entre elas há uma que muda a rotina de quem mantém a ferramenta em servidor próprio: o self-hosted passa a exigir deployment baseado em Docker. Instalações feitas via npm ou npx n8n deixam de ser suportadas.

Se a sua automação roda hoje com Node.js e n8n instalado por npm, seja em uma VPS, em um servidor dentro da empresa ou até em um computador que fica ligado no escritório, o caminho que você usou nas últimas atualizações deixa de existir. Não haverá um comando de update que resolva. Haverá uma migração.

Vale separar as duas coisas, porque elas têm riscos bem diferentes.

Um update mantém o mesmo ambiente e troca a versão do software. Uma migração move dados, credenciais e configuração de um ambiente para outro. É nesse movimento que as coisas se perdem.

O que muda além do Docker

A obrigatoriedade do container é a mudança mais visível, mas não é a única. A versão 3.0 também aposenta nós, recursos e comportamentos que ainda aparecem em muitos fluxos antigos, e endurece os padrões de segurança da ferramenta. Na prática, isso significa que mesmo um container que suba sem nenhum erro pode conter fluxos que simplesmente pararam de funcionar, porque dependem de um componente que não existe mais. E fluxo que para sem alarde costuma ser descoberto pelo cliente, não pelo time.

Vamos tratar dessa parte em um próximo post, item a item, com os substitutos recomendados para cada componente removido e o que revisar nos fluxos existentes.

Por que “subir um docker compose” é mais arriscado do que parece

A internet está cheia de tutoriais que resolvem a instalação do n8n em três linhas. Eles funcionam muito bem para quem está começando do zero. O problema é aplicar essa mesma receita sobre um ambiente que já está em produção, com integrações ativas e histórico acumulado.

Alguns pontos que costumam derrubar migrações feitas às pressas:

A chave de criptografia. O n8n cifra as credenciais salvas usando uma chave gerada na instalação. Se o container subir com uma chave nova, todas as credenciais existentes se tornam ilegíveis. Na prática, isso significa reconectar manualmente cada integração: contas de e-mail, CRMs, gateways de pagamento, APIs internas. Em ambientes maduros, são dezenas.

O banco de dados. Instalações via npm normalmente usam SQLite, gravado em um arquivo no diretório do usuário. Se o volume não for mapeado corretamente, o container sobe limpo, com a interface funcionando e nenhum workflow dentro. É o cenário que mais assusta: aparentemente tudo certo, e o histórico inteiro fora do ar.

As variáveis de ambiente. Configurações que hoje vivem no serviço do systemd, em um gerenciador de processos ou no próprio shell precisam ser transportadas para o compose. Fuso horário, política de retenção de execuções, limites de concorrência e endereço público entram nessa lista.

Os webhooks. Serviços externos guardam a URL que você cadastrou neles. Se o endereço público muda durante a migração, ou se o proxy reverso é reconfigurado sem atenção, os gatilhos param de chegar sem gerar nenhum erro visível no n8n.

O que estava fora do n8n. Nós da comunidade instalados via npm, scripts auxiliares, arquivos lidos ou gravados em pastas locais e permissões de diretório mudam de contexto dentro de um container. Nada disso migra sozinho.

A migração como oportunidade de revisão

Trocar a forma de execução obriga a abrir o ambiente. É um bom momento para corrigir decisões que foram tomadas quando a automação ainda era um experimento e nunca mais foram revisitadas.

Sair do SQLite e adotar PostgreSQL é a mudança de maior impacto. O SQLite atende bem no início, mas sofre com concorrência, cresce sem controle conforme o histórico de execuções aumenta e torna backup e restauração mais frágeis. O PostgreSQL sustenta volume, permite backup consistente sem parar o serviço e é pré-requisito para rodar o n8n em modo fila, com workers separados, quando o número de execuções justificar.

Outros pontos que valem entrar no escopo:

• Backup automatizado e, principalmente, teste de restauração. Backup que nunca foi restaurado é uma suposição, não uma garantia.
• Um ambiente de homologação separado da produção, para validar alterações antes de publicá-las.
• Versionamento dos workflows, com histórico de quem mudou o quê.
• Monitoramento e alerta para execuções que falham, em vez de depender de alguém abrir a tela e conferir.
• Política de atualização com versão fixada, evitando que uma imagem latest mude o comportamento do ambiente sem aviso.

Como uma migração bem feita acontece

O roteiro é conhecido e não tem mistério, mas exige método:

1. Inventário do ambiente atual: versão em uso, credenciais ativas, workflows em produção, nós descontinuados em uso, integrações que dependem de URL pública e variáveis de configuração.
2. Réplica paralela em containers, com o banco migrado e a chave de criptografia preservada, sem tocar na instalação atual.
3. Validação fluxo a fluxo, incluindo os que rodam por agendamento e podem não aparecer em um teste rápido.
4. Ajuste dos nós removidos e das expressões afetadas, com o comportamento comparado ao da versão antiga.
5. Virada de chave planejada, em janela definida, com o ambiente antigo preservado.
6. Plano de rollback escrito antes, não improvisado durante.

A ordem importa. A produção só é desligada depois que a nova instalação provou que funciona.

Onde entra uma consultoria especializada

Se o seu n8n roda dois fluxos simples e nenhuma credencial crítica, um fim de semana e um tutorial provavelmente resolvem.

Se ele sustenta operação, atendimento, cobrança ou entrega de serviço para clientes, o cálculo muda. O custo de uma migração mal feita não é o tempo de servidor: é o pedido que não foi processado, o lead que não entrou no CRM, a cobrança que não foi disparada e a semana de trabalho gasta reconectando integrações uma a uma.

Na n8nscale trabalhamos exatamente nesse ponto. Conduzimos a migração para Docker preservando credenciais e histórico, revisamos os fluxos que dependem de nós descontinuados, movemos a base para PostgreSQL quando o cenário justifica e deixamos backup, monitoramento e processo de atualização documentados. Você recebe o ambiente funcionando e a operação segue rodando durante todo o processo.

Outubro parece distante. Mas o inventário do que você tem hoje é a parte que ninguém quer fazer com pressa.

Quer saber em que estado está o seu ambiente antes da 3.0? Fale com a n8nscale e receba um diagnóstico da sua instalação atual, com os pontos de risco mapeados.

---

Fonte oficial das mudanças: n8n Docs — v3.0 Breaking changes