towercontrol/BACKUP.md

🔒 Système de Sauvegarde TowerControl

Vue d'ensemble

TowerControl dispose d'un système de sauvegarde automatique et manuel complet pour protéger vos données SQLite.

Fonctionnalités

• ✅ Sauvegardes automatiques avec planification configurable
• ✅ Sauvegardes manuelles via UI et CLI
• ✅ Compression gzip optionnelle pour économiser l'espace
• ✅ Rétention automatique des anciennes sauvegardes
• ✅ Vérification d'intégrité de la base de données
• ✅ Restauration complète (développement uniquement)
• ✅ Interface graphique dans les paramètres avancés
• ✅ CLI pour l'administration système

Configuration

Paramètres par défaut

{
  enabled: true,              // Sauvegardes automatiques activées
  interval: 'daily',          // Fréquence: 'hourly', 'daily', 'weekly'
  maxBackups: 7,              // Nombre maximum de sauvegardes conservées
  backupPath: './backups',    // Dossier de stockage
  compression: true,          // Compression gzip activée
}

Modification via l'interface

1. Aller dans Paramètres → Avancé
2. Section 💾 Sauvegarde et données
3. Cliquer sur "Gérer les sauvegardes"
4. Modifier la configuration selon vos besoins

Modification via CLI

# Voir la configuration actuelle
npm run backup:config

# Modifier la fréquence
tsx scripts/backup-manager.ts config-set interval=daily

# Modifier le nombre max de sauvegardes
tsx scripts/backup-manager.ts config-set maxBackups=10

# Activer/désactiver la compression
tsx scripts/backup-manager.ts config-set compression=true

Utilisation

Interface graphique

Paramètres Avancés

• Visualisation du statut en temps réel
• Création manuelle de sauvegardes
• Vérification de l'intégrité
• Lien vers la gestion complète

Page de gestion complète

• Configuration détaillée du système
• Liste de toutes les sauvegardes
• Actions (supprimer, restaurer)
• Statistiques et métriques

Ligne de commande

# Créer une sauvegarde immédiate
npm run backup:create

# Lister toutes les sauvegardes
npm run backup:list

# Vérifier l'intégrité de la base
npm run backup:verify

# Voir la configuration
npm run backup:config

# Démarrer le planificateur
npm run backup:start

# Arrêter le planificateur
npm run backup:stop

# Statut du planificateur
npm run backup:status

# Commandes avancées (tsx requis)
tsx scripts/backup-manager.ts delete <filename>
tsx scripts/backup-manager.ts restore <filename> --force

Planificateur automatique

Fonctionnement

Le planificateur fonctionne en arrière-plan et crée des sauvegardes selon la fréquence configurée :

• Hourly : Toutes les heures
• Daily : Une fois par jour (recommandé)
• Weekly : Une fois par semaine

Auto-démarrage

En production, le planificateur démarre automatiquement 30 secondes après le lancement de l'application.

Gestion

# Démarrer manuellement
npm run backup:start

# Arrêter
npm run backup:stop

# Voir le statut
npm run backup:status

Fichiers de sauvegarde

Format des noms

towercontrol_2025-01-15T10-30-00-000Z.db      # Non compressé
towercontrol_2025-01-15T10-30-00-000Z.db.gz   # Compressé

Localisation

Par défaut : ./backups/ (relatif au dossier du projet)

Métadonnées

Chaque sauvegarde contient :

• Horodatage précis de création
• Taille du fichier
• Type (manuelle ou automatique)
• Statut (succès, échec, en cours)

Restauration

⚠️ ATTENTION : La restauration remplace complètement la base de données actuelle.

Sécurités

1. Sauvegarde automatique de la base actuelle avant restauration
2. Confirmation obligatoire
3. Environnement : Bloqué en production via API
4. CLI uniquement pour les restaurations en production

Procédure

Via interface (développement uniquement)

1. Aller dans la gestion des sauvegardes
2. Cliquer sur "Restaurer" à côté du fichier souhaité
3. Confirmer l'action

Via CLI

# Restaurer avec confirmation
tsx scripts/backup-manager.ts restore towercontrol_2025-01-15T10-30-00-000Z.db.gz

# Restaurer en forçant (sans confirmation)
tsx scripts/backup-manager.ts restore towercontrol_2025-01-15T10-30-00-000Z.db.gz --force

Vérification d'intégrité

Quand l'utiliser

• Après une restauration
• Avant une opération critique
• En cas de doute sur la base de données
• Dans une tâche de maintenance

Commandes

# Via npm script
npm run backup:verify

# Via CLI complet
tsx scripts/backup-manager.ts verify

Vérifications effectuées

1. Test de connexion à la base
2. PRAGMA integrity_check SQLite
3. Validation de la structure
4. Rapport détaillé

Maintenance

Nettoyage automatique

Le système supprime automatiquement les anciennes sauvegardes selon maxBackups.

Nettoyage manuel

# Supprimer une sauvegarde spécifique
tsx scripts/backup-manager.ts delete towercontrol_2025-01-15T10-30-00-000Z.db.gz

# Forcer la suppression
tsx scripts/backup-manager.ts delete towercontrol_2025-01-15T10-30-00-000Z.db.gz --force

Surveillance des logs

Les opérations de sauvegarde sont loggées dans la console de l'application.

Dépannage

Problèmes courants

Erreur "sqlite3 command not found"

# Sur macOS
brew install sqlite

# Sur Ubuntu/Debian
sudo apt-get install sqlite3

Permissions insuffisantes

# Vérifier les permissions du dossier de sauvegarde
ls -la backups/

# Modifier si nécessaire
chmod 755 backups/

Espace disque insuffisant

# Vérifier l'espace disponible
df -h

# Supprimer d'anciennes sauvegardes
tsx scripts/backup-manager.ts list
tsx scripts/backup-manager.ts delete <filename>

Logs de debug

Pour activer le debug détaillé, modifier services/database.ts :

export const prisma = globalThis.__prisma || new PrismaClient({
  log: ['query', 'info', 'warn', 'error'], // Debug activé
});

Sécurité

Bonnes pratiques

1. Stockage externe : Copier régulièrement les sauvegardes hors du serveur
2. Chiffrement : Considérer le chiffrement pour les données sensibles
3. Accès restreint : Limiter l'accès au dossier de sauvegarde
4. Tests réguliers : Vérifier la restauration périodiquement

Variables d'environnement

# Optionnel : personnaliser le chemin de la base
DATABASE_URL="file:./custom/path/dev.db"

API

Endpoints disponibles

GET    /api/backups              # Lister les sauvegardes
POST   /api/backups              # Actions (create, verify, config, scheduler)
DELETE /api/backups/[filename]   # Supprimer une sauvegarde
POST   /api/backups/[filename]   # Restaurer (dev seulement)

Exemples d'utilisation

// Créer une sauvegarde
const response = await fetch('/api/backups', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ action: 'create' })
});

// Lister les sauvegardes
const response = await fetch('/api/backups');
const data = await response.json();

Architecture

services/
├── backup.ts           # Service principal de sauvegarde
└── backup-scheduler.ts # Planificateur automatique

src/app/api/backups/
├── route.ts           # API endpoints principaux
└── [filename]/route.ts # Actions sur fichiers spécifiques

clients/
└── backup-client.ts   # Client HTTP pour l'interface

components/settings/
├── AdvancedSettingsPageClient.tsx    # Vue d'ensemble dans paramètres
└── BackupSettingsPageClient.tsx      # Gestion complète

scripts/
└── backup-manager.ts  # CLI d'administration

Roadmap

Version actuelle ✅

• Sauvegardes automatiques et manuelles
• Interface graphique complète
• CLI d'administration
• Compression et rétention

Améliorations futures 🚧

• Sauvegarde vers cloud (S3, Google Drive)
• Chiffrement des sauvegardes
• Notifications par email
• Métriques de performance
• Sauvegarde incrémentale