Como instalar o n8n? Tutorial completo de implantação local e primeira execução para iniciantes

Instalar o n8n em si não é difícil; o difícil é a questão de "os dados vão se perder?" depois da instalação. Já vi muita gente rodar um comando, usar por uma semana, deletar o container e recriá-lo, e todos os workflows sumiram — porque o volume de dados não foi montado corretamente.

Este artigo explica claramente três métodos comuns de instalação, ordenados por "menos armadilhas": Docker, Docker Compose, npm. Após a instalação você terá: um n8n acessível no navegador, dados armazenados localmente que não se perdem, e fuso horário correto.

Para quem é indicado, o que é necessário antes de começar

Indicado para pessoas que nunca implantaram um serviço, mas é necessário saber abrir o terminal e digitar comandos. Windows, macOS e Linux são compatíveis; este artigo foca em Docker, porque facilita mais a atualização e migração posteriores.

Se você só quer testar na máquina de outra pessoa sem uso a longo prazo, pule direto para a terceira seção, o método npm, que roda com duas linhas de comando, mas não coloque dados importantes nele.

Primeiro decida onde instalar

Método	Para quem é indicado	Vantagens	Custo
Docker (container único)	Computador pessoal, uso leve	Isolamento limpo, deletou acabou, atualização apenas troca a image	Precisa aprender um pouco de Docker
Docker Compose	Execução de longa duração, precisa conectar ao banco de dados	Configuração gravada em arquivo, pode ter controle de versão, reinício com inicialização automática	Um yaml a mais para manter
Instalação global via npm	Já possui ambiente Node, quer economizar recursos	Sem container, conexão direta ao host, perda de desempenho mínima	Depende da versão do Node do sistema, atualizações facilmente causam confusão

Minha sugestão: para uso pessoal, escolha Docker Compose, não use um único docker run. O motivo é bem prático — depois de rodar com um único comando, em dois meses você com certeza não vai lembrar quais parâmetros configurou na época. O Compose grava os parâmetros no arquivo, se houver problema dá para ver, alterar e fazer backup.

Verificar o ambiente

Primeiro confirme se o Docker está presente. Execute no terminal:

docker -v

Se conseguir ver o número da versão (no formato Docker version 29.5.3, build d1c06ef) significa que está instalado. No Windows e macOS, o Docker Desktop já vem incluído; no Linux, use o Docker Engine.

Depois confirme que a porta 5678 não está ocupada. Linux:

ss -lntp | grep 5678

No macOS ou Linux também pode usar lsof -i :5678. Se houver saída, significa que está ocupada, troque para outra porta, por exemplo -p 5679:5678. Windows usa netstat -ano | findstr 5678。

Método 1: executar com um único docker run

Primeiro crie o volume de dados, depois inicie o container. Não combine estes dois passos num só; crie o volume separadamente, assim, ao excluir e recriar o container depois, os dados não serão perdidos:

docker volume create n8n_data

docker run -d --name n8n 
  -p 5678:5678 
  -e GENERIC_TIMEZONE="Asia/Shanghai" 
  -e TZ="Asia/Shanghai" 
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true 
  -e N8N_DEFAULT_LOCALE=zh-CN 
  -v n8n_data:/home/node/.n8n 
  --restart unless-stopped 
  n8nio/n8n

Explique um a um o que cada parâmetro faz; estes são os pontos onde realmente se cometem erros:

• -d: executar em segundo plano. A documentação oficial fornece -it --rm(executar em primeiro plano, excluir ao sair), isso é para testes. Para uso a longo prazo, deve-se alterar para -d --restart unless-stopped, assim o container reinicia automaticamente após o servidor reiniciar.
• -p 5678:5678: mapeia a porta 5678 dentro do container para o host. O lado esquerdo é a porta do host; basta alterar o lado esquerdo.
• GENERIC_TIMEZONE 和 TZ: ambos devem ser definidos.TZ controla o horário dos comandos de sistema dentro do container,GENERIC_TIMEZONE controla por qual fuso horário os nós de agendamento (como Schedule Trigger) são calculados. Definir apenas um fará com que ocorra "defini 9 da manhã, mas na prática executou às 5 da tarde".
• -v n8n_data:/home/node/.n8n：A linha mais crítica. O banco de dados SQLite, a chave de criptografia e os logs do n8n estão todos neste diretório. Sem montar o volume, tudo se perde ao excluir o container.
• N8N_DEFAULT_LOCALE=zh-CN: interface em chinês por padrão. Note que o chinês do n8n só traduz a interface; os parâmetros dos nós permanecem em inglês.

Após iniciar, abra no navegador http://localhost:5678. Na primeira vez, será solicitado que você crie uma conta de administrador, com senha de pelo menos 8 caracteres. Essa conta é armazenada localmente; se esquecida, só é possível redefinir. Anote bem.

Método 2: Docker Compose (recomendado)

Crie um diretório e coloque dentro docker-compose.yml：

services:
  n8n:
    image: n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - GENERIC_TIMEZONE=Asia/Shanghai
      - TZ=Asia/Shanghai
      - N8N_DEFAULT_LOCALE=zh-CN
      - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
      - N8N_SECURE_COOKIE=false
    volumes:
      - ./n8n_data:/home/node/.n8n

Em seguida, execute neste diretório:

docker compose up -d

Algumas observações:

N8N_SECURE_COOKIE=false Esta linha só é necessária quando «acessado localmente via http». Se você já configurou domínio e HTTPS, remova-a — manter HTTPS ativado e escrever false reduz a segurança. Muitas pessoas ficam com a página de login girando indefinidamente após a instalação local justamente por causa dessa configuração de cookie.

O diretório de dados usa ./n8n_data, ou seja, a pasta no mesmo nível do yml. A vantagem é que o backup basta empacotar esse diretório, sem precisar adivinhar onde o volume do Docker está escondido.

Verificar logs e saber se subiu:

docker compose logs -f --tail=50

Ao ver a linha com o endereço do editor e o número da versão, significa que subiu. Pressionar Ctrl+C apenas sai dos logs; o container continua rodando.

Método 3: instalação global via npm

A instância que eu uso é desse modo, sem container, rodando diretamente no host. O pré-requisito é ter ambiente Node.js; o n8n 2.x exige Node 20 ou superior (esta máquina está com Node 24.21.0).

npm install -g n8n
n8n start

Mas rodar assim diretamente tem um problema: os dados ficam por padrão no diretório do usuário atual em .n8n, e ao fechar o terminal o processo para. Em produção, geralmente se usa variáveis de ambiente para especificar o diretório de dados e systemd ou pm2 para gerenciar. As variáveis-chave realmente usadas nesta instância são assim (substitua pelos seus próprios valores):

N8N_USER_FOLDER=/data/n8n
N8N_HOST=127.0.0.1
N8N_PORT=5678
N8N_PROTOCOL=http
N8N_EDITOR_BASE_URL=https://你的域名/
N8N_DEFAULT_LOCALE=zh-CN

N8N_HOST=127.0.0.1 Em conjunto com N8N_EDITOR_BASE_URL, é a prática comum de colocar o n8n atrás do Nginx, sem expor a porta diretamente; será detalhado no próximo artigo sobre implantação em servidor. Se você só usa na máquina local, defina HOST como localhost .

Como fica depois de instalar

Após o login, você entra na página "Visão geral". À esquerda fica a navegação de funcionalidades, no centro as abas de workflows, execuções e credenciais, e no canto superior direito o botão "Criar workflow".

Clique em "Criar workflow" e você terá uma tela em branco, com apenas uma linha "Adicionar primeiro passo" no centro:

Primeiro workflow: três nós

Clique no sinal de mais no centro da tela e a biblioteca de nós aparecerá à direita. No campo de busca, digite manual, selecione "Manual Trigger (gatilho manual)"; ele é o ponto de partida deste fluxo.

Em seguida, no pequeno sinal de mais à direita do nó de gatilho manual, adicione um "Edit Fields (editar campos)" e preencha dois campos quaisquer, por exemplo city preencha "Fuzhou",temp preencha 27. Mais à direita, adicione um nó "Code (código)" e cole na caixa de código:

return items.map(item => ({
  json: {
    message: `${item.json.city} 现在 ${item.json.temp} 度`
  }
}));

Por fim, clique no botão "Executar" na parte inferior da tela. Os três nós acendem em sequência e ficam com marca de verificação verde, indicando que toda a cadeia está funcionando. Nesse momento, abra qualquer nó e a área de saída à direita mostrará os dados reais.

O objetivo deste passo não é aprender a escrever código, mas confirmar que o conjunto instalado consegue correr.

Como saber se a instalação foi realmente bem-sucedida

Conseguir abrir a interface não conta como sucesso. Percorre os quatro pontos abaixo; só passa se todos forem cumpridos:

1. Consegue abrir o editor: aceder pelo browser sem erros e ver a lista de workflows.
2. Consegue guardar: cria um workflow, adiciona um node qualquer, espera que guarde automaticamente, atualiza a página e o conteúdo continua lá.
3. Reiniciar não perde dados：docker compose restart, atualiza novamente e o workflow anterior continua presente. Este ponto é a única forma de verificar se o volume de dados foi montado corretamente.
4. Consegue executar: corre um workflow manual, o node fica verde e, ao abrir, vês os dados de saída.

O terceiro ponto é o mais facilmente ignorado e também o mais crítico. Se o workflow desaparecer após reiniciar, não duvides do n8n, vai verificar -v se o caminho seguinte está mal escrito ou se foi usado um volume anónimo.

Erros comuns

Port ocupado.O erro contém port is already allocated. Troque a porta do host, por exemplo -p 5679:5678, e depois acesse com 5679.

Abre, mas o login fica girando.Ao acessar localmente via http, se N8N_SECURE_COOKIE for o padrão true, o navegador recusará gravar o cookie. Em testes locais, defina como false; após configurar HTTPS, remova esta linha.

O horário da tarefa agendada está errado.Apenas TZ foi definido, sem definir GENERIC_TIMEZONE, e o nó de agendamento é calculado em UTC. Defina ambos como Asia/Shanghai。

Após reiniciar, o container não subiu.Esqueceu de adicionar --restart unless-stopped ou no yml o restart. Após reiniciar o servidor, é preciso manualmente docker start n8n。

O pull da image está muito lento ou falha.Puxar do Docker Hub na rede doméstica costuma dar timeout; configure um mirror accelerator antes de puxar, ou use docker pull n8nio/n8n e espere com paciência, a image tem centenas de MB.

O chinês não entrou em vigor.N8N_DEFAULT_LOCALE Afeta apenas o idioma padrão de novas sessões; contas existentes precisam alterar manualmente nas configurações. E, como dito antes, apenas o shell da interface está em chinês.

Não exponha à rede pública com pressa

Assim que instalou, quis acessar pelo celular e abriu a port 5678 para a rede pública — este é o erro mais comum. No n8n ficam as API Key dos seus diversos sistemas; expor isso cru na rede pública é como pendurar as chaves na porta.

A abordagem correta é: primeiro usar na máquina local ou na rede interna; após confirmar o uso a longo prazo, seguir o processo do próximo artigo para vincular domínio, habilitar HTTPS, usar reverse proxy com Nginx e permitir escuta apenas em 127.0.0.1.

Além disso, após o primeiro login, altere a senha do administrador para uma senha forte; não use admin123 deste tipo.

Sobre versões

O n8n lança uma minor version por semana. Ao escrever este artigo, a versão estável indicada na documentação oficial era 2.44.5, a beta era 2.45.2; minha instância roda a 2.43.7, e as capturas de tela da interface foram todas tiradas dela.

Recomendações:Não use latest em ambiente de produção. Fixe a image em um número de versão específico, por exemplo n8nio/n8n:2.44.5, para atualizar, altere o número e faça o pull novamente. A consequência de usar latest é que um dia, ao reiniciar, a versão muda silenciosamente e o comportamento do workflow também muda, tornando a investigação muito trabalhosa.

Como ver a sua versão: após iniciar sessão, entre em configurações no canto inferior esquerdo, ou execute docker exec n8n n8n --version。

Próximo passo

Instalado, primeiro gaste dez minutos a reconhecer a interface:Visão geral da interface do n8n: o que o canvas, os nodes e o histórico de execuções dizem. Depois de reconhecer, use esta instalação de hoje para escrever o exemplo de três nodes acima uma vez; as mãos memorizam melhor que os olhos.

Se preferir primeiro entender «porque vale a pena aprender», volte ao artigo anterior:O que é o n8n, introdução para principiantes e cenários de aplicação。

Referências

• Install with Docker (oficial)
• Install with npm (oficial)
• Configuração de variáveis de ambiente (oficial)
• Repositório oficial de exemplos n8n-hosting

Última atualização: 22 de outubro de 2026. Os comandos Docker foram verificados segundo a documentação oficial (a versão estável indicada na altura era 2.44.5), as capturas de ecrã foram tiradas da minha própria máquina com 2.43.7.