Principais mudanças no n8n v2.0 | documentação do n8n

A versão n8n v2.0 será lançada em breve. Esta documentação destaca as principais mudanças incompatíveis, além das medidas de preparação que você deve tomar para a transição. Essas atualizações aumentam a segurança, simplificam a configuração e removem funcionalidades legadas.

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

Mudanças de comportamento

Retornar os dados esperados quando um subworkflow é retomado após um estado de espera

Anteriormente, quando uma execução pai chamava um subworkflow que continha um nó que fazia a execução filha entrar em estado de espera, e a execução pai estava configurada para aguardar a conclusão da execução filha, a execução pai recebia um resultado incorreto.

Por exemplo, isso acontecia quando a execução filha continha um nó Wait com tempo limite superior a 65 segundos, uma chamada Webhook, um envio de formulário ou um nó de revisão humana, como um nó Slack.

Workflow pai:

Subworkflow:

v1: a execução pai reproduzia a entrada da execução filha como saída:

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

Isso permite usar nós de revisão humana em subworkflows e aproveitar seus resultados no workflow pai, como aprovar ou rejeitar uma ação.

Caminho de migração: revise todos os workflows que chamam subworkflows e esperam receber a entrada do subworkflow. Atualize-os para se adaptar ao novo comportamento: o workflow pai passará a receber a saída final do subworkflow, e não a entrada dele.

Remoção do nó Start

O nó Start não é mais suportado. Esse nó era a forma original de iniciar workflows, mas agora foi substituído por nós de gatilho mais específicos.

Caminho de migração: substitua o nó Start de acordo com a forma como seu workflow é usado:

• Execução manual: substitua o nó Start pelo nó Manual Trigger.
• Subworkflow: se outro workflow chama este workflow como subworkflow, substitua o nó Start pelo nó Execute Workflow Trigger e ative o workflow.
• Nó Start desabilitado: se o nó Start já estiver desabilitado, remova-o do workflow.

Salvar e publicar workflows

O novo sistema de publicação de workflows substitui o antigo alternador de ativação/desativação. O antigo alternador “Ativar/Desativar” passa a ser o novo botão “Publicar/Despublicar”. Essa mudança permite controlar melhor quando alterações em workflows são colocadas em produção, reduzindo o risco de implantação acidental de mudanças ainda em andamento. Para mais informações, consulte: salvar e publicar workflows.

Remoção de nós de serviços que não estão mais disponíveis

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

Caminho de migração: se seus workflows usam qualquer um dos nós acima, atualize-os ou remova-os para evitar erros.

Segurança

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

Para melhorar a segurança, o n8n bloqueará por padrão o acesso do nó Code às variáveis de ambiente. O valor padrão de N8N_BLOCK_ENV_ACCESS_IN_NODE agora será true.

Caminho de migração: se seus workflows precisarem acessar variáveis de ambiente em nós 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.

Aplicar permissões rígidas aos arquivos de configuração

O n8n exigirá permissões rígidas para arquivos de configuração, para aumentar a segurança. Por padrão, os arquivos de configuração deverão usar a permissão 0600, ou seja, apenas o proprietário do arquivo poderá ler e gravar. Isso funciona de forma semelhante à proteção de chaves privadas no SSH.

Caminho de migração: para testar esse comportamento antes da v2.0, defina N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true. Se o seu ambiente não suportar permissões de arquivo, como no Windows, defina N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=false para desabilitar essa exigência.

Ativação padrão do task runner

O n8n ativará por padrão o task runner para melhorar a segurança e o isolamento. A execução de todos os nós Code passará a ocorrer no task runner.

Caminho de migração: antes de atualizar para a v2.0, defina N8N_RUNNERS_ENABLED=true para testar esse comportamento. Certifique-se de que sua infraestrutura atenda aos requisitos para executar o task runner. Para uma camada extra de segurança, considere usar o modo externo.

Remoção do task runner da imagem Docker n8nio/n8n

A partir da v2.0, a imagem Docker principal n8nio/n8n não incluirá mais o task runner para o modo externo. Você deverá usar a imagem Docker separada n8nio/runners para executar o task runner no modo externo.

Caminho de migração: se você executa o task runner em modo externo com Docker, atualize sua configuração para usar a imagem n8nio/runners em vez de n8nio/n8n.

Remoção dos nós e ferramentas Python baseados em Pyodide

O n8n removerá os nós e ferramentas Python baseados em Pyodide, substituindo-os por uma implementação baseada em task runner, que usa Python nativo e oferece melhor segurança e desempenho. A partir da v2.0, você só poderá usar o nó Python Code com o task runner em modo externo e com ferramentas de Python nativo.

O nó Python Code nativo não oferece suporte às variáveis embutidas fornecidas na versão Pyodide, como _input, nem à notação de acesso por ponto. Consulte a documentação do nó Code para mais detalhes.

A ferramenta Python nativa oferece suporte a _query, que é a string de entrada passada quando um agente de IA chama a ferramenta.

Caminho de migração: para continuar usando Python no nó Code, configure o task runner em modo externo e verifique se seus nós e ferramentas Python existentes são compatíveis.

Desativação padrão dos nós ExecuteCommand e LocalFileTrigger

O n8n desativará por padrão os nós ExecuteCommand e LocalFileTrigger, pois eles apresentam riscos de segurança. Esses nós permitem executar comandos arbitrários e acessar o sistema de arquivos.

Caminho de migração: se você precisar usar esses nós, remova-os da lista de nós desabilitados na configuração do n8n, atualizando a variável de ambiente NODES_EXCLUDE. Por exemplo, defina NODES_EXCLUDE="[]" para ativar todos os nós, ou remova apenas os nós específicos de que você precisa.

Exigência padrão de autenticação para o endpoint de callback do OAuth

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

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

Definição de valor padrão para N8N_RESTRICT_FILE_ACCESS_TO

O n8n definirá um valor padrão para N8N_RESTRICT_FILE_ACCESS_TO, a fim de 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.

Caminho de migração: revise os workflows que usam nós de arquivo e garanta 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 o caminho desejado.

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

Por razões de segurança, o nó Git agora bloqueará repositórios bare por padrão. O valor padrão de N8N_GIT_NODE_DISABLE_BARE_REPOS será true, o que significa que repositórios bare ficarão desabilitados, a menos que você altere essa configuração.

Caminho de migração: se seus workflows 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 deixará de oferecer suporte a MySQL e MariaDB como backends de armazenamento. Esse suporte já havia sido marcado como obsoleto na v1.0. Para melhor compatibilidade e suporte de longo prazo, use PostgreSQL. O nó MySQL continuará sendo suportado normalmente.

Caminho de migração: antes de atualizar para a v2.0, use ferramentas de migração de banco de dados para migrar os dados de 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 passará a ser o único driver SQLite. Esse driver usa modo WAL, uma única conexão de gravação e um pool de conexões de leitura. Nossos benchmarks mostram que ele pode ser até 10 vezes mais rápido.

Caminho de migração: o driver sqlite-pooled passará automaticamente a ser o driver padrão. Você já pode habilitar 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 de N8N_DEFAULT_BINARY_DATA_MODE, que mantinha os dados binários da execução em memória durante a execução. A partir da v2, estarão disponíveis as seguintes opções, oferecendo melhor desempenho e estabilidade:

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

A configuração N8N_AVAILABLE_BINARY_DATA_MODES também será removida. Com isso, o modo passará a ser definido apenas por N8N_DEFAULT_BINARY_DATA_MODE.

Caminho de migração: o modo de sistema de arquivos ou banco de dados será usado automaticamente, dependendo da configuração. Certifique-se de que sua instância do n8n tenha espaço em disco suficiente para armazenar os dados binários. Para mais detalhes, consulte a configuração de dados binários.

Configuração e ambiente

Atualização do dotenv

O n8n usa a biblioteca dotenv para carregar a configuração do ambiente a partir do arquivo .env. Essa biblioteca será atualizada da versão 8.6.0 para a versão mais recente, o que pode mudar a forma como o arquivo .env é analisado. As principais mudanças incompatíveis incluem:

• suporte a acentos graves (backticks) (#615): se seu valor contiver backticks, envolva-o com aspas simples ou duplas.
• suporte a múltiplas linhas: agora é possível usar valores em várias linhas.
• # marca o início de um comentário: linhas que começam com # serão tratadas como comentário.

Caminho de migração: 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.

Caminho de migração: se você usa atualmente a opção --tunnel para desenvolvimento ou testes, migre para outra solução de túnel, como ngrok, localtunnel ou Cloudflare Tunnel. Atualize seus workflows e sua 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 do Bull para repetir tarefas paradas serão removidos, pois frequentemente causam confusão e não funcionam de forma confiável.

Caminho de migração: remova essa variável de ambiente da sua configuração. Após a atualização, o n8n não tentará mais repetir automaticamente tarefas paradas. Se você precisar lidar com esse tipo de tarefa, considere implementar sua própria lógica de repetição ou monitoramento.

Remoção de N8N_CONFIG_FILES

A variável de ambiente N8N_CONFIG_FILES foi removida.

Caminho de migração: remova essa variável de ambiente da sua configuração. Migre a configuração para variáveis de ambiente, arquivos .env ou configurações baseadas em _FILE.

CLI e workflows

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 nomes mais claros:

• publish:workflow, com os parâmetros id e versionId (opcional)
• o parâmetro --all será removido para evitar a publicação acidental de workflows em produção
• unpublish:workflow, com o parâmetro id e a opção all

Caminho de migração: use o novo comando publish:workflow para publicar workflows individualmente por ID, com a opção de especificar uma versão. Para despublicar, use o novo comando unpublish:workflow. Isso oferece mais clareza e controle sobre o status de publicação dos workflows.

External Hooks

Descontinuação dos hooks de workflow no frontend

Os hooks workflow.activeChange e workflow.activeChangeCurrent serão descontinuados e substituídos pelo novo hook workflow.published. O novo hook será disparado sempre que qualquer versão de um workflow for publicada.

Caminho de migração: 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 quando uma versão do workflow é publicada.

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. No momento, o n8n continuará marcando as versões lançadas também com as tags latest e next. Essas tags serão removidas em uma futura versão principal.

Recomendação: fixe a versão do n8n em um número específico, como 2.0.0.

Problemas e feedback

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