Alterações significativas no n8n v2.0

O n8n v2.0 será lançado em breve. Este documento destaca as alterações mais importantes e as ações que você deve tomar para preparar sua transição. Essas atualizações melhoram a segurança, simplificam a configuração e removem funcionalidades legadas.

O lançamento do n8n 2.0 reforça o compromisso contínuo do n8n com a entrega de uma plataforma de automação segura, confiável e pronta para produção. Esta versão principal inclui melhorias significativas de segurança e a remoção de funcionalidades obsoletas.

Alterações de comportamento

Retorno dos dados esperados ao retomar subfluxos de trabalho em estado de espera

Anteriormente, quando uma execução pai chamava uma execução filha contendo um nó que colocava a execução filha em estado de espera — e a execução pai estava configurada para aguardar a conclusão da filha —, a execução pai recebia resultados incorretos.

Por exemplo, isso ocorria quando a execução filha continha um nó Wait com tempo limite superior a 65 segundos, chamadas de webhook, envios de formulário ou nós de revisão manual (como o nó do Slack).

Fluxo de trabalho pai:

Fluxo de trabalho filho:

v1: A execução pai retornava a entrada da execução filha como sua própria saída:

v2: A execução pai recebe o resultado da execução filha:

Isso permite usar nós de revisão manual em fluxos de trabalho filhos e utilizar seus resultados no fluxo pai (por exemplo, aprovar ou rejeitar uma ação).

Como migrar: Revise todos os fluxos de trabalho que chamam subfluxos e esperam receber a entrada do subfluxo. Atualize esses fluxos para se adaptarem ao novo comportamento: o fluxo pai agora receberá a saída final do fluxo filho, e não sua entrada.

Remoção do nó Start

O nó Start não é mais suportado. Ele era o método original para iniciar fluxos de trabalho, mas foi substituído por gatilhos mais específicos.

Como migrar: Substitua o nó Start conforme o uso do seu fluxo:

• Execução manual: Substitua o nó Start pelo nó Manual Trigger.
• Subfluxo de trabalho: Se outro fluxo chamar este como subfluxo, substitua o nó Start pelo nó Execute Workflow Trigger e ative o fluxo.
• Nó Start desativado: Se o nó Start já estiver desativado, remova-o do fluxo de trabalho.

Salvar e publicar fluxos de trabalho

O novo sistema de publicação de fluxos de trabalho substitui o antigo interruptor de ativação/desativação. O antigo botão "Ativar/Desativar" tornou-se o novo botão Publicar/Cancelar publicação. Essa mudança oferece melhor controle sobre o momento exato em que as alterações entram em produção, reduzindo o risco de implantação acidental de mudanças em andamento. Para mais informações, consulte a documentação sobre salvar e publicar fluxos de trabalho.

Remoção de nós de serviços descontinuados

Os seguintes nós foram removidos porque os serviços externos aos quais se conectavam não estão mais disponíveis:

• Nó Spontit
• Nó crowd.dev
• Nó Kitemaker
• Nó Automizy

Como migrar: Se seus fluxos de trabalho usarem algum desses nós, atualize-os ou remova-os para evitar erros.

Segurança

Bloqueio padrão do acesso a variáveis de ambiente no nó Code

Para aumentar a segurança, o n8n bloqueará por padrão o acesso a variáveis de ambiente no nó Code. O valor padrão de N8N_BLOCK_ENV_ACCESS_IN_NODE agora será definido como true.

Como migrar: Se seus fluxos de trabalho precisarem acessar variáveis de ambiente no nó Code, defina N8N_BLOCK_ENV_ACCESS_IN_NODE=false na configuração do ambiente. Para dados sensíveis, recomenda-se usar credenciais ou outros métodos seguros em vez de variáveis de ambiente.

Permissões obrigatórias de arquivo de configuração

O n8n exigirá permissões rigorosas nos arquivos de configuração para melhorar a segurança. Por padrão, os arquivos de configuração deverão ter permissão 0600, ou seja, apenas o proprietário poderá ler e escrever. Esse comportamento é semelhante à forma como o SSH protege chaves privadas.

Como migrar: Para testar esse comportamento antes do v2.0, defina N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true. Se seu ambiente não suportar permissões de arquivo (por exemplo, no Windows), defina N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=false para desativar essa exigência.

Executor de tarefas habilitado por padrão

O n8n habilitará por padrão o executor de tarefas (task runner) para melhorar segurança e isolamento. Todas as execuções do nó Code serão executadas no executor de tarefas.

Como migrar: Antes de atualizar para o v2.0, defina N8N_RUNNERS_ENABLED=true para testar esse comportamento. Certifique-se de que sua infraestrutura atende aos requisitos para executar o executor de tarefas. Para segurança adicional, considere usar o modo externo (ou seja, executado em um contêiner ou processo separado).

Remoção do executor de tarefas da imagem Docker n8nio/n8n

A partir do v2.0, a imagem principal do Docker n8nio/n8n não incluirá mais o executor de tarefas para o modo externo. Você deverá usar a imagem separada n8nio/runners para executar o executor de tarefas em modo externo.

Como migrar: Se você estiver executando o executor de tarefas em modo externo com Docker, atualize sua configuração para usar a imagem n8nio/runners em vez de n8nio/n8n.

Remoção do nó Python Code baseado em Pyodide e ferramentas associadas

O n8n removerá o nó Python Code baseado em Pyodide e as ferramentas associadas, substituindo-os por uma implementação baseada no executor de tarefas que usa Python nativo, oferecendo melhor segurança e desempenho. A partir do v2.0, só será possível usar o nó Python Code com o executor de tarefas em modo externo e com Python nativo.

O nó Python Code nativo não suporta as variáveis embutidas disponíveis na versão Pyodide (como _input) nem a notação de ponto. Consulte a documentação do nó Code para mais detalhes.

As ferramentas Python nativas suportam _query, que é a string de entrada passada quando um agente de IA invoca a ferramenta.

Como migrar: Para continuar usando Python no nó Code, configure o executor de tarefas em modo externo e verifique se seus nós e ferramentas Python Code existentes são compatíveis.

Nós ExecuteCommand e LocalFileTrigger desabilitados por padrão

O n8n desabilitará por padrão os nós ExecuteCommand e LocalFileTrigger devido aos riscos de segurança que representam. Esses nós permitem que usuários executem comandos arbitrários e acessem o sistema de arquivos.

Como migrar: Se precisar usar esses nós, remova-os da lista de nós desabilitados atualizando a variável de ambiente NODES_EXCLUDE. Por exemplo, defina NODES_EXCLUDE="[]" para habilitar todos os nós ou remova apenas os nós específicos necessários.

Autenticação obrigatória por padrão nas URLs de retorno do OAuth

O n8n exigirá autenticação por padrão nos endpoints de retorno do OAuth. O valor padrão de N8N_SKIP_AUTH_ON_OAUTH_CALLBACK mudará de true (sem autenticação) para false (com autenticação).

Como migrar: Antes de atualizar para o v2.0, defina N8N_SKIP_AUTH_ON_OAUTH_CALLBACK=false e teste suas integrações OAuth para garantir que funcionem corretamente com autenticação ativada.

Valor padrão para N8N_RESTRICT_FILE_ACCESS_TO

O n8n definirá um valor padrão para N8N_RESTRICT_FILE_ACCESS_TO para controlar onde as operações com arquivos podem ocorrer. Isso afeta os nós ReadWriteFile e ReadBinaryFiles. Por padrão, esses nós só poderão acessar arquivos no diretório ~/.n8n-files.

Como migrar: Revise os fluxos de trabalho que usam nós de arquivo e certifique-se de que eles acessem apenas arquivos em diretórios permitidos. Se precisar permitir acesso a outros diretórios, defina a variável de ambiente N8N_RESTRICT_FILE_ACCESS_TO com os caminhos desejados.

Alteração do valor padrão de N8N_GIT_NODE_DISABLE_BARE_REPOS para true

Por motivos de segurança, os nós Git agora bloquearão repositórios bare por padrão. O valor padrão de N8N_GIT_NODE_DISABLE_BARE_REPOS será definido como true, o que significa que repositórios bare estarão desabilitados, a menos que você altere essa configuração.

Como migrar: Se seus fluxos de trabalho precisarem usar repositórios bare, defina N8N_GIT_NODE_DISABLE_BARE_REPOS=false na configuração do ambiente para habilitá-los.

Dados

Fim do suporte a MySQL/MariaDB

O n8n não suportará mais MySQL e MariaDB como backends de armazenamento — esse suporte já havia sido descontinuado na v1.0. Para melhor compatibilidade e suporte de longo prazo, use PostgreSQL. O nó MySQL continuará sendo suportado normalmente.

Como migrar: Antes de atualizar para o v2.0, use ferramentas de migração de banco de dados para transferir seus dados do MySQL ou MariaDB para PostgreSQL ou SQLite.

Remoção do driver legado do SQLite

Devido a problemas de confiabilidade, o n8n removerá o driver legado do SQLite. O driver com pool de conexões será o único disponível. Esse driver usa modo WAL, uma única conexão de escrita e um pool de conexões de leitura. Nossos testes de desempenho mostram que ele pode ser até 10 vezes mais rápido.

Como migrar: O driver sqlite-pooled se tornará automaticamente o padrão. Você pode habilitar imediatamente o pool de conexões definindo DB_SQLITE_POOL_SIZE com um valor maior que 0. O tamanho padrão do pool será 2.

Remoção do modo de dados binários em memória

O n8n removerá o modo default da variável N8N_DEFAULT_BINARY_DATA_MODE, que armazenava dados binários em memória durante a execução. A partir da v2, as seguintes opções estarão disponíveis para melhor desempenho e estabilidade:

• filesystem: dados binários armazenados no sistema de arquivos (opção padrão no modo regular).
• database: dados binários armazenados no banco de dados (opção padrão no modo com fila).
• s3: dados binários armazenados em armazenamento compatível com S3.

A configuração N8N_AVAILABLE_BINARY_DATA_MODES também será removida, portanto o modo será determinado exclusivamente por N8N_DEFAULT_BINARY_DATA_MODE.

Como migrar: O modo de sistema de arquivos ou banco de dados será usado automaticamente com base na configuração. Certifique-se de que sua instância do n8n tenha espaço em disco suficiente para armazenar dados binários. Consulte a documentação sobre configuração de dados binários para mais detalhes.

Configuração e ambiente

Atualização do dotenv

O n8n usa a biblioteca dotenv para carregar configurações de ambiente do arquivo .env. Essa biblioteca será atualizada da versão 8.6.0 para a mais recente, o que pode alterar a forma como o arquivo .env é analisado. As principais alterações incluem:

• Suporte a crases (backticks) (#615): se seus valores contiverem crases, envolva-os com aspas simples ou duplas.
• Suporte a valores multilinha: agora é possível usar valores em várias linhas.
• # marca o início de comentários: linhas que começam com # serão tratadas como comentários.

Como migrar: Consulte o changelog do dotenv e atualize seu arquivo .env para garantir compatibilidade com a nova versão.

Remoção da opção n8n --tunnel

A opção de linha de comando n8n --tunnel será removida na v2.0.

Como migrar: Se você atualmente usa a opção --tunnel para desenvolvimento ou testes, mude para outras soluções de túnel, como ngrok, localtunnel ou Cloudflare Tunnel. Atualize seus fluxos de trabalho e documentação para refletir essa mudança.

Remoção de QUEUE_WORKER_MAX_STALLED_COUNT

A variável de ambiente QUEUE_WORKER_MAX_STALLED_COUNT e o mecanismo de reexecução do Bull para tarefas travadas serão removidos, pois frequentemente causavam confusão e funcionavam de forma não confiável.

Como migrar: Remova essa variável de ambiente da sua configuração. Após a atualização, o n8n não reexecutará automaticamente tarefas travadas. Se precisar lidar com tarefas travadas, considere implementar sua própria lógica de reexecução ou monitoramento.

Remoção de N8N_CONFIG_FILES

A variável de ambiente N8N_CONFIG_FILES foi removida.

Como migrar: Remova essa variável da sua configuração. Migre suas configurações para variáveis de ambiente, arquivo .env ou configuração baseada em _FILE.

CLI e fluxos de trabalho

Substituição do comando CLI update:workflow

O comando CLI update:workflow será descontinuado e substituído por dois novos comandos que oferecem funcionalidade semelhante com semântica mais clara:

• publish:workflow, com parâmetros id e versionId (opcional)
• O parâmetro --all será removido para evitar publicações acidentais em ambientes de produção
• unpublish:workflow, com parâmetros id e all

Como migrar: Use o novo comando publish:workflow para publicar fluxos de trabalho individualmente por ID, opcionalmente especificando uma versão. Para cancelar a publicação, use o novo comando unpublish:workflow. Isso oferece maior clareza e controle sobre o estado de publicação dos fluxos de trabalho.

Hooks externos (External Hooks)

Descontinuação dos hooks de fluxo de trabalho do frontend

As funções de hook workflow.activeChange e workflow.activeChangeCurrent serão descontinuadas e substituídas pelo novo hook workflow.published. Esse novo hook será acionado sempre que qualquer versão de um fluxo de trabalho for publicada.

Como migrar: Atualize seu código para usar o novo hook workflow.published em vez de workflow.activeChange e workflow.activeChangeCurrent. Esse hook oferece um comportamento mais consistente e é acionado no momento exato da publicação de uma versão do fluxo.

Canais de lançamento

O n8n renomeou os canais de lançamento de latest e next para stable e beta, respectivamente.

A tag stable indica a versão estável mais recente, e a tag beta indica a versão experimental mais recente. Essas tags estão disponíveis tanto no npm quanto no Docker Hub. Atualmente, o n8n continuará aplicando as tags latest e next às versões lançadas, mas elas serão removidas em futuras versões principais.

Recomendação: Use uma versão específica do n8n, por exemplo, 2.0.0.

Relatar problemas

Se encontrar algum problema ao atualizar para o n8n 2.0, visite o fórum da comunidade para obter ajuda e suporte.