manuais-e-documentacao-itguys/documentacao zammad/[Nível 3] Manutenção, Backup E Restore.md

MANUAL TÉCNICO - MANUTENÇÃO, BACKUP E RESTORE - ZAMMAD

Código: ITGENG 0003/26 | Classificação: CRÍTICO Responsável: João Pedro Toledo Gonçalves | Data: {{DATA_ATUAL}}

1. HISTÓRICO DE REVISÃO

Data	Versão	Descrição	Autor
{{DATA_ATUAL}}	1.0	Criação Inicial	João Pedro Toledo Gonçalves

2. OBJETIVO

Garantir a continuidade do negócio através de rotinas de Backup, procedimentos de Atualização e Plano de Restore (Disaster Recovery).

3. PRÉ-REQUISITOS

• Acesso Root ao servidor.
• Downtime agendado (para Restore).

4. PASSO A PASSO (EXECUÇÃO)

Etapa 1: Rotina de Backup (Docker)

O Zammad via Docker não tem backup automático nativo no cron do host, você deve criar um script.

1. Crie o script /opt/zammad-docker-compose/backup.sh:

   #!/bin/bash
   cd /opt/zammad-docker-compose
   docker compose exec zammad-railsserver /usr/local/bin/zammad-backup
   # Os arquivos ficarão em /var/tmp/zammad (dentro do volume)
   # Mova para o host:
   timestamp=$(date +%Y-%m-%d)
   docker cp $(docker compose ps -q zammad-railsserver):/var/tmp/zammad_backup_${timestamp}.tar.gz /mnt/backup/
   

2. Adicione ao Crontab (crontab -e):

   0 2 * * * /opt/zammad-docker-compose/backup.sh
   

Etapa 2: Rotina de Backup (Pacote)

Instalações via pacote já possuem script nativo.

1. Edite a config:

   zammad run rails r "Setting.set('backup_dir', '/mnt/backup_externo')"
   

2. Verifique o Cron:

   /etc/cron.d/zammad
   

Etapa 3: Procedimento de Restore

⚠️ PERIGO: Isso apaga os dados atuais.

Para Docker:

1. Pare o serviço: docker compose stop.
2. Limpe o banco (se necessário) ou suba um ambiente limpo.
3. Coloque o arquivo .tar.gz do backup na pasta mapeada.
4. Execute:

   docker compose exec zammad-railsserver /usr/local/bin/zammad-restore /path/to/backup_file
   

5. Reinicie: docker compose start.

Etapa 4: Atualização de Versão (Update)

Docker:

1. Edite o .env ou docker-compose.yml mudando a Tag da versão (ex: 6.1 para 6.2).
2. Pull e Up:

   docker compose pull
   docker compose up -d
   

   • O container cuidará das migrações de banco (db:migrate).

5. SOLUÇÃO DE PROBLEMAS (TROUBLESHOOTING)

!!! warning "Pânico: Restore Falhou" O backup não sobe ou o sistema quebrou após update.

Problema 1: Versão do PostgreSQL incompatível no Restore

• Erro: pg_restore: [archiver] unsupported version (1.14) of input file.
• Causa: Você fez backup num Postgres 15 e tentou restaurar num Postgres 12.
• Solução: O ambiente de destino DEVE ter a mesma versão ou superior do Banco de Dados. Atualize o Docker do Postgres.

Problema 2: "Migrations Pending" após Update

• Sintoma: Tela de "Maintenance" eterna.
• Solução: Force a migração manual:

  docker compose exec zammad-railsserver rails db:migrate
  docker compose restart
  

Problema 3: Disco cheio durante Backup

• Causa: O directorio /var/tmp lotou.
• Solução: Configure o backup_dir para um mountpoint externo (NFS/S3) ou limpe backups antigos (> 7 dias).

6. DADOS TÉCNICOS

Componente	Local Padrão (Pacote)	Nota
Arquivos	/opt/zammad	Código fonte e assets.
Banco	/var/lib/postgresql	Dados críticos.
Storage	/opt/zammad/storage	Anexos de tickets (se local).

7. VALIDAÇÃO FINAL

• O arquivo de backup .tar.gz é gerado diariamente e tem tamanho coerente (> 10MB)?
• O script de restore finalizou com "Restore completed successfully"?