SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

Como atualizar o n8n self-hosted da 2.x para a 3.0

O n8n 3.0 está em beta e a versão estável está prevista para o início de dezembro. Veja a ordem segura no Docker: Migration Report, backup completo, cópia de teste e o que quebra.

Como atualizar o n8n self-hosted da 2.x para a 3.0 sem perder dados

Para atualizar o n8n self-hosted da 2.x para a 3.0, siga esta ordem: saia do npm para o Docker ainda na 2.x, suba para a 2.x mais recente, abra o Migration Report e corrija o que ele aponta. Depois faça um backup completo e teste a 3.0 numa cópia antes da produção. Não existe volta da 3.x para a 2.x, então o backup é a sua única forma de desfazer a atualização.

A data importa. Em 2 de novembro de 2026, a 3.0.0 ainda é um beta. Ela saiu em 27 de outubro de 2026, sem cadastro, e a página de mudanças da 3.0 a descreve como "early access release". A versão estável está planejada para o início de dezembro, segundo o anúncio oficial no fórum do n8n. "Início de dezembro" é um plano. Não é uma data.

Este guia parte de um n8n rodando numa VPS (servidor virtual privado) com Docker Compose, como no guia de instalar o n8n com Docker e HTTPS numa VPS. Também cobre quem usa um template de painel e quem ainda roda com npm.

Preciso atualizar para o n8n 3.0 agora?

Não. Para uma instalação de produção, ficar numa 2.x fixada até a estável sair é um plano válido. O anúncio diz que a 2.x continua recebendo correções de segurança e de bugs críticos por 12 meses depois do lançamento da 3.x estável. Esses 12 meses só começam quando a estável sair.

A pressa é de quem ainda está na 1.x. O suporte à 1.x termina em 31 de dezembro de 2026. E não há caminho direto da 1.x para a 3.x: o n8n pede para subir primeiro para a v2 e só depois para a v3. Se você está na 1.x, o trabalho deste mês é chegar a uma 2.x atual. Leia as notas da 2.0 antes desse salto.

Para quem já está na 2.x, novembro serve para preparar a instalação. O beta dá tempo de limpar o Migration Report e de testar uma cópia sem pressa.

Passo 1: saia do npm e vá para o Docker, ainda na 2.x

A 3.0 exige uma instalação baseada em Docker. A página de mudanças diz que instalações com npm (o gerenciador de pacotes do Node.js) ou npx n8n não são mais suportadas. Ela também diz que a 3.0 não publica um pacote n8n executável no npm. Segundo o anúncio, instalações com Kubernetes e Helm não são afetadas.

Faça essa troca agora, enquanto ainda está na 2.x. Assim você muda uma coisa por vez: primeiro o jeito de rodar, depois a versão. Se algo quebrar, você sabe qual das duas mudanças causou o problema.

Quem já usa um arquivo Docker Compose próprio não precisa mudar nada aqui. A página de mudanças diz isso de forma explícita. Quem usa um template de painel, como Coolify ou EasyPanel, deve abrir a configuração do serviço e olhar o campo da imagem. Se ele mostra n8nio/n8n, você já está no Docker.

Na instalação npm, exporte os workflows e as credenciais com a CLI (interface de linha de comando) do próprio n8n:

mkdir -p backups/latest
n8n export:workflow --backup --output=backups/latest/
n8n export:credentials --all --decrypted --output=backups/decrypted.json

A flag --backup equivale a --all --pretty --separate, então cada workflow vira um arquivo JSON na pasta. As credenciais saem em texto puro por causa do --decrypted. A documentação da CLI indica esse formato para migrar para uma instalação com outra chave de criptografia, que é o caso de um container novo. A mesma documentação avisa: todos os segredos ficam visíveis nesse arquivo. Apague-o assim que o import terminar.

Suba o n8n no Docker com uma tag 2.x fixa (veja o passo 2) e importe os arquivos dentro do container:

docker compose cp backups n8n:/home/node/backups
docker compose exec -u root n8n chown -R node:node /home/node/backups
docker compose exec -u node n8n n8n import:workflow --separate --input=/home/node/backups/latest/
docker compose exec -u node n8n n8n import:credentials --input=/home/node/backups/decrypted.json
docker compose exec -u root n8n rm -rf /home/node/backups
rm -rf backups

O chown existe porque o Docker cria como root os arquivos copiados para dentro do container. Sem ele, o usuário node, que roda o n8n, pode não conseguir ler o arquivo de credenciais. Abra o editor depois do import e confira se os workflows e as credenciais estão lá.

Passo 2: fixe uma tag 2.x exata e atualize

A imagem oficial se chama n8nio/n8n. No Compose, escreva a versão exata:

services:
  n8n:
    image: n8nio/n8n:2.47.7

Em 15 de novembro de 2026, o GitHub marca n8n@2.47.7 como Latest, e a página de instalação Docker lista 2.47.7 como a versão estável atual. Esse número vai mudar. Confira a release atual no GitHub do n8n antes de copiar.

Não use latest nem stable no arquivo. Essas tags trocam de versão sem você editar nada, então quem escolhe a versão passa a ser o próximo docker compose pull. Com a tag exata, a versão só muda quando você muda o arquivo.

Também não use a tag beta como atalho para a 3.0. A página de instalação Docker do n8n lista o beta como 2.48.4, e nem o anúncio nem as notas de versão dizem qual tag é o beta da 3.0. Para testar a 3.0, escolha uma tag exata e confira no Docker Hub o que existe no dia.

Depois de editar o Compose, atualize e confira:

docker compose pull n8n
docker compose up -d n8n
docker compose images n8n
docker compose logs --tail=50 n8n

docker compose images deve mostrar a tag que você escreveu. Se ainda aparece a antiga, o container não foi recriado: rode o up -d de novo e leia o log.

Passo 3: abra o Migration Report e limpe a lista

O Migration Report fica em Settings > Migration Report e precisa do n8n 2.39 ou mais novo. A página de mudanças pede para usar essa ferramenta antes de atualizar. Ela lista os workflows e as configurações da instância que precisam de atenção antes da 3.0.

Entre como owner ou admin. Qualquer usuário abre o relatório, mas quem não é admin vê só os workflows que pode editar. A aba Instance issues, que mostra variáveis de ambiente e configurações de deploy, aparece só para owners e admins.

Para alguns problemas, o n8n reescreve os nós por você. Nesses casos, cada linha tem um botão Migrate, e o exemplo da própria documentação é trocar um nó Cron por um Schedule Trigger. O resultado é salvo como uma nova versão do workflow. Um workflow publicado continua rodando a versão atual até você publicar a nova. Por isso a migração automática não muda nada em produção sozinha.

A documentação lembra que a migração automática cobre só mudanças de nós. Teste o workflow migrado e confira se a saída continua igual antes de publicar. Um workflow que você não vai consertar, porque está abandonado, pode ser marcado como Won't fix. Ele conta como resolvido e sai da lista de pendências.

Passo 4: faça um backup completo antes de tocar na 3.0

O anúncio é direto: depois de ir para a 3.x, não há volta para a 2.x. Um backup completo tem duas partes.

A primeira é a pasta de dados, /home/node/.n8n na imagem oficial. A página de instalação Docker diz que essa pasta guarda as chaves de criptografia. Sem a chave certa, as credenciais salvas não podem ser lidas. Se você não configurou Postgres, o n8n usa SQLite por padrão, e o banco fica em ~/.n8n/database.sqlite, dentro dessa mesma pasta.

A segunda é o banco Postgres, se você usa um. Os nomes abaixo (serviço postgres, usuário n8n, banco n8n, volume meuprojeto_n8n_data) são de exemplo. Use os do seu arquivo e do docker volume ls. Sem Postgres, pule a linha do pg_dump.

docker volume ls
docker compose stop n8n
docker run --rm -v meuprojeto_n8n_data:/data:ro -v "$PWD":/backup alpine:3.21 tar czf /backup/n8n-data-2026-11-02.tgz -C /data .
docker compose exec -T postgres pg_dump -U n8n -Fc n8n > n8n-pg-2026-11-02.dump
docker compose start n8n

O n8n fica parado durante a cópia porque um banco SQLite copiado no meio de uma escrita pode sair inconsistente. O -T no exec desliga o terminal interativo, então a saída do pg_dump vai limpa para o arquivo.

Confira os dois arquivos antes de confiar neles:

tar tzf n8n-data-2026-11-02.tgz | head
docker compose exec -T postgres pg_restore --list < n8n-pg-2026-11-02.dump | head

O tar deve listar o conteúdo da pasta .n8n, incluindo ./database.sqlite se você usa SQLite. O pg_restore --list deve imprimir o índice do dump. Um erro aqui significa que o dump está vazio ou corrompido. Guarde também o docker-compose.yml e o .env, porque um N8N_ENCRYPTION_KEY definido ali faz parte do backup. Mantenha uma cópia fora da VPS. O guia de backup e atualização de uma stack Docker Compose mostra como automatizar isso.

Há mais um motivo para guardar a chave. A 3.0 liga por padrão a rotação da chave de criptografia, em Settings > Data Encryption Keys. Antes, no self-hosted, isso era opcional. A página de mudanças diz que os dados criptografados antes da atualização continuam legíveis, e que a partir da 2.40.3 dá para desligar o recurso. Mesmo assim, se precisar voltar para a 2.x, é a chave e o banco de antes que você vai restaurar.

Passo 5: teste a 3.0 numa cópia

O anúncio pede para testar numa instância de teste antes da produção. Numa VPS, a cópia mais simples é um segundo projeto Compose com outro nome, outra porta e os dados restaurados do backup. Supondo que o projeto está em ~/n8n, copie a pasta inteira:

sudo cp -a ~/n8n ~/n8n-teste
cd ~/n8n-teste

No docker-compose.yml da cópia, troque a tag por uma 3.0 exata que você conferiu no Docker Hub. Troque a porta publicada para 127.0.0.1:5679:5678, assim a cópia só responde dentro da própria VPS. Apague qualquer linha container_name, porque dois containers não podem ter o mesmo nome. Se algum volume tem um name: fixo no Compose, troque esse nome também, senão a cópia usa os dados da produção. Se o seu Compose usa pastas locais em vez de volumes nomeados, o cp -a já copiou os dados e você pode pular o restore do volume.

docker compose -p n8n-teste create
docker run --rm -v n8n-teste_n8n_data:/data -v "$HOME/n8n":/backup:ro alpine:3.21 tar xzf /backup/n8n-data-2026-11-02.tgz -C /data
docker compose -p n8n-teste start postgres
docker compose -p n8n-teste logs postgres

Espere até a última linha do log do Postgres ser database system is ready to accept connections. Então restaure o banco e suba o n8n:

docker compose -p n8n-teste exec -T postgres pg_restore -U n8n -d n8n --clean --if-exists < ~/n8n/n8n-pg-2026-11-02.dump
docker compose -p n8n-teste start n8n
docker compose -p n8n-teste logs -f n8n

Do seu computador, abra um túnel SSH e acesse http://localhost:5679 no navegador:

ssh -L 5679:127.0.0.1:5679 usuario@sua-vps

Atenção com gatilhos reais. A cópia tem os mesmos workflows publicados e as mesmas credenciais da produção. Um Schedule Trigger que manda mensagem no WhatsApp às 9h vai mandar a mensagem duas vezes, uma de cada instância. Desligue esses workflows na cópia assim que ela abrir, ou pare a cópia logo depois do teste.

Na cópia, rode à mão os workflows que importam e compare a saída com a da produção. Leia o log inteiro da primeira subida. As armadilhas abaixo aparecem ali.

O que quebra no n8n 3.0 para quem hospeda o próprio servidor

A página de mudanças ainda é de uma versão early access. Releia a página antes de atualizar a produção, porque o conteúdo pode mudar até a estável.

A pasta binaryData vira storage, e o n8n para se as duas existirem

Na primeira subida, a 3.0 renomeia ~/.n8n/binaryData para ~/.n8n/storage. Se as duas pastas já existem, a 3.0 para com um erro em vez de adivinhar qual usar. Confira antes, ainda na 2.x:

docker compose exec n8n ls -la /home/node/.n8n

Se aparecem binaryData e storage ao mesmo tempo, descubra qual tem os arquivos reais e resolva antes de atualizar. Para manter o caminho antigo, defina N8N_STORAGE_PATH com ele. A variável N8N_MIGRATE_FS_STORAGE_PATH foi removida.

Na mesma área, N8N_DEFAULT_BINARY_DATA_MODE=default deixa de ser válido. Instâncias com esse valor passam para filesystem na atualização. Defina o valor de forma explícita: filesystem, s3, azure ou database.

O Code node agora tem 1 minuto, não 5

O padrão de N8N_RUNNERS_TASK_TIMEOUT cai de 300 (5 minutos) para 60 (1 minuto). Um Code node que processa uma planilha grande e levava 2 minutos na 2.x vai ser interrompido na 3.0. Se você tem tarefas assim, defina o valor no environment do serviço:

    environment:
      - N8N_RUNNERS_TASK_TIMEOUT=300

Community nodes não verificados ficam desligados: atenção no WhatsApp

O padrão de N8N_UNVERIFIED_PACKAGES_ENABLED muda de true para false. Depois da atualização, você não consegue instalar community nodes não verificados pelo npm, e os que já estão instalados param de carregar. Um workflow que depende de um nó que não carrega deixa de funcionar.

Isso pesa no Brasil, onde muita automação de WhatsApp roda com pacotes da comunidade, como os da Evolution API. Não deduza se o seu pacote é verificado, nem num sentido nem no outro. Confira cada um. Os nós verificados aparecem no painel de nós do editor, na seção More from the community, e só owners e admins podem instalar e gerenciar esses nós. Desde 1 de maio de 2026, um nó enviado para verificação precisa ser publicado com GitHub Actions e uma declaração de procedência (provenance), e não pode ter dependências em tempo de execução.

Para cada pacote não verificado, você tem dois caminhos. O primeiro é definir N8N_UNVERIFIED_PACKAGES_ENABLED=true e continuar como antes, sabendo que esse código não passou pela revisão do n8n. O segundo é trocar por um nó verificado. Quando a integração é uma API HTTP, como a da Evolution API, o nó HTTP Request do próprio n8n também chama a API sem pacote nenhum.

Execuções manuais vão para os workers no queue mode

A variável OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS foi removida. No queue mode, as execuções manuais agora sempre rodam nos workers. Apague a variável do seu .env e revise a memória dos workers, que passam a receber também os testes feitos no editor. Isso só afeta quem usa o queue mode do n8n numa única VPS ou em várias máquinas.

Nós removidos e o que usar no lugar

Um workflow que usa um nó removido falha quando roda. Um workflow publicado com um nó removido não é ativado quando a 3.0 sobe, então os gatilhos dele param de disparar. As trocas indicadas pelo n8n:

  • Function: Code node, no modo Run Once for All Items.
  • Function Item: Code node, no modo Run Once for Each Item.
  • Item Lists: Split Out, Aggregate, Sort, Limit, Remove Duplicates ou Summarize, conforme a operação que você usava.
  • Cron e Interval: Schedule Trigger.
  • OpenAI legado e OpenAI Assistant: o nó OpenAI atual, que continua na seção de IA.
  • AI Agent versão 1: a versão mais nova do nó, que usa o Tools Agent no lugar dos modos removidos. Para o caso do SQL Agent, use um sub-nó de ferramenta Postgres ou MySQL ligado a um AI Agent recente.

O LangChain Code node e os nós Motorhead, Zep e SerpApi não têm substituto direto. Se você usa algum deles, planeje a troca antes, porque não há botão que resolva. O Migration Report mostra quais workflows usam cada nó.

Depois da estável: atualizar a produção

Quando a 3.x estável sair e a cópia de teste passar, a atualização da produção é curta. Confira que o Migration Report está limpo. Faça um backup novo no mesmo dia, com os comandos do passo 4. Troque a tag no Compose para a 3.x exata, rode docker compose pull n8n e docker compose up -d n8n, e acompanhe o log da primeira subida.

Se der errado, a volta é restaurar o backup. Primeiro, volte a tag da imagem no Compose para a 2.x exata de antes. Depois apague os volumes e restaure. Os nomes de volume abaixo são de exemplo, e o do Postgres aparece no docker volume ls. Sem Postgres, pule as linhas do postgres.

docker compose down
docker volume rm meuprojeto_n8n_data meuprojeto_db_storage
docker compose create
docker run --rm -v meuprojeto_n8n_data:/data -v "$PWD":/backup:ro alpine:3.21 tar xzf /backup/n8n-data-2026-11-02.tgz -C /data
docker compose start postgres
docker compose exec -T postgres pg_restore -U n8n -d n8n --clean --if-exists < n8n-pg-2026-11-02.dump
docker compose start n8n

Entre o start postgres e o pg_restore, espere o Postgres aceitar conexões, como no passo 5. O volume do Postgres também é apagado para que a 2.x encontre exatamente o banco do backup, sem nada que a 3.0 tenha criado depois. Tudo o que aconteceu entre o backup e a restauração se perde, incluindo execuções e workflows editados nesse intervalo. Por isso o backup precisa ser do mesmo dia da atualização.

FAQ

O n8n 3.0 já é estável?

Não, em 2 de novembro de 2026. A 3.0.0 saiu como beta em 27 de outubro de 2026, o GitHub marca a release como Pre-release e a documentação a chama de early access. O anúncio do n8n planeja a 3.x estável para o início de dezembro. Até lá, a produção pode ficar numa tag 2.x exata, porque a 2.x recebe correções de segurança e de bugs críticos por 12 meses depois da estável.

Posso atualizar o n8n direto da 1.x para a 3.0?

Não. O anúncio diz que não há caminho direto da v1 para a v3: suba primeiro para a 2.x e só depois para a 3.x. O suporte à 1.x termina em 31 de dezembro de 2026. Na 2.x, use o Migration Report (Settings > Migration Report, a partir da 2.39) antes de pensar na 3.0.

Meu nó da Evolution API para o WhatsApp vai parar na 3.0?

Depende de o pacote ser verificado. Na 3.0, N8N_UNVERIFIED_PACKAGES_ENABLED passa a ser false por padrão, e community nodes não verificados param de carregar. Confira o seu pacote no painel de nós, na seção More from the community. Se ele não for verificado, defina a variável como true ou troque o pacote por um nó verificado. Para uma API HTTP como a da Evolution API, o nó HTTP Request do n8n também serve.

Como volto para a 2.x se a 3.0 der problema?

Só restaurando um backup. O n8n diz que não há volta da 3.x para a 2.x. Pare a stack, volte a tag da imagem para a 2.x exata de antes, restaure a pasta /home/node/.n8n e o dump do Postgres, e suba de novo. Sem um backup feito antes da atualização, com a chave de criptografia junto, não há rollback.

Este artigo foi útil?