Workflow, Node, Connection, Execution: quatro palavras que explicam claramente o mundo do n8n

No canvas há cinco blocos e quatro linhas. Exporte isso como JSON e restam apenas duas chaves:nodes 和 connections. O registro de execução fica em outro lugar, disposto um a um, cada um com um número.

Os três lugares falam da mesma coisa, com quatro palavras: workflow, node, connection, execution. Se essas quatro palavras estiverem claras, ler qualquer tutorial de node depois será mais fácil; se não estiverem, você ficará batendo de um lado para o outro entre "eu claramente cliquei em executar" e "por que não rodou".

Não precisa saber programar. Basta conseguir abrir o n8n instalado e ter executado um workflow uma vez (se não instalou, vejaeste artigo, e se a interface ainda não é familiar, consulte primeiroo tour da interface). O meu aqui é 2.43.7; se a sua versão menor for diferente, a posição dos botões pode variar um pouco.

• Quatro palavras, quatro coisas
• Workflow: um container, mais dois estados
• Node: o nome é a chave primária
• Connection: array de duas camadas, a primeira camada é o índice de saída
• Execution: uma execução, com um snapshot
• Juntando tudo: a ordem de uma depuração
• Como saber se você realmente entendeu
• Cinco erros que realmente acontecem
• Riscos de exportação, compartilhamento e rastreabilidade

Quatro palavras, quatro coisas diferentes

Primeiro uma tabela comparativa; as seções seguintes apenas a desdobram.

A linha mais fácil de confundir é a última. Workflow é o projeto, execution é a obra. Mude o projeto dez vezes, a obra já feita não muda junto.

Workflow: um container, mais dois estados

A definição oficial é curta: um grupo de nós conectados que automatizam algo; o trigger disparou, você clicou manualmente, outro fluxo o chamou, ele começa a rodar, executando nó por nó, podendo ramificar, mesclar e fazer loop.

A definição não tem nada a criticar. O que realmente exige atenção é o estado que surgiu a partir da versão 2.x:Rascunho e publicado são duas coisas diferentes。

Você altera coisas na tela, o n8n salva sozinho, grava no banco em um a cinco segundos, sem botão de salvar. Mas isso só salva no rascunho. Para colocar as alterações no ar, é preciso clicar em «Publicar» no canto superior direito, fixando uma versão específica em produção. Depois disso, timers, Webhook e eventos de aplicação executam essa versão fixada, não a versão que está na sua tela agora.

Essa regra resolveu um problema antigo (alteração pela metade ser atingida por uma tarefa agendada), mas também criou uma nova armadilha: alterar parâmetros e esquecer de publicar, e a produção continua rodando a lógica de ontem, enquanto na tela tudo parece normal. Na primeira vez que encontrei isso, fiquei dez minutos comparando as duas versões de parâmetros até lembrar que o botão lá em cima ainda estava ativo.

Isso também explica por que o primeiro workflow de algumas pessoas simplesmente não «ativa». Só tem um trigger manual, que por natureza não tem forma de produção, e o botão de publicar fica sempre cinza. Para agendar, adicione um Schedule Trigger; para receber requisições externas, adicione um Webhook. Com esse tipo de trigger, o botão é que acende.

Pela interface fica mais claro: nesta minha instância, um workflow recém-criado active 是 false，activeVersionId 是 null, só tem um versionId que muda a cada alteração. Se nunca foi publicado, não existe versão em produção.

Node: o nome é a chave primária

Um nó é uma unidade de execução. Alguns iniciam o fluxo (triggers), outros buscam dados, enviam dados, calculam dados, e outros só fazem controle de fluxo, uma linha IF também pode ser um nó.

No JSON, um nó tem apenas sete coisas:

{
  "parameters": { "jsCode": "return [{ json: { amount: 620 } }];" },
  "id": "n2",
  "name": "造两条订单",
  "type": "n8n-nodes-base.code",
  "typeVersion": 2,
  "position": [-400, 0]
}

• type: qual tipo de nó é.n8n-nodes-base.code é o nó Code,-base. a parte depois é o nome do nó em minúsculas.
• typeVersion: A versão da definição do nó. Versões diferentes do mesmo nó alteram a estrutura de parâmetros. Nesta minha, IF é 2.2, Edit Fields é 3.5, Code é 2, Manual Trigger é 1. Esse número não é você que preenche; ele é gravado na criação conforme a definição daquele momento.
• parameters: Tudo o que você preenche no painel da direita está aqui. Ao trocar o tipo de nó, todo este bloco é substituído.
• position: Coordenadas no canvas, apenas para exibição, sem relação com a ordem de execução.
• id: Identificador curto usado internamente pelo workflow; copiar um nó gera um novo.

name Parece o mais discreto, mas na prática é o ponto mais propenso a problemas entre estas quatro palavras:é a chave primária. As conexões registram o nome, não o id.

No canvas, alterei «小单归档» para «小单归档（改）», e as quatro conexões permaneceram intactas; após salvar, o connections na interface também mudou para o novo nome — isso é a interface compensando por você. De outra forma, alterando diretamente o nameno JSON sem mexer nas conexões, o servidor rejeita na hora, e o erro reporta duas mensagens de uma vez:

Workflow structure is invalid. nodes[4].name (duplicate_node_name):
Duplicate node name "大单跟进"; connections.判断大单.main[1][0].node
(unknown_connection_target): Connection target "小单归档" does not
reference an existing node

A primeira diz nome duplicado, a segunda diz que há uma linha apontando para um nó inexistente. As duas mensagens são, na verdade, duas faces da mesma coisa: você renomeou um nó para o nome de outro, e o nome deslocado ainda é apontado pelas conexões.

Por isso, sugiro nomear os nós como se fossem nomes de variáveis: não use coisas como "Set" ou "Code 1", e também não fique mudando o nome a cada dois dias. Pode incluir espaços, parênteses e caracteres chineses no nome; o n8n aceita, mas quando você mesmo escreve nas expressões $('小单归档（改）') é fácil esquecer um parêntese.

Connection: array de dois níveis, o primeiro nível é o índice da saída

Conectar significa ligar a saída de um nó à entrada de outro nó. No JSON fica assim:

"connections": {
  "造两条订单": { "main": [[{ "node": "判断大单", "type": "main", "index": 0 }]] },
  "判断大单": { "main": [
    [{ "node": "大单跟进", "type": "main", "index": 0 }],
    [{ "node": "小单归档", "type": "main", "index": 0 }]
  ]}
}

Lendo por partes: a chave mais externa énome do nó de origem；main é o tipo de conexão (fluxo de dados normal; no caso de AI é ai_tool、ai_languageModel estes); oíndice do array interno corresponde a qual saída; mais dentro está a lista de destinos, e uma saída pode se conectar a vários downstream.

O nó de decisão de pedido grande tem dois grupos, por isso ele é [[...],[...]]. O primeiro grupo corresponde ao ponto marcado true no nó, o segundo grupo corresponde a false. À primeira vista parece que há arrays aninhados demais, mas na verdade é só "qual saída → conecta a quem".

Há um mal-entendido conceitual aqui que vale a pena esclarecer. Muitas pessoas pensam que IF é "escolha binária": se a condição for verdadeira vai por um lado, se não for vai pelo outro, seguindo apenas um caminho.

Não é. IF éroteamento por item. Fiz ele receber dois pedidos, 620 e 180, e o resultado foi 1 item no branch true e 1 item no branch false, as duas linhas acenderam. Se você colocar 100 registros, ele distribui cada um para os dois lados conforme o próprio valor, podendo dar 30 à esquerda e 70 à direita, ou 0 de um lado.

Portanto, quando alguém diz "o nó depois do IF não executou", primeiro confirme se aquele lado simplesmente não tinha dados. Isso não é falha.

Execution: uma execução, com um snapshot

Execução é quando este workflow rodou uma vez. Um clique manual conta como uma, o timer disparar conta como uma, um Webhook receber uma requisição conta como uma. Ela não pertence ao JSON do workflow, fica em outra tabela, ligada por workflowId mount de volta.

Campos que me interessam em um registro de execução:

A última linha é fácil de ignorar mas muito útil: a execução reconhece a versão. Você alterou os parâmetros mas não publicou, a produção continua executando a versão antiga, e o registro de execução aponta para o id da versão antiga.

E um detalhe que só notei desta vez: cada execução armazena um snapshot do workflow daquele momento (workflowData). Depois de renomear "小单归档" para "小单归档（改）", voltei ao registro das 09:17:42 e o canvas ainda mostrava "小单归档" — porque a renderização usa o snapshot embutido naquela execução, não o seu canvas atual.

Isso explica duas coisas. O lado bom: alterar parâmetros, deletar nós, os registros antigos não são adulterados, ao investigar problemas você vê exatamente o cenário daquele momento. O lado ruim: se você comparar registros antigos com o canvas atual, os nomes dos nós podem não bater, não pense que foi você que lembrou errado.

Por quanto tempo armazenar é uma questão prática. A limpeza automática vem ativada por padrão: execuções com mais de 336 horas (14 dias) são apagadas, e quando o total ultrapassa 10000 registros os mais antigos também são removidos. Sucesso e falha são armazenados, execuções manuais também. Das duas regras, vale a que bater primeiro: um workflow que roda a cada 5 minutos, 288 vezes por dia, em 14 dias acumula 4032 registros, bate primeiro pela idade; um que roda 2000 vezes por dia, no quinto dia já atinge dez mil, bate primeiro pela contagem. Portanto, "aquela execução não está na lista" não significa necessariamente que não rodou, pode já ter sido limpa.

Juntando tudo: a ordem de uma sessão de troubleshooting

As quatro palavras separadas todos entendemos, mas ao usar é preciso uma ordem. Meu hábito é ir de fora para dentro:

1. Primeiro veja o status do registro de execução. Sem registro, significa que não foi acionado de forma alguma — o problema está no trigger ou no status de publicação, não nos nós.
2. Se o status for falha, clique e veja qual nó está vermelho. Nos detalhes do nó, veja a entrada; na maioria das vezes a entrada já está errada.
3. Se o status for sucesso mas o resultado estiver errado, veja o número de itens nas conexões. Se alguma linha tem 0, os nós seguintes naturalmente não farão nada.
4. Se os números estiverem certos mas os campos errados, só então é hora de suspeitar dos parâmetros do nó, ou de que o upstream alterou o tipo.

A vantagem dessa ordem é que cada passo elimina um grande conjunto de possibilidades. Ao contrário, ficar olhando o código no nó Code logo de cara costuma resultar em meia hora perdida só para descobrir que o upstream enviou apenas 0 itens.

Como saber se você realmente entendeu

Não precisa decorar definições; fazer três coisas já basta, e cada uma tem resultado observável.

Um, conte.Quantos blocos há no canvas, o JSON exportado nodes deve ter o mesmo número no array. O meu tem 5, o comprimento do array é 5. O número de conexões também é igual: 4 linhas correspondem a connections 4 chaves de origem (o nó de julgamento de grandes pedidos tem duas condições em uma chave, mas ainda são 4 linhas).

Dois, altere uma linha.Delete o nó do caminho false e exporte novamente;判断大单 o segundo grupo do array deve se tornar um array vazio, e não desaparecer por completo. Esse passo faz você lembrar que "a saída é determinada pela posição, não pela existência ou não de downstream".

III. Execute duas vezes.Após executar, vá em «Todas as execuções», deve haver uma a mais, com ID 1 maior que a anterior, e o horário é o momento em que você clicou. Altere mais um parâmetro, sem publicar, execute uma vez, e depois vá ao ambiente online (agendado ou Webhook) verificar se ele ainda usa o parâmetro antigo — se este for o seu negócio real, recomenda-se fazer este passo em um workflow de teste.

Cinco erros que realmente acontecem

1. Dois nós com o mesmo nome.Após copiar um nó, esqueceu de renomear, ou editou o JSON manualmente. Ao salvar, o servidor rejeita, retornando Duplicate node name, e ao mesmo tempo lança um unknown_connection_target. Ao ver dois, não entre em pânico, basta renomear de volta para um nome único.

2. Alterou o nome do nó, mas a expressão não foi alterada junto.As conexões são preenchidas automaticamente pela interface, as expressões não. O nó anterior chamava-se A, e você a jusante usa $('A').item.json.amount para obter dados; após renomear para B, esta expressão não encontrará nada, e o erro apontará para a linha da expressão, não para a renomeação.

3. O botão de publicar está cinza.O workflow só tem gatilho manual, não há nada que possa ir para produção. Ao passar o mouse, aparece «Este workflow não tem nós de gatilho que precisam ser publicados». Adicione um Schedule Trigger ou Webhook para poder publicar.

4. Após alterar parâmetros, a tarefa agendada ainda executa a lógica antiga.O que foi alterado é o rascunho, não clicou em publicar. Este tipo de problema é o mais difícil de diagnosticar, porque o canvas, os parâmetros e a execução de teste estão todos normais, apenas o comportamento online está errado.

5. Registros de execução não encontrados.Três possibilidades: foi limpo por exceder o período de retenção, o workflow foi excluído e os registros desapareceram junto, ou a opção «guardar também em caso de sucesso» foi desativada (EXECUTIONS_DATA_SAVE_ON_SUCCESS=none). As duas primeiras são as mais comuns.

Riscos de exportação, compartilhamento e rastreamento

O JSON do workflow pode ser exportado por inteiro e enviado a outras pessoas. Há três pontos onde coisas vazam.

Texto em claro nos parâmetros.As credenciais em si não estão no JSON (fica apenas uma referência de nome), mas parameters pode conter de tudo: token na URL, key escrita à mão no cabeçalho HTTP, path do Webhook.grep uma passada key、token、Bearer e reenviar, questão de dois minutos.

Os registros de execução contêm dados brutos.O que o nó executou fica armazenado como texto original no registro: número do pedido, nome do cliente, endereço, tudo lá. Auto-hospedado permite controlar o período de retenção; reduzir EXECUTIONS_DATA_MAX_AGE é a forma mais simples; em instâncias compartilhadas por várias pessoas, é melhor configurar desde o início.

Colar diretamente um JSON enviado por outra pessoa.Colar significa executar no seu instance o código que ele escreveu; o JS no nó Code não pergunta se você quer executar. Jogue workflows de origem desconhecida em uma instância de teste vazia e só depois analise.

Resumo

Workflow é o desenho, node são os blocos no desenho, conexão são as setas entre os blocos, execução é a vez em que se constrói seguindo o desenho. As quatro palavras correspondem a quatro coisas, as posições são diferentes, e as consequências de alterar também são diferentes: alterar parâmetros de node afeta cada execução futura, alterar o registro de execução não muda nada (ele é um registro por natureza), alterar o nome faz as conexões acompanharem, mas as expressões não necessariamente.

Se realmente tivesse que escolher uma coisa que deveria ser lembrada primeiro, seria «execução com snapshot». Isso explica ao mesmo tempo por que registros antigos não mentem para você, por que novas alterações não necessariamente entram em vigor, e por que, passado o período de limpeza, não se consegue mais consultar nada.

Para julgar se você entendeu ou não, há um método simples: abra aleatoriamente um workflow feito por outra pessoa, sem olhar o canvas, olhando apenas o JSON exportado, você consegue dizer quantos nodes ele terá ao rodar, quantos caminhos, e qual é execução vazia. Se conseguir dizer, então essas quatro palavras estão dominadas.

Continuando adiante

Para quem ainda não fez o primeiro workflow rodar com sucesso, veja primeiro《Primeiro workflow: gatilho manual → editar campos → código》, aquele artigo explica como conectar três nodes e fazer rodar. Problemas de inicialização com erro, porta ocupada e outros problemas que impedem de entrar pela porta, estão emaqui. O índice do curso completo está emesta página, e os conteúdos relacionados a nodes estão todos emesta categoriaabaixo.

Entre os triggers, o tipo agendado é o mais propenso a problemas, e foi escrito em um artigo separado:Workflow agendado não dispara: 5 causas verificadas uma a uma。

Referências

• Key concept glossary: definições oficiais de workflow, node, execution e publish, é com isto que este artigo se alinha
• Understand workflows: o que é um workflow, e os quatro volumes sobre criação de workflow, componentes e execução
• Connect nodes together: criação e remoção de conexões, a saída de um node ligada à entrada de outro
• Save and publish workflows: intervalo de tempo do salvamento automático, a publicação fixa a versão em produção, a execução de produção usa a versão publicada
• Understand executions: diferença entre execução manual e de produção, quais execuções contam para a quota
• If: tipos de dados e formas de comparação da condição, duas saídas
• Executions variáveis de ambiente: retenção de 336 horas, limite de 10000 registros, sucesso e falha ambos armazenados, estes valores padrão

Última atualização: 4 de novembro de 2026, usando n8n 2.43.7.