DfBackup SW: guia completo

O DfBackup SW é um sistema de cópias de segurança de nível de produção para Shopware 6.5, 6.6 e 6.7, sem qualquer dependência externa: sem mysqldump, sem shell_exec, sem SDK da Amazon. Copia a base de dados e os ficheiros em PHP puro, cifra os arquivos em AES-256 autenticado, envia-os para Local, S3, FTP ou Dropbox, e sabe até replicar cada cópia para um segundo Shopware de staging. O restauro faz-se num clique, com um snapshot de segurança automático. Este guia cobre a instalação, a execução em segundo plano, a cifra, os backends de armazenamento, a replicação, o restauro, o agendamento e a resolução de problemas.

Instalação

1. Transfira o arquivo DfBackup-SW-1.0.0.zip a partir da sua conta DataFirefly.
2. Copie a pasta descomprimida DfBackup para custom/plugins/ do seu Shopware, ou instale o ZIP em Administração → Extensões → As minhas extensões → Carregar extensão.
3. Execute a instalação e a ativação:

   bin/console plugin:refresh
   bin/console plugin:install --activate DfBackup
   bin/console cache:clear

4. Na instalação, a extensão cria as suas quatro tabelas (df_backup, df_backup_log, df_backup_filemap, df_backup_audit) e regista a sua ScheduledTask.

Onde encontrar a extensão na administração

Depois da ativação, aparece no menu um módulo de administração dedicado DfBackup. Reúne a lista das cópias, o botão Guardar agora, o progresso em tempo real, e o acesso às ações por cópia (verificar, transferir, proteger, restaurar, eliminar). A configuração (agendamento, cifra, backends, replicação, notificações) faz-se na configuração da extensão em Extensões → As minhas extensões → DfBackup → ⋯ → Configurar.

Execução em segundo plano: Messenger, ScheduledTask e web-cron

Uma cópia nunca bloqueia a interface. O clique em Guardar agora pré-aloca uma linha, envia uma mensagem assíncrona do Symfony Messenger e devolve imediatamente o identificador. O trabalho real é executado no worker, e a administração mostra o progresso em direto através de 15 marcos (arranque, cópia da base de dados, arquivamento, cifra, checksum, upload por backend, rotação).

Worker recomendado em produção

Nas lojas em produção, mantenha um consumidor Messenger supervisionado a correr permanentemente:

bin/console messenger:consume async --time-limit=300 --memory-limit=512M

Coloque-o sob systemd ou supervisor para que reinicie automaticamente. É a configuração que permite executar as cópias sem qualquer limite de tempo web.

ScheduledTask

Uma ScheduledTask nativa corre a cada 10 minutos e serve de porta de entrada ao agendamento: verifica se uma cópia agendada deve arrancar e, nesse caso, envia a mensagem. Depende do scheduler do Shopware, ele próprio acionado pelo worker ou pelo cron do Shopware.

Web-cron de recurso

Em alojamentos sem acesso CLI nem worker permanente, ative o web-cron: um URL assinado com token (regenerável a partir da configuração) que um serviço externo como o cron-job.org chama a cada 10 a 15 minutos. A porta de agendamento interna (janela de 30 minutos, desduplicação de 60 minutos) evita os disparos duplicados.

A cópia da base de dados, pensada para o Shopware

Uma cópia SQL ingénua parte-se no Shopware. O DfBackup SW trata nativamente das particularidades do esquema:

• As colunas geradas (STORED ou VIRTUAL) são excluídas dos INSERT, porque o MySQL não permite escrevê-las.
• As colunas binárias, entre as quais as chaves primárias UUID em BINARY 16, omnipresentes no Shopware, são emitidas em literais hexadecimais 0x… para uma reimportação perfeitamente fiel.
• A paginação keyset sobre chave primária inteira permite copiar as tabelas muito grandes (order, log_entry) sem saturar a memória.
• As vistas são recriadas no fim, depois de todas as tabelas.

A cópia é feita por blocos (500 linhas por lote) e o ficheiro produzido reimporta-se corretamente, instrução a instrução, com FOREIGN_KEY_CHECKS desativado durante a importação.

A cópia dos ficheiros

Os ficheiros são arquivados com ZipArchive e exclusões glob configuráveis (por predefinição var/cache, var/log, node_modules, miniaturas e outros). O modo incremental opcional assenta num sha1 de caminho, tamanho e mtime registado na base de dados: só os ficheiros alterados desde a última cópia completa são rearquivados.

Cifra AES-256

A cifra é opcional mas fortemente recomendada para os arquivos guardados fora do local. O DfBackup SW aplica um esquema AES-256-CBC com HMAC-SHA-256 segundo o padrão encrypt-then-MAC:

• A frase-passe passa por PBKDF2-SHA256 com 120 000 iterações para derivar chaves de cifra e de HMAC separadas.
• A cifra é feita em streaming por blocos de 1 MiB: um arquivo de vários GB cifra-se com uma pegada de memória constante.
• Na leitura, o HMAC é verificado antes de qualquer decifra (proteção contra ataques de padding oracle e bit-flip).
• Um SHA-256 independente garante a integridade do ficheiro em bruto (estado verified ou corrupted na base de dados).

Backends de armazenamento

Cada cópia pode ser enviada para um ou vários backends em simultâneo, para aplicar a regra 3-2-1:

• Local: em var/df-backup, com proteção contra listagem.
• Amazon S3 e compatíveis: assinatura AWS V4 nativa (sem SDK), upload multipart automático acima de 100 MB (partes de 10 MB). Compatível com MinIO, Wasabi, Cloudflare R2, OVH, Scaleway e Backblaze B2 através da substituição do endpoint e da região.
• FTP e FTPS: modo passivo, criação automática do diretório remoto.
• Dropbox v2: REST com upload_session por blocos para os arquivos acima de 150 MB.

Replicação para um Shopware de staging

É a função que distingue o DfBackup SW: empurrar cada cópia para uma segunda instalação Shopware equipada com a mesma extensão.

1. Instale o DfBackup SW na produção e no staging.
2. Gere um segredo comum (cadeia aleatória longa) e indique-o dos dois lados.
3. Do lado da produção, ative Replicação como destino e indique o URL do staging.

A cada cópia, o arquivo é carregado em blocos de 8 MB assinados com HMAC-SHA-256 para endpoints dedicados no destino (chunk, commit, delete, ping), com antirreprodução por data e hora com tolerância de 5 minutos. Se a opção de restauro automático estiver ativa no staging, o arquivo é aplicado automaticamente e o staging reflete a produção da véspera logo na manhã seguinte.

Restauro num clique

A partir da lista das cópias, o botão Restaurar abre uma janela:

1. Escolha o âmbito: tudo, apenas a base de dados ou apenas os ficheiros.
2. Para confirmar, escreva a palavra RESTORE, uma salvaguarda contra manobras acidentais.
3. Opcionalmente, ative o modo de migração de domínio e indique o novo domínio.

Antes de qualquer restauro, é criado automaticamente um snapshot protegido da base de dados: se o restauro falhar a meio, volta ao estado inicial em poucos minutos. As tabelas da extensão (df_backup*) nunca são substituídas, pelo que o seu histórico de cópias fica preservado mesmo ao restaurar uma versão de há seis meses.

Migração de domínio

Em modo de migração, a extensão reescreve os sales_channel_domain e aplica uma substituição best-effort nas colunas de texto das tabelas de tradução (CMS, produtos, categorias) e também no seo_url, para que o clone fique imediatamente navegável no seu próprio domínio.

Agendamento, rotação e modo de manutenção

• Frequências: diária (hora alvo), semanal (dia e hora), mensal (dia do mês e hora). Janela de tolerância de 30 minutos e desduplicação de 60 minutos.
• Rotação: por número de cópias a conservar e por idade em dias. As cópias marcadas como protegidas (nomeadamente os snapshots pré-restauro) nunca são rodadas.
• Modo de manutenção opcional: coloca os sales channels em manutenção durante a cópia da base de dados para uma coerência transacional perfeita, útil em lojas com volumes de encomendas muito elevados.

Notificações e auditoria

• Email através do Symfony Mailer (sucesso, falha, ou ambos à escolha).
• Webhook com deteção automática do formato: Slack, Discord, Microsoft Teams ou JSON genérico.
• Alerta no módulo se não houver cópia bem-sucedida há N dias.
• Registo de auditoria: cada ação sensível (execução, restauro, eliminação, verificação, transferência) fica registada com o utilizador de administração, o IP e a data e hora.

FAQ e resolução de problemas

A extensão funciona sem shell_exec? Sim. Nenhuma chamada a shell_exec, exec, passthru ou mysqldump. Tudo em PHP puro (DBAL, ZipArchive, cURL, funções ftp nativas).

As minhas cópias não arrancam automaticamente. Verifique que há um worker Messenger a correr (ou que o web-cron é chamado regularmente) e que a ScheduledTask DfBackup está ativa no Shopware. Sem worker nem web-cron, o agendamento não pode ser executado.

A cópia falha numa tabela grande. A paginação keyset trata normalmente das tabelas grandes; confirme que a chave primária inteira existe e aumente a memória do worker se necessário (--memory-limit).

Um arquivo sai com o estado corrupted. O SHA-256 não corresponde: o upload ou a escrita foram truncados. Relance a cópia e verifique o espaço em disco e as quotas do backend remoto.

Como verificar uma cópia sem a restaurar? O botão Verificar recalcula o SHA-256 e, nos arquivos cifrados, controla o HMAC, sem restaurar nada.

O que acontece na desinstalação? Com a opção de eliminação dos dados, as quatro tabelas df_backup* são eliminadas e a configuração apagada. Os ficheiros em var/df-backup não são eliminados automaticamente: transfira as suas cópias recentes antes de desinstalar.