n8n

n8n em modo fila sobre Docker, com workers, task runners, PostgreSQL e Redis próprios, HTTPS e atualizações com backup.

Categoria: Servidores e infraestrutura
Estado: Disponível
Requisitos: Um VPS ativo com pelo menos 4 GB de RAM livre real (não a nominal do plano); Docker possível no VPS (os VPS novos já têm as permissões); Nenhum n8n instalado via npm nesse VPS
Ferramentas MCP (Só leem): ver_preflight_app, ver_app, ver_operacion_app
Ferramentas MCP (Escrevem ou modificam): instalar_app, controlar_app, reintentar_operacion_app
Ferramentas MCP (Destrutivas): desinstalar_app

O que permite fazer?

A ArduMaker instala o n8n como um stack Docker pronto para produção: um processo principal, workers em modo fila, um task runner por processo, seu próprio PostgreSQL e seu próprio Redis. É uma instalação por VPS.

Instalar sem perguntas: as credenciais internas são geradas sozinhas.
Publicar o editor com HTTPS; a URL de webhooks e do editor é configurada sozinha.
Reiniciar, atualizar a versão (com cópia do banco antes) e escalar workers.
Editar variáveis de ambiente pelo painel, com as críticas protegidas.
Desinstalar mantendo os dados, ou apagando-os com confirmação.

Quando convém usar?

Automações e webhooks próprios, sem os limites de execuções de um serviço hospedado.
Fluxos com nós Code que precisam de isolamento real (task runners externos).
Muito volume de execuções que convém distribuir entre workers.

Como funciona na ArduMaker?

Validar: VPS ativo, função n8n do sistema, Docker possível e RAM livre real (MemAvailable) de pelo menos 4 GB. Se já houver um n8n (Docker ou npm), ele é adotado como está, sem reinstalar nem migrar.
Preparar credenciais (ou reutilizar as do .env de uma tentativa anterior: um PostgreSQL já inicializado não aceita outra senha).
Gerar o Compose a partir do código conforme a RAM livre, baixar as imagens como passo longo e subir o stack.
Publicar o editor (porta 5678) com HTTPS e escrever no .env WEBHOOK_URL e N8N_EDITOR_BASE_URL com o endereço publicado, e N8N_PROXY_HOPS=1.
Verificar: running só com o processo principal ativo, /healthz e /healthz/readiness em 200 e todos os workers ativos.

Se um worker cair no meio, quem retoma a operação espera a mesma instalação: nunca lança um segundo stack.

O que muda realmente?

Arquivo ou recurso	Conteúdo
`/opt/n8n/docker-compose.yml`	Compose gerado pela plataforma (644 root)
`/opt/n8n/.env`	Variáveis de todos os contêineres (600 root)
`/opt/n8n/stack.json`	Versão, topologia, limites e volumes (600 root)
`/opt/n8n/backups/`	Dumps diários do banco com 7 dias de retenção (timer `n8n-db-backup`)
`n8n-stack.service`	Unidade que controla o stack com `docker compose`
Volumes	`n8n_data`, `n8n_pg_data`, `n8n_redis_data`

RAM, workers e topologia

A quantidade de workers sai da RAM livre real, não do plano. Além disso, são reservados 896 MB fixos para PostgreSQL e Redis e 512 MB de folga antes de conceder workers extras; o máximo é 8.

RAM livre	Workers	Runner do principal
Menos de 4 GB	Recusado	—
4 – 5,9 GB	2	Não
6 – 7,9 GB	3	Não
8 GB ou mais	4 ou mais (até 8)	Sim

Cada contêiner tem seu limite de memória e o n8n recebe --max-old-space-size em torno de 75% desse limite, para que o coletor trabalhe antes de o sistema matar o processo. Os logs rotacionam (10 MB, 3 arquivos) e o histórico de execuções é podado após 14 dias.

Variáveis de ambiente

Protegidas (não editáveis): N8N_ENCRYPTION_KEY, N8N_RUNNERS_AUTH_TOKEN, DB_POSTGRESDB_*, POSTGRES_*, REDIS_PASSWORD, QUEUE_BULL_REDIS_*.
Geridas pela plataforma: N8N_WORKERS (escala), WEBHOOK_URL e N8N_EDITOR_BASE_URL (domínio), EXECUTIONS_MODE, N8N_RUNNERS_MODE, N8N_PORT.
Secretas (mostradas mascaradas): as protegidas e qualquer uma terminada em PASSWORD, SECRET, TOKEN, KEY ou _PWD. Revelá-las exige admin e fica registrado.
Os valores não podem ter aspas, #, $, crase, barra invertida nem quebras de linha: um valor assim não falha, vale outra coisa.

Atualizar, escalar e fazer backup

Atualizar baixa as imagens do n8n e dos runners (mesma tag), faz um dump do banco, regenera o Compose e sobe; se a verificação falhar, volta à versão anterior.
Aumentar workers não interrompe nada; reduzi-los para primeiro os de índice mais alto com um tempo de tolerância para terminar as execuções em andamento.
A cópia semanal do VPS inclui os volumes, mas é feita a quente; o dump diário em /opt/n8n/backups/ é a cópia consistente do banco.

Esquema

Internet: HTTPS no endereço publicado
nginx do VPS: encaminha para 127.0.0.1:5678
`n8n-main`: editor e webhooks; enfileira execuções
`n8n-redis`: fila de execuções
`n8n-worker-N`: executa, cada um com seu runner
`n8n-postgres`: banco de workflows, credenciais e execuções

Stack do n8n no VPS — O PostgreSQL e o Redis do stack nunca são publicados: vivem na rede interna do projeto Compose.

Resultado esperado

O app n8n aparece em Apps como um único app (seus contêineres são componentes) com a URL HTTPS do editor quando o link estiver verificado.

docker compose -p n8n ps
docker logs n8n-main --tail 50

Erros e resolução

Erro ou sintoma	Causa e o que fazer
`recursos_insuficientes`	Menos de 4 GB de RAM livre real. Liberar memória ou subir de plano.
`requiere_reinicio_vps`	VPS antigo sem permissões de Docker: é preciso reiniciá-lo.
`n8n_npm_instalado`	Há um n8n via npm: o Docker não é instalado por cima.
`app_ya_existe` / `limite_de_tipo`	Já existe um n8n nesse VPS (ou uma instalação em andamento).
`n8n_instalandose` / `n8n_instalacion_fallida`	Ainda instalando ou terminou com erro. Pode tentar de novo: relança com as credenciais do `.env`.
`n8n_webhook_no_configurado`	Ficou publicado, mas o `.env` não pegou a URL. Pode tentar de novo, sem reinstalar.
Execuções com nó Code enfileiradas para sempre	Um runner não encontrou seu worker ou tem outra versão de imagem.
Uma variável foi alterada e nada aconteceu	`compose restart` não relê o `.env`: é preciso reiniciar recriando os contêineres.

Relação com MCP

O n8n é instalado e operado via MCP com as ferramentas de Apps (/mcp/docs, /mcp/servicios).

Leitura: ver_preflight_app (com app_type: n8n diz se a RAM e o Docker atendem), ver_app, ver_operacion_app.
Modificam: instalar_app com app_type: n8n e config opcional workers (1–8), concurrency (1–50) e version; controlar_app com restart ou update; reintentar_operacion_app.
Destrutiva: desinstalar_app (só admin). Mantém os volumes salvo delete_data=true com confirm_delete_data=true, que apaga o banco do n8n.

Qualquer outro campo em config (usuários, senhas) responde config_invalida. As variáveis de ambiente e o escalonamento são feitos pelo painel; as ações só existem para o runtime Docker (um n8n via npm responde runtime_no_soportado).