# 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…

- Página: <https://www.datafirefly.com/pt/documentation/dfbackup-sw/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfbackup-sw/index.md), [en](https://www.datafirefly.com/en/documentation/dfbackup-sw/index.md), [es](https://www.datafirefly.com/es/documentation/dfbackup-sw/index.md), [de](https://www.datafirefly.com/de/documentation/dfbackup-sw/index.md), [it](https://www.datafirefly.com/it/documentation/dfbackup-sw/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfbackup-sw/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfbackup-sw/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

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.

Compatível com Shopware 6.5.x, 6.6.x e 6.7.x numa única base de código, PHP 8.1 a 8.3. Extensões PHP necessárias: `zip` e `openssl` (sempre), `curl` (S3, Dropbox, replicação) e `ftp` (backend FTP/FTPS). Sem dependências Composer adicionais.

## 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.

Se a página de administração for fechada durante uma cópia, o processo continua no worker. Volte a abrir o módulo DfBackup para reencontrar o progresso e o resultado.

## 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).

Se a frase-passe se perder, os arquivos cifrados tornam-se definitivamente irrecuperáveis, e essa é a própria garantia da cifra autenticada. Guarde a frase-passe num gestor de palavras-passe externo (Bitwarden, 1Password) antes de ativar a cifra.

## 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.

O Cloudflare R2 oferece 10 GB gratuitos com custo zero de saída: um excelente backend remoto para cópias cifradas. Indique o endpoint R2 e a região `auto` na configuração S3.

## 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.

Combinada com a migração de domínio (ver abaixo), a replicação dá um clone imediatamente navegável no seu próprio domínio, sem rsync nem scripts de cron de sistema.

## 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.

Um restauro substitui a base de dados e os ficheiros existentes. Verifique o âmbito selecionado e evite restaurar uma versão antiga numa produção que continuou a registar encomendas, salvo numa migração controlada.

### 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.