# n8n

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

Fonte: https://ardumaker.com/pt/docs/n8n/

- 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?

1. 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.
2. Preparar credenciais (ou reutilizar as do `.env` de uma tentativa anterior: um PostgreSQL já inicializado não aceita outra senha).
3. Gerar o Compose a partir do código conforme a RAM livre, baixar as imagens como passo longo e subir o stack.
4. 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`.
5. 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

**Stack do n8n no VPS**

```text
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)
```

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.

```bash
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. |

> **PRECAUCION:** As migrações de esquema do n8n são irreversíveis. Se uma atualização falhar na verificação, volta-se à imagem anterior, mas o banco não é revertido: para isso existe o dump anterior.

## Relação com MCP

O n8n é instalado e operado via MCP com as ferramentas de Apps ([/mcp/docs](https://ardumaker.com/pt/mcp/docs), [/mcp/servicios](https://ardumaker.com/pt/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`).

## Funcionalidades relacionadas

- [Docker](https://ardumaker.com/pt/docs/docker/)
- [Servidores VPS](https://ardumaker.com/pt/docs/vps/)
- [PostgreSQL](https://ardumaker.com/pt/docs/postgresql/)
- [Redis](https://ardumaker.com/pt/docs/redis/)
- [Cópias de segurança](https://ardumaker.com/pt/docs/backups/)
- [Certificados SSL](https://ardumaker.com/pt/docs/ssl/)