Este guia transforma o backup manual do n8n num backup diário que roda sozinho: um script faz o dump do PostgreSQL, guarda a pasta .n8n e o .env com a chave de criptografia, manda tudo criptografado para um bucket S3 fora da VPS e apaga as cópias antigas. No fim, você restaura a cópia num projeto separado e confere que os workflows voltaram e que as credenciais ainda podem ser lidas.

Antes de começar

O ponto de partida é a instalação do guia Como instalar o n8n com Docker numa VPS: n8n com PostgreSQL em Docker Compose, na pasta /home/deploy/n8n. Se a sua pasta ou o nome dos serviços forem outros, ajuste as variáveis no começo do script.

Você também vai precisar de um bucket num armazenamento compatível com S3 que não esteja na mesma VPS: Backblaze B2, Cloudflare R2, Wasabi, Amazon S3 ou outro. Crie o bucket e uma chave de acesso que só enxergue esse bucket. Anote o endpoint, a região, o nome do bucket e o par de chaves.

O que entra no backup

Um backup que restaura o n8n inteiro tem quatro partes:

  • O banco PostgreSQL, com workflows, credenciais (criptografadas), usuários e histórico de execuções.
  • A pasta .n8n, que fica no volume n8n_data e guarda o arquivo config com a chave de criptografia.
  • O .env, com a N8N_ENCRYPTION_KEY e as senhas do banco e do runner.
  • O docker-compose.yml e o Caddyfile, para subir a mesma stack numa VPS nova.

Sem a chave, as credenciais se perdem. O banco restaura, os workflows aparecem, mas o n8n não consegue ler nenhuma credencial salva. Por isso o .env vai junto, e por isso a cópia que sai da VPS precisa ser criptografada.

Instalar o rclone

O rclone copia arquivos para quase qualquer armazenamento em nuvem e criptografa no caminho. O pacote do Ubuntu 24.04 está várias versões atrás, então instale o .deb do próprio projeto:

cd /tmp curl -fsSLO https://downloads.rclone.org/rclone-current-linux-$(dpkg --print-architecture).deb sudo apt install ./rclone-current-linux-$(dpkg --print-architecture).deb rclone version 

O backup vai rodar como root, pelo cron, então a configuração do rclone também fica no root. Por isso os comandos abaixo usam sudo rclone.

Configurar o destino criptografado

Primeiro, o acesso ao bucket. O read pede os valores sem que eles fiquem no histórico do shell:

read -rp "Endpoint S3 (https://...): " S3_ENDPOINT read -rp "Região: " S3_REGION read -rp "Access key ID: " S3_KEY read -rsp "Secret access key: " S3_SECRET; echo sudo rclone config create n8n-s3 s3 provider=Other \ endpoint="$S3_ENDPOINT" region="$S3_REGION" \ access_key_id="$S3_KEY" secret_access_key="$S3_SECRET" > /dev/null sudo rclone lsd n8n-s3: 

O rclone config create imprime a configuração que acabou de criar, com a chave secreta; o > /dev/null evita que ela apareça na tela. O último comando lista os buckets que a chave enxerga. Se o seu provedor estiver na lista do rclone (AWS, Cloudflare, Wasabi e outros), troque provider=Other pelo nome dele.

Depois, a camada de criptografia. Ela fica por cima do bucket, numa pasta n8n, e cifra o conteúdo e os nomes dos arquivos antes do envio. Gere duas senhas longas e guarde as duas num gerenciador de senhas antes de continuar:

openssl rand -hex 32 openssl rand -hex 32 
read -rp "Nome do bucket: " S3_BUCKET read -rsp "Senha da criptografia: " CRYPT_PASS; echo read -rsp "Segunda senha (salt): " CRYPT_SALT; echo sudo rclone config create n8n-offsite crypt \ remote="n8n-s3:$S3_BUCKET/n8n" \ password="$CRYPT_PASS" password2="$CRYPT_SALT" --obscure > /dev/null echo "teste" | sudo rclone rcat n8n-offsite:teste.txt sudo rclone cat n8n-offsite:teste.txt sudo rclone deletefile n8n-offsite:teste.txt 

O rclone cat precisa imprimir teste. O aviso NOTICE sobre --checksum que o rcat mostra pode ser ignorado. No painel do provedor, o arquivo aparece com nome embaralhado dentro de n8n/.

Sem as duas senhas, o backup não abre. A documentação do rclone é direta: perdeu a senha, perdeu os dados. O arquivo /root/.config/rclone/rclone.conf guarda as senhas apenas ofuscadas, não protegidas; não o copie para lugares públicos.

O script de backup

Crie o script com sudo nano /usr/local/sbin/n8n-backup.sh e cole:

#!/usr/bin/env bash # Backup diário do n8n: banco, pasta .n8n e arquivos da stack, # com cópia criptografada fora da VPS. set -euo pipefail N8N_DIR=/home/deploy/n8n # pasta do docker-compose.yml LOCAL_DIR=/var/backups/n8n # cópias locais REMOTE=n8n-offsite: # destino criptografado do rclone KEEP_LOCAL_DAYS=7 # dias de cópias na VPS KEEP_REMOTE=30d # tempo de cópias no bucket cd "$N8N_DIR" set -a; . ./.env; set +a STAMP=$(date +%F-%H%M) DEST="$LOCAL_DIR/$STAMP" install -d -m 700 "$LOCAL_DIR" "$DEST" # 1. Banco, no formato do pg_restore, e conferência do arquivo docker compose exec -T postgres pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc > "$DEST/n8n-db.dump" docker compose exec -T postgres pg_restore --list < "$DEST/n8n-db.dump" > /dev/null # 2. Pasta .n8n, de dentro do volume docker run --rm --volumes-from "$(docker compose ps -q n8n)" -v "$DEST":/backup \ ubuntu:24.04 tar czf /backup/n8n-data.tar.gz -C /home/node .n8n # 3. Arquivos da stack cp .env "$DEST/env" cp docker-compose.yml Caddyfile "$DEST/" # 4. Cópia para fora da VPS e conferência rclone copy "$DEST" "$REMOTE$STAMP" rclone cryptcheck "$DEST" "$REMOTE$STAMP" # 5. Limpeza das cópias antigas find "$LOCAL_DIR" -mindepth 1 -maxdepth 1 -type d -mtime +"$KEEP_LOCAL_DAYS" -exec rm -rf {} + rclone delete "$REMOTE" --min-age "$KEEP_REMOTE" rclone rmdirs "$REMOTE" --leave-root echo "$(date -Is) backup $STAMP concluído" 
sudo chmod 700 /usr/local/sbin/n8n-backup.sh sudo /usr/local/sbin/n8n-backup.sh sudo rclone lsl n8n-offsite: 

A primeira execução precisa terminar com backup ... concluído, e o rclone lsl precisa listar os cinco arquivos dentro de uma pasta com a data e a hora.

O que vale saber sobre o script:

  • O set -euo pipefail faz o script parar no primeiro erro. Um dump que falha não chega ao bucket, e a limpeza das cópias antigas não roda.
  • O dump sai no formato próprio do PostgreSQL (-Fc), em vez do pg_dumpall do guia de instalação. Ele restaura dentro de um banco que já existe, que é o caso de um contêiner novo do Postgres. O pg_restore --list lê o arquivo inteiro e falha se ele estiver corrompido.
  • O pg_dump lê um retrato consistente do banco com o n8n rodando. Não é preciso parar a stack.
  • O rclone cryptcheck confere cada arquivo do bucket contra o original, pelo hash, sem baixar nada.
  • A limpeza apaga cópias locais com mais de 7 dias e cópias no bucket com mais de 30. Mude KEEP_LOCAL_DAYS e KEEP_REMOTE se o seu banco for grande ou se precisar guardar por mais tempo.

Agendar com o cron

Crie o arquivo /etc/cron.d/n8n-backup com sudo nano /etc/cron.d/n8n-backup:

SHELL=/bin/bash PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin 30 3 * * * root flock -n /run/n8n-backup.lock /usr/local/sbin/n8n-backup.sh >> /var/log/n8n-backup.log 2>&1 

O backup roda todo dia às 3h30 no fuso da VPS. Confira o fuso com timedatectl: muitas VPS vêm em UTC, e 3h30 UTC são 0h30 em Brasília. Se mudar o fuso com sudo timedatectl set-timezone, reinicie o cron com sudo systemctl restart cron, porque ele só lê o fuso ao iniciar. O flock impede que duas execuções rodem ao mesmo tempo, e a saída de cada uma vai para /var/log/n8n-backup.log.

Arquivos em /etc/cron.d não podem ter ponto no nome e precisam terminar com uma quebra de linha. O cron lê o arquivo sozinho, sem reiniciar nada. No dia seguinte, confira:

tail -n 5 /var/log/n8n-backup.log sudo rclone lsd n8n-offsite: 

Backup que falha em silêncio não é backup. O cron não avisa ninguém quando o script falha. Um serviço de monitoramento de cron, como o Healthchecks.io, avisa por e-mail quando a execução do dia não chega: acrescente curl -fsS -m 10 --retry 3 https://hc-ping.com/SEU-UUID como última linha do script.

Testar a restauração

Um backup só vale se restaura. O teste abaixo baixa a cópia mais recente do bucket e a restaura na mesma VPS, num projeto separado do Compose. Ele não publica portas nem inicia o servidor do n8n. Assim, nenhum gatilho ou workflow agendado roda em dobro, e a instância de produção continua intacta.

Baixe a cópia mais recente:

mkdir -p ~/n8n-restore-test && cd ~/n8n-restore-test STAMP=$(sudo rclone lsf --dirs-only n8n-offsite: | sort | tail -n 1 | tr -d /) echo "$STAMP" [ -n "$STAMP" ] && sudo rclone copy "n8n-offsite:$STAMP" ./backup sudo chown -R "$USER": backup cp backup/env .env cp backup/docker-compose.yml backup/Caddyfile . chmod 600 .env set -a && . ./.env && set +a 

O echo precisa mostrar a data e a hora da cópia; se sair vazio, o bucket não tem backup e o comando seguinte não baixa nada.

Como a pasta se chama n8n-restore-test, o Compose cria contêineres e volumes com esse prefixo, separados dos de produção. Restaure o banco num Postgres novo:

sudo docker compose up -d --wait postgres sudo docker compose exec -T postgres pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --no-owner --exit-on-error < backup/n8n-db.dump 

Devolva a pasta .n8n ao volume do n8n:

sudo docker compose run --rm --no-deps -v "$PWD/backup":/backup --entrypoint tar n8n xzf /backup/n8n-data.tar.gz -C /home/node 

Agora confira os workflows e as credenciais com a linha de comando do n8n, que roda e sai sem iniciar o servidor:

sudo docker compose run --rm --no-deps n8n export:workflow --all --pretty | grep '"name"' | head sudo docker compose run --rm --no-deps n8n export:credentials --all --decrypted --pretty | grep -c '"data"' 

O primeiro comando lista os nomes dos workflows e dos nós. O segundo conta as credenciais que o n8n conseguiu abrir com a chave do backup; o número precisa bater com o total de credenciais da sua instância. Se ele der 0 e aparecer Credentials could not be decrypted ou Mismatching encryption keys, a chave do backup não confere com a do banco, e esse backup não restauraria as credenciais. Os dois comandos não gravam nada em disco, mas o segundo lê as credenciais abertas: não troque o grep -c por algo que as imprima na tela.

Por fim, apague o ambiente de teste. Aqui, e só aqui, o -v é o que você quer, porque apaga os volumes do teste:

cd ~/n8n-restore-test sudo docker compose down -v cd ~ && rm -rf ~/n8n-restore-test 

Confira a pasta antes do down -v. O comando apaga os volumes do projeto da pasta em que você está. Em ~/n8n, ele apagaria o banco e a chave de produção.

Repita o teste de tempos em tempos, por exemplo depois de cada atualização do n8n ou uma vez por mês.

Restaurar numa VPS nova

Se a VPS se perder, o caminho é o mesmo do teste, com a stack de produção:

  1. Instale o Docker e o rclone na VPS nova, como no guia de instalação e neste guia.
  2. Recrie os dois destinos do rclone com as mesmas chaves do bucket e as mesmas duas senhas do gerenciador de senhas.
  3. Baixe a cópia mais recente para /home/deploy/n8n/backup e coloque env (renomeado para .env), docker-compose.yml e Caddyfile em /home/deploy/n8n.
  4. Suba só o Postgres, restaure o banco e a pasta .n8n com os mesmos comandos do teste.
  5. Aponte o DNS para o IP novo e suba a stack inteira com sudo docker compose up -d.
  6. Entre no editor com a mesma conta de antes e, depois de conferir, apague a pasta backup, que tem uma cópia do .env.

Próximos passos

  • Se o provedor do bucket permitir, use uma chave que lista, lê e grava, mas não apaga, e ligue o versionamento ou o bloqueio de objetos (object lock) do bucket. A retenção passa para uma regra de ciclo de vida do bucket, e as duas linhas de limpeza com rclone saem do script. Assim, quem invadir a VPS não consegue apagar nem sobrescrever as cópias antigas. A chave não pode ser só de escrita: o rclone copy, o cryptcheck e a restauração precisam listar e ler o bucket.
  • Guarde o .env e as duas senhas do rclone num gerenciador de senhas, fora da VPS e fora do bucket.
  • Para o servidor inteiro, e não só o n8n, o passo seguinte é um backup com versões e deduplicação, como o do restic.