Backup de fluxos e credenciais do Node-RED em VPS Linux

O backup de fluxos e credenciais do Node-RED em VPS Linux é a rotina de arquivamento dos arquivos de lógica (flows.json), chaves criptografadas (flows_cred.json) e configurações (settings.js) para assegurar a continuidade operacional contra perdas de dados. Para implementar uma rotina consistente, siga estes passos:

1. Identifique o diretório do usuário do Node-RED e a chave credentialSecret no arquivo de configuração.
2. Crie um script Bash para criar cópias compactadas contendo permissões restritas de leitura.
3. Valide a consistência da cópia do arquivo JSON de fluxos no diretório temporário antes de consolidar o arquivo tar.
4. Agende a execução diária do script via crontab com política de retenção local.
5. Transfira as cópias compactadas para armazenamento externo ou servidor secundário.

Pré-requisitos

• Servidor VPS rodando Ubuntu 24.04 LTS ou Debian 13.
• Node-RED instalado e em execução (gerenciado via systemd ou PM2) sob usuário não-root (ex: nodered ou o próprio usuário padrão da máquina).
• Acesso SSH com privilégios de sudo no servidor.
• Utilitários instalados no sistema: tar, gzip e jq para manipulação e validação de JSON.

Localizando os arquivos de dados e a chave criptográfica

No ecossistema de automação residencial e industrial, entender o armazenamento de dados no Node-RED é vital para evitar backups incompletos. Por padrão, a aplicação armazena seus dados em um diretório oculto no diretório base do usuário que executa o processo, normalmente localizado em ~/.node-red (verifique o caminho real com systemctl cat nodered ou pela opção -u nos argumentos de inicialização; instalações Docker costumam usar /data). Se você configurou sua infraestrutura seguindo as diretrizes de Node-RED sem desperdício: escolher VPS para Node-RED, é provável que um usuário exclusivo gerencie o runtime.

Dentro desse diretório, os seguintes componentes são críticos para a restauração dos fluxos e configurações:

• flows.json (ou flows_<hostname>.json): contém toda a lógica de nós, conexões, fios e posições visuais do painel.
• flows_cred.json (ou flows_<hostname>_cred.json): armazena credenciais (senhas de bancos de dados, tokens de APIs e chaves SSH) inseridas nos nós.
• settings.js: arquivo de configuração do runtime que define portas, permissões, middleware e a chave de descriptografia.
• .config.runtime.json: arquivo oculto gerado automaticamente pelo Node-RED; contém a chave aleatória de descriptografia quando credentialSecret não está definido explicitamente.

O arquivo flows_cred.json utiliza criptografia AES-256-CTR. Caso a propriedade credentialSecret não esteja explicitamente configurada no settings.js, o Node-RED gera automaticamente uma chave aleatória e a armazena no arquivo oculto ~/.node-red/.config.runtime.json (campo _credentialSecret). Essa chave não é derivada de propriedades do hardware e não pode ser reconstruída. Se você perder a VPS sem incluir esse arquivo no backup, o flows_cred.json se tornará irrecuperável mesmo com settings.js e flows.json em mãos. Por isso o script de backup inclui .config.runtime.json no pacote. Recomendação: configure uma credentialSecret explícita e documente-a fora do servidor para eliminar a dependência desse arquivo.

Para inspecionar o diretório ativo e verificar os arquivos presentes, execute:

ls -la ~/.node-red/

A saída incluirá os arquivos de fluxos, configurações e os arquivos ocultos gerados pelo runtime (listagem resumida aos arquivos relevantes):

total 84
drwx------  3 nodered nodered   4096 Jan 15 10:20 .
drwxr-xr-x 10 nodered nodered   4096 Jan 10 14:00 ..
-rw-------  1 nodered nodered    890 Jan 15 10:20 .config.runtime.json
-rw-r--r--  1 nodered nodered  45120 Jan 15 10:20 flows.json
-rw-------  1 nodered nodered   3410 Jan 15 10:20 flows_cred.json
-rw-r--r--  1 nodered nodered   1250 Jan 10 14:12 package.json
-rw-r--r--  1 nodered nodered  28164 Jan 10 14:15 package-lock.json
-rw-r--r--  1 nodered nodered  18432 Jan 10 14:15 settings.js

Observe que settings.js aparece com permissão 644 por padrão. Como esse arquivo contém a credentialSecret, recomenda-se restringir suas permissões imediatamente:

chmod 600 ~/.node-red/settings.js
chmod 700 ~/.node-red

Abra o arquivo settings.js e garanta que a opção credentialSecret esteja descomentada e configurada com uma cadeia de caracteres segura:

grep "credentialSecret" ~/.node-red/settings.js

Caso a linha esteja comentada com barras duplas (// credentialSecret: "a-secret-key",), é necessário seguir um procedimento controlado de migração: preserve todo o conteúdo de ~/.node-red (especialmente .config.runtime.json) antes de alterar qualquer valor, reinicie o Node-RED, realize um deploy completo nos fluxos existentes e confirme nos logs que as credenciais foram carregadas com sucesso antes de executar o primeiro backup com a nova chave. Alterar apenas a linha no arquivo e executar o backup imediatamente pode resultar em settings.js com a nova chave e flows_cred.json ainda cifrado com a chave anterior automática, tornando as credenciais irrecuperáveis.

Criando o script Bash para extração e validação dos fluxos

Para um backup de fluxos e credenciais do Node-RED em VPS Linux consistente, o processo deve garantir integridade estrutural antes do arquivamento. Como o Node-RED grava os arquivos em formato JSON puro, podemos usar o jq para conferir se a cópia capturada não sofreu corrupção causada por um deploy concorrente. A validação ocorre sobre a cópia já feita no diretório temporário, não sobre o arquivo de origem em produção — isso evita uma condição de corrida em que o arquivo mudaria entre a verificação e a cópia efetiva. Note que o arquivo tar.gz gerado não oferece criptografia em repouso — ele contém settings.js com a credentialSecret em texto claro. Para proteção completa, considere criptografar o arquivo compactado com uma ferramenta como age, GPG ou restic antes de transferi-lo para armazenamento externo.

Crie um diretório de scripts e o destino onde as cópias locais serão mantidas. Execute todos os comandos como o usuário do serviço Node-RED (ex: sudo -iu nodered) para garantir que os caminhos e permissões sejam consistentes:

mkdir -p ~/scripts ~/backups/node-red

Crie o script de backup no arquivo ~/scripts/backup_nodered.sh:

nano ~/scripts/backup_nodered.sh

Insira a seguinte estrutura de automação:

#!/usr/bin/env bash
set -euo pipefail

NODERED_DIR="${HOME}/.node-red"
BACKUP_DIR="${HOME}/backups/node-red"
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
BACKUP_FILE="${BACKUP_DIR}/nodered_backup_${TIMESTAMP}.tar.gz"

# Definir umask restritivo antes de criar arquivos temporarios
umask 077
TEMP_WORK_DIR=$(mktemp -d)

trap 'rm -rf "${TEMP_WORK_DIR}"' EXIT

# 1. Configurar caminhos dos arquivos
# Confirme qual arquivo o runtime utiliza antes de definir FLOW_FILE.
# Verifique a propriedade flowFile em settings.js ou os argumentos de inicializacao do servico.
FLOW_FILE="${NODERED_DIR}/flows.json"
CRED_FILE="${NODERED_DIR}/flows_cred.json"
SETTINGS_FILE="${NODERED_DIR}/settings.js"
PACKAGE_FILE="${NODERED_DIR}/package.json"
PACKAGE_LOCK_FILE="${NODERED_DIR}/package-lock.json"
RUNTIME_CONFIG="${NODERED_DIR}/.config.runtime.json"

if [ ! -f "${FLOW_FILE}" ]; then
    echo "Erro: Arquivo principal de fluxos nao encontrado em ${FLOW_FILE}." >&2
    exit 1
fi

if [ ! -f "${SETTINGS_FILE}" ]; then
    echo "Erro: Arquivo settings.js nao encontrado em ${NODERED_DIR}." >&2
    exit 1
fi

# 2. Copiar dados para espaco temporario (umask 077 ativo; arquivos criados como 0600)
cp "${FLOW_FILE}" "${TEMP_WORK_DIR}/flows.json"
cp "${SETTINGS_FILE}" "${TEMP_WORK_DIR}/settings.js"

if [ -f "${CRED_FILE}" ]; then
    cp "${CRED_FILE}" "${TEMP_WORK_DIR}/flows_cred.json"
fi

if [ -f "${PACKAGE_FILE}" ]; then
    cp "${PACKAGE_FILE}" "${TEMP_WORK_DIR}/package.json"
fi

# Incluir package-lock.json para garantir reproducao exata de versoes no restore
if [ -f "${PACKAGE_LOCK_FILE}" ]; then
    cp "${PACKAGE_LOCK_FILE}" "${TEMP_WORK_DIR}/package-lock.json"
fi

# Incluir chave automatica do runtime (necessaria quando credentialSecret nao esta em settings.js)
if [ -f "${RUNTIME_CONFIG}" ]; then
    cp "${RUNTIME_CONFIG}" "${TEMP_WORK_DIR}/.config.runtime.json"
fi

# 3. Validar sintaxe JSON sobre a copia no diretorio temporario
# A validacao ocorre apos a copia para evitar condicao de corrida com deploys concorrentes:
# o arquivo de origem pode mudar entre uma verificacao antecipada e a copia efetiva.
if ! jq empty "${TEMP_WORK_DIR}/flows.json" 2>/dev/null; then
    echo "Erro critico: A copia de flows.json contem JSON invalido ou corrompido (possivel deploy concorrente)." >&2
    exit 1
fi

# 4. Gerar pacote compactado com permissoes restritas
tar -czf "${BACKUP_FILE}" -C "${TEMP_WORK_DIR}" .

# 5. Rotacao: remover arquivos com mais de 14 periodos completos de 24h (~15 dias de idade)
# -mtime +14 descarta arquivos cujo mtime supera 14*24h completos; backups do dia 15 podem
# ainda ser retidos dependendo do horario exato de criacao.
find "${BACKUP_DIR}" -type f -name "nodered_backup_*.tar.gz" -mtime +14 -delete

echo "Backup concluido com sucesso em: ${BACKUP_FILE}"

Conceda permissão de execução exclusiva para o seu usuário:

chmod 700 ~/scripts/backup_nodered.sh

Execute manualmente o script para testar o funcionamento:

~/scripts/backup_nodered.sh

Saída esperada:

Backup concluido com sucesso em: /home/nodered/backups/node-red/nodered_backup_20260330_120000.tar.gz

Automação do agendamento com cron e envio remoto

Executar tarefas periódicas exige mecanismos consolidados no ecossistema Unix. Para agendar a execução recorrente do script, utilize o cron integrado do Linux. Essa abordagem é detalhada em profundidade no guia de Passo a passo para configurar backup automático com cron no VPS Linux e servidor dedicado.

Edite o arquivo crontab do usuário que executa o Node-RED. Se estiver conectado como outro usuário, instale o cron na conta correta com sudo crontab -u nodered -e:

crontab -e

Adicione a instrução para disparar o backup diariamente às 03:30 da madrugada, enviando saídas de erro para um arquivo de log. Utilize o caminho absoluto do script:

30 3 * * * /home/nodered/scripts/backup_nodered.sh >> /home/nodered/backups/backup.log 2>&1

Para proteger os dados contra falhas de hardware ou desastres lógicos na própria VPS, sincronize o diretório de destino com um servidor secundário ou storage remoto. A forma mais segura e eficiente no Linux é através do utilitário rsync via canal criptografado SSH com autenticação por chave pública sem senha.

Você pode testar a transferência remota com o comando:

rsync -avz -e "ssh -p 22" ~/backups/node-red/ [email protected]:/var/backups/nodered-nodes/

Se a transferência manual funcionar sem pedir senha (usando chave SSH autorizada), basta adicionar essa linha de comando logo ao final do script ~/scripts/backup_nodered.sh, garantindo a redundância geográfica dos dados.

Restauração e validação de desastre

Um backup só é válido se puder ser restaurado com sucesso. Para recuperar uma instalação do Node-RED a partir do pacote compactado gerado, execute um teste de restauração em ambiente controlado antes de precisar dele em produção.

Primeiro, crie um diretório de testes protegido e extraia o backup mais recente:

mkdir -m 700 /tmp/restore_test
LATEST=$(ls -t ~/backups/node-red/nodered_backup_*.tar.gz | head -n1)
tar -xzf "${LATEST}" -C /tmp/restore_test/

Verifique o conteúdo extraído:

ls -la /tmp/restore_test/

Saída esperada (arquivos criados com umask 077 ativo durante o backup apresentam permissão 600):

total 112
drwx------ 2 nodered nodered   4096 Mar 30 12:00 .
drwxrwxrwt 9 root    root      4096 Mar 30 12:01 ..
-rw------- 1 nodered nodered    890 Mar 30 12:00 .config.runtime.json
-rw------- 1 nodered nodered  45120 Mar 30 12:00 flows.json
-rw------- 1 nodered nodered   3410 Mar 30 12:00 flows_cred.json
-rw------- 1 nodered nodered   1250 Mar 30 12:00 package.json
-rw------- 1 nodered nodered  28164 Mar 30 12:00 package-lock.json
-rw------- 1 nodered nodered  18432 Mar 30 12:00 settings.js

Caso precise aplicar a restauração dos fluxos e configurações na pasta ativa do Node-RED em produção. Atenção: este procedimento restaura apenas os arquivos incluídos no backup (flows.json, flows_cred.json, settings.js, package.json, package-lock.json e .config.runtime.json). Nós customizados, bibliotecas, arquivos de contexto persistente e projetos não incluídos precisarão de atenção separada:

1. Interrompa o serviço do Node-RED temporariamente. Se estiver usando systemd:

   sudo systemctl stop nodered

   Se estiver usando PM2, substitua pelo nome ou ID do processo:

   pm2 stop nodered

2. Faça uma cópia de segurança rápida do diretório que será substituído:

   mv ~/.node-red ~/.node-red.bak

3. Crie uma nova pasta e extraia o arquivo do backup:

   mkdir -p ~/.node-red
   tar -xzf ~/backups/node-red/nodered_backup_20260330_120000.tar.gz -C ~/.node-red/

4. Instale as dependências de nós a partir do package-lock.json incluído no backup. O uso de npm ci garante versões exatas dos pacotes, evitando divergências causadas por atualizações publicadas após a data do backup:

   cd ~/.node-red && npm ci --omit=dev

5. Inicie o serviço novamente e valide os registros operacionais. Para systemd:

   sudo systemctl start nodered
   sudo journalctl -u nodered -n 50 --no-pager

   Para PM2:

   pm2 start nodered
   pm2 logs nodered --lines 50

Problemas comuns e como resolver

Sintoma: O Node-RED exibe erro "Error loading credentials: SyntaxError: Unexpected token" após restauração

Causa: O arquivo flows_cred.json foi restaurado em um servidor cuja propriedade credentialSecret no settings.js está ausente ou difere da máquina original. Com a chave errada, a descriptografia AES-CTR produz JSON inválido, gerando esse erro seguido de Error loading flows.
Solução: Abra o arquivo settings.js original (ou do backup), localize a linha exata credentialSecret: "sua_chave" e configure exatamente o mesmo valor na nova instalação. Se a instalação original não tinha credentialSecret definido, restaure também o arquivo .config.runtime.json incluído no backup para que o runtime utilize a mesma chave aleatória. Reinicie o processo em seguida.

Sintoma: Falha no comando jq com erro "parse error: Unfinished string" durante o backup

Causa: O arquivo de fluxos estava sendo reescrito pelo Node-RED exatamente no milissegundo em que o script realizou a cópia, resultando em um JSON truncado capturado no diretório temporário.
Solução: Evite agendar rotinas em períodos de deploy frequente. O script com a validação jq empty sobre a cópia protegeu o backup de arquivar um arquivo quebrado. Adicione uma instrução de retry (repetição) com intervalo de 3 segundos no script Bash.

Sintoma: Permissão negada ao salvar backups dentro de ~/backups/node-red

Causa: O diretório foi criado originalmente sob privilégios do usuário root (usando sudo), impedindo a escrita pelo usuário comum que roda a cron.
Solução: Corrija a propriedade das pastas usando caminhos absolutos (o shell expande ~ para o usuário atual, que pode não ser nodered): sudo chown -R nodered:nodered /home/nodered/backups /home/nodered/scripts e reexecute o procedimento.

Perguntas frequentes

Onde ficam armazenados os fluxos e credenciais no Node-RED?

Por padrão, o Node-RED armazena esses dados dentro do diretório do usuário em ~/.node-red. Os arquivos principais são flows.json, flows_cred.json, o arquivo de configuração settings.js e o arquivo oculto .config.runtime.json, que contém a chave de descriptografia gerada automaticamente quando credentialSecret não está definido explicitamente.

Por que as credenciais do Node-RED não abrem em outro servidor?

O arquivo de credenciais flows_cred.json é criptografado usando uma chave definida pela propriedade credentialSecret no arquivo settings.js. Se essa propriedade não estiver configurada, o Node-RED usa uma chave aleatória armazenada em ~/.node-red/.config.runtime.json. Se você restaurar as credenciais em um novo host sem a mesma secret configurada (ou sem o arquivo .config.runtime.json correspondente), o Node-RED não conseguirá descriptografar senhas e tokens.

É necessário parar o Node-RED para fazer o backup?

Geralmente não é obrigatório se você estiver copiando arquivos estáticos gravados em disco. No entanto, criar cópias consistentes enquanto nenhum deploy está ocorrendo garante que o arquivo JSON não seja gravado de forma parcial ou corrompida durante a rotina.

Como agendar a rotina de backup automaticamente no Linux?

Você pode utilizar o crontab do usuário executando o comando crontab -e e inserindo uma linha com a periodicidade desejada apontando para o seu script de backup Bash. Recomenda-se definir uma execução diária durante horários de menor carga no servidor. Certifique-se de instalar o cron no usuário que efetivamente executa o Node-RED.

Como testar se o backup dos fluxos do Node-RED foi bem-sucedido?

Extrair e verificar a sintaxe do flows.json com jq é um primeiro passo, mas não garante que o backup é utilizável. Para um teste completo, restaure os arquivos em uma instância isolada do Node-RED configurada com a mesma credentialSecret ou o mesmo .config.runtime.json do backup, inicie o runtime, verifique nos logs que as credenciais foram carregadas sem erros e confirme que os nós apresentam seus dados sem acessar serviços de produção.

Conclusão

• Mantenha a diretiva credentialSecret documentada fora do servidor; se não estiver definida, inclua o arquivo .config.runtime.json no backup para permitir a recuperação das credenciais dos nós em novos ambientes.
• Adote validações de sintaxe JSON sobre a cópia no diretório temporário — não sobre o arquivo de origem — para evitar backups corrompidos por deploys concorrentes.
• Inclua package-lock.json no backup e use npm ci na restauração para garantir a reprodução exata das versões dos pacotes instalados.
• Automatize a replicação para volumes remotos ou storages externos via SSH para evitar perda de dados por falhas no nó principal.

Leia também

• Como Instalar e Configurar o Firewall CSF no VPS Linux para Segurança Avançada
• Checklist Completo para Configurar e Testar o Firewall UFW em VPS Linux e Servidores Dedicados
• Passo a passo para configurar firewall com nftables em VPS Linux e servidor dedicado

Precisa de ajuda com a infraestrutura do seu Node-RED?

Garanta que suas automações críticas rodem em ambientes com alta disponibilidade, armazenamento NVMe redundante e proteção contínua para seus dados operacionais.

Conheça nossos planos de VPS Linux