Ir para o conteúdo

Tutorial

Backup automático do n8n: cron, cópia criptografada e restauração testada

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.

Neste artigo
  1. Antes de começar
  2. O que entra no backup
  3. Instalar o rclone
  4. Configurar o destino criptografado
  5. O script de backup
  6. Agendar com o cron
  7. Testar a restauração
  8. Restaurar numa VPS nova
  9. Próximos passos

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.

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:

bash
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:

bash
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:

bash
openssl rand -hex 32
openssl rand -hex 32
bash
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/.

O script de backup

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

n8n-backup.sh
#!/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"
bash
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:

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:

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

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:

bash
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:

bash
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:

bash
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:

bash
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:

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

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.