Sauvegarde et restauration

Tout ce que votre passerelle connaît (messages, contacts, conversations, campagnes, règles, paramètres, comptes, téléphones appairés) vit sur votre machine, et nulle part ailleurs : nous n'en gardons aucune copie. Perdre le disque sans sauvegarde, c'est tout perdre. Cette page explique comment vous en protéger.

La sauvegarde automatique est activée par défaut : chaque jour à 03:00 dans le fuseau de la plateforme, sept copies conservées, aussi bien sur une installation neuve que sur une installation mise à jour depuis une version antérieure. Vérifiez-la, et modifiez-la, dans Paramètres > Sauvegarde et export (voir Sauvegarde automatique). Ces copies restent sur la machine qu'elles protègent : dès le jour de l'installation, décidez aussi comment vous gardez des copies hors de la machine.

Les trois outils, et à quoi sert chacun

La clé maîtresse (secret.key) protège les secrets de vos téléphones appairés, les secrets des webhooks et votre clé de licence enregistrée. Une base restaurée sans sa clé maîtresse s'ouvre normalement, mais :

• chaque téléphone doit être appairé de nouveau ;
• chaque secret de webhook, et le secret de chaque action de règle qui appelle une URL, doit être redéfini (et mis à jour du côté destinataire) ;
• la clé de licence doit être saisie de nouveau.

C'est pourquoi l'archive de sms-gateway backup, qui contient la clé, est celle à garder en cas de sinistre. La clé est volontairement tenue hors de la base : une copie de la base qui fuiterait ne livre pas vos téléphones.

Qui peut faire quoi

Les sauvegardes et l'export de la base contiennent les comptes du dashboard : c'est pourquoi ils sont réservés au superadministrateur. Les autres rôles ne voient que la partie Export complet de l'écran.

Faire une sauvegarde

Depuis le dashboard

Paramètres > Sauvegarde et export > Sauvegarder maintenant. La passerelle écrit une copie cohérente de la base sans interrompre les envois, la relit pour s'assurer qu'elle est valide, et seulement alors la compte comme réussie. La nouvelle copie apparaît dans Sauvegardes disponibles, et la tentative dans Journal des sauvegardes.

Si la copie échoue (le plus souvent : disque plein), la tentative apparaît en Échec dans Journal des sauvegardes avec une courte raison, et le fichier endommagé est supprimé.

En ligne de commande

Sur la machine, depuis le dossier où vous voulez l'archive :

sudo sms-gateway backup

Sous Windows, il n'y a pas de commande sms-gateway. Depuis %ProgramData%\SmsGateway, dans PowerShell :

docker compose stop gateway
docker run --rm -v sms-gateway_gateway-data:/data:ro -v "${PWD}:/out" alpine:3 tar czf /out/sms-gateway-backup.tar.gz -C /data .
docker compose start gateway

Ne copiez jamais le fichier de la base à la main pendant que la passerelle tourne. Une copie prise au milieu d'une écriture donne un fichier endommagé, et vous ne le découvrez que le jour où vous en avez besoin. Utilisez l'un des outils ci-dessus.

Sauvegarde automatique

La passerelle sauvegarde sa base d'elle-même, sans interrompre les envois, et relit chaque copie avant de la compter comme réussie. Les copies apparaissent dans Sauvegardes disponibles avec l'origine Planifiée, et chaque tentative dans Journal des sauvegardes.

Réglez-la dans Paramètres > Sauvegarde et export, carte Sauvegarde planifiée (Superadmin seulement), puis Enregistrer. Le changement s'applique dans la minute, sans redémarrage.

Bon à savoir :

• Le changement d'heure est suivi : 03:00 reste 03:00 à l'heure locale des deux côtés du changement. Une heure qui n'existe pas le jour du changement (dans l'heure sautée) est exécutée une fois, juste après ; une heure qui existe deux fois est exécutée une seule fois.
• Une passerelle arrêtée à l'heure prévue fait la sauvegarde manquée une fois à son redémarrage, et non une par jour manqué. Une installation neuve, ou qui n'a jamais fait de sauvegarde automatique, fait la première dans la minute.
• Une sauvegarde manuelle ne décale pas la planification : la sauvegarde de la nuit a lieu même après un Sauvegarder maintenant à 02:59.
• Une sauvegarde à la fois : une sauvegarde automatique qui tombe pendant l'écriture d'une autre sauvegarde attend la minute suivante.
• Toutes les N heures se compte depuis la sauvegarde automatique précédente, réussie ou non : un disque plein est retenté une fois par intervalle, et non chaque minute.

La case Prochaine sauvegarde indique la prochaine échéance, dans le fuseau de la plateforme : Aucune quand la sauvegarde automatique est désactivée, Au prochain passage quand elle est due dans la minute.

Par l'API, avec une clé API de portée admin : PATCH /api/v1/settings avec un bloc backup (enabled, frequency daily ou interval, dailyAt HH:MM, intervalHours, retention). Un champ omis reste inchangé.

curl -X PATCH https://sms.exemple.com/api/v1/settings \
  -H "X-API-KEY: sk_..." -H "Content-Type: application/json" \
  -d '{"backup": {"frequency": "daily", "dailyAt": "02:30", "retention": 14}}'

L'archive en ligne de commande n'est pas planifiée par la passerelle. Lancez sudo sms-gateway backup quand vous voulez l'archive complète avec la clé maîtresse : après l'installation, avant une mise à jour ou un déménagement, et régulièrement si vous la gardez hors de la machine.

Garder des copies hors de la machine

Une sauvegarde qui reste sur le disque qu'elle protège ne survit pas à la perte de ce disque, et une sauvegarde qui reste dans le même bâtiment ne survit pas à un incendie ou à un vol.

• Télécharger une sauvegarde du dashboard (automatique ou manuelle) : dans Sauvegardes disponibles, le bouton de téléchargement à côté de chaque fichier. Par l'API : GET /api/v1/backups/{name}/download.
• Copier les archives de sms-gateway backup vers un autre serveur ou le stockage de votre choix (scp, rsync, le stockage objet de votre hébergeur).

Trois règles :

1. Chiffrez les copies. Les sauvegardes ne sont pas chiffrées : elles contiennent chaque message, chaque contact et chaque numéro en clair, et l'archive en ligne de commande contient en plus la clé maîtresse.
2. Gardez la clé maîtresse, ou l'archive complète qui la contient, même si vous comptez sur les sauvegardes du dashboard.
3. Supprimez les anciennes copies dont vous n'avez plus besoin, des deux côtés.

Combien de sauvegardes du dashboard sont conservées

La valeur Copies conservées de la carte Sauvegarde planifiée (7 par défaut, de 1 à 365) s'applique aux Sauvegardes disponibles, copies automatiques et manuelles confondues. Après chaque sauvegarde réussie, les copies les plus anciennes au-delà de ce nombre sont supprimées. Jamais avant, et jamais après un échec : une sauvegarde ratée ne vous coûte jamais une ancienne copie valable. Baisser la valeur supprime le surplus à la sauvegarde réussie suivante, pas immédiatement.

Espace disque : chaque copie pèse à peu près la taille de la base. Sept copies d'une base de 200 Mo occupent environ 1,4 Go dans le dossier de données.

Un fichier que vous ajoutez vous-même compte aussi. Tout fichier .db déposé dans le dossier des sauvegardes est listé comme restaurable et compte dans les copies conservées. Gardez votre original ailleurs : ne comptez pas sur ce dossier comme seule copie.

Restaurer une sauvegarde du dashboard

Une restauration remplace toute la base par la copie choisie. Tout ce qui a été écrit depuis cette copie (messages, contacts, réglages, comptes) disparaît de la base en service.

1. Paramètres > Sauvegarde et export > Sauvegardes disponibles, le bouton de restauration sur la ligne choisie.
2. Lisez la confirmation, cochez Je comprends que les données écrites depuis cette sauvegarde seront perdues, puis Préparer la restauration. La passerelle vérifie le fichier et le prépare ; rien n'est encore remplacé.
3. Un bandeau Restauration en attente apparaît, avec Annuler la restauration si ce n'est pas la bonne copie. Préparer une autre copie remplace celle en attente.
4. Redémarrez la passerelle pour l'appliquer : sudo sms-gateway restart (sous Windows, docker compose restart gateway depuis le dossier d'installation).
5. Reconnectez-vous, et vérifiez vos données.

Pourquoi un redémarrage : la base ne peut pas être échangée pendant que la passerelle l'utilise. L'échange a lieu au démarrage suivant, avant toute autre chose, et seulement si le fichier préparé est exactement celui qui a été vérifié.

La passerelle refuse une copie dans deux cas, chacun avec un message précis :

Une copie faite par une version plus ancienne est acceptée : elle est mise à niveau automatiquement au redémarrage.

Une restauration ratée n'empêche jamais la passerelle de démarrer : elle démarre sur la base qu'elle avait, et les journaux (sms-gateway logs) disent pourquoi.

La base précédente est conservée

La base qui était en service n'est pas supprimée : elle est mise de côté dans le dossier de données sous le nom gateway.db.pre-restore-<horodatage>. C'est votre chemin de retour si l'état restauré ne vous convient pas, et elle n'est jamais supprimée automatiquement : supprimez-la vous-même une fois satisfait, surtout sur une grosse base, sinon elle finira par remplir le disque.

Pour y revenir, passerelle arrêtée :

sudo sms-gateway stop
# Trouver le nom exact du fichier mis de côté
docker run --rm -v sms-gateway_gateway-data:/data alpine:3 ls -la /data
# Remettre la base précédente, en gardant la base restaurée de côté
docker run --rm -v sms-gateway_gateway-data:/data alpine:3 sh -c '
  mv /data/gateway.db /data/gateway.db.restore-rejected &&
  rm -f /data/gateway.db-wal /data/gateway.db-shm &&
  mv /data/gateway.db.pre-restore-1756800000 /data/gateway.db'
sudo sms-gateway start

Remplacez 1756800000 par la valeur affichée par ls. Les fichiers -wal et -shm appartiennent à la base mise de côté : ils doivent être supprimés, sinon ils endommageraient celle que vous remettez.

Restaurer une copie faite sur une autre machine

Une sauvegarde téléchargée auparavant, ou prise sur une autre installation, se restaure de la même façon une fois placée dans le dossier des sauvegardes de cette passerelle :

# Cliquez d'abord une fois sur "Sauvegarder maintenant", pour que le dossier des sauvegardes existe
docker run --rm -v sms-gateway_gateway-data:/data -v "$PWD:/in" alpine:3 sh -c '
  cp /in/gateway-20260901T020000Z-01930f2c.db /data/backups/ &&
  chown 65532:65532 /data/backups/gateway-20260901T020000Z-01930f2c.db'

Le fichier apparaît dans Sauvegardes disponibles avec l'origine Importée. Son nom doit se terminer par .db, commencer par une lettre ou un chiffre, et ne contenir que des lettres, des chiffres, des points, des tirets et des tirets bas. Suivez ensuite Restaurer une sauvegarde du dashboard.

Attention : cette copie ne porte pas la clé maîtresse de sa machine d'origine. Si cette passerelle n'a pas le même secret.key, les téléphones doivent être appairés de nouveau et la clé de licence saisie de nouveau.

Restaurer une archive complète (sms-gateway backup)

Cela ramène toute l'installation telle qu'elle était, clé maîtresse comprise : les téléphones se reconnectent sans appairage, et la licence n'a besoin de rien. Tout le contenu actuel du dossier de données est remplacé.

sudo sms-gateway stop
docker run --rm -v sms-gateway_gateway-data:/data -v "$PWD:/in" alpine:3 sh -c '
  rm -rf /data/* &&
  tar xzf /in/sms-gateway-backup-20260901-023000.tar.gz -C /data'
sudo sms-gateway start

La passerelle doit être au moins de la version qui a produit l'archive : mettez-la à jour d'abord si nécessaire. Sur une nouvelle machine, installez d'abord la passerelle, puis lancez ces commandes (voir Changer de serveur).

Exporter vos données

Paramètres > Sauvegarde et export > Export complet. Les exports ne sont pas des sauvegardes : ils vous permettent d'emporter vos données ailleurs, dans des formats ouverts que n'importe quel outil lit.

Les colonnes, dans l'ordre :

• Messages : id, conversationId, direction, phone, body, encoding, segments, status, errorCode, deviceId, simSlot, attempts, createdAt, sentAt, deliveredAt, failedAt
• Contacts : id, phone, firstName, lastName, company, email, notes, tags, blacklisted, createdAt, updatedAt
• Conversations : id, phone, contactId, state, unreadCount, pinned, archived, assignedTo, createdAt, lastMessageAt

Bon à savoir :

• Les lignes vont de la plus ancienne à la plus récente. Un export vide a quand même sa ligne d'en-tête (CSV) ou [] (JSON). Une date absente est un champ vide, jamais une fausse date.
• Ces fichiers contiennent les textes des messages et les numéros complets : rangez-les en conséquence.
• Les exports restent disponibles même si votre licence est retirée : vos données restent les vôtres.
• L'export de la base complète a besoin d'un espace temporaire sur la machine, de la taille de la base environ. S'il échoue sur une très grosse base, faites une sauvegarde et téléchargez-la à la place.

Être averti quand les sauvegardes échouent

Une passerelle qui a cessé de sauvegarder ressemble exactement à une passerelle qui fonctionne. Deux moyens de s'en rendre compte :

• Journal des sauvegardes, dans Paramètres > Sauvegarde et export, liste chaque tentative, échecs compris, avec une courte raison (par exemple snapshot could not be written : le plus souvent un disque plein). Un échec est aussi inscrit, comme erreur, dans le Journal d'activité.
• Notifications : l'alerte Échec de sauvegarde (Paramètres > Notifications) est activée par défaut et envoie un message sur chaque canal que vous avez configuré (SMS, e-mail, navigateur) dès qu'une sauvegarde automatique ou manuelle échoue. Voir Paramètres, notifications.
• Webhooks : abonnez un webhook à l'événement backup.failed (et backup.completed si vous voulez un signal positif) pour être alerté par vos propres outils. Voir Webhooks.

Vérifier qu'une sauvegarde vaut quelque chose

Une sauvegarde que personne n'a jamais restaurée est un espoir, pas une sauvegarde. La passerelle relit déjà chaque copie qu'elle fait, ce qui prouve que le fichier est une base valide. Cela ne prouve pas que vous savez la remettre en service.

En une minute, sur une copie téléchargée, avec l'outil sqlite3 :

sqlite3 gateway-20260901T020000Z-01930f2c.db 'PRAGMA quick_check;'
# doit répondre : ok
sqlite3 gateway-20260901T020000Z-01930f2c.db 'SELECT count(*) FROM messages; SELECT count(*) FROM contacts;'
# des nombres plausibles

Le vrai test : restaurez une archive complète sur une machine de secours (un petit VPS, une machine virtuelle), en suivant Restaurer une archive complète, connectez-vous avec votre compte habituel et vérifiez que vos conversations sont là. Faites-le sur une machine que les téléphones ne connaissent pas : les téléphones appairés ne se connectent qu'à l'adresse de votre vraie passerelle, donc la copie de test ne les dérange pas. Supprimez ensuite la machine de test : elle contient toutes vos données.

Faites ce test après chaque mise à jour importante, après tout changement de votre routine de sauvegarde, et au moins une fois avant d'en avoir besoin.

Référence de l'API

Toutes ces opérations exigent une clé API de portée admin (en-tête X-API-KEY) ou une session de superadministrateur. Détails dans la référence de l'API.

Une sauvegarde est refusée tant que la licence est retirée (c'est une écriture) ; les téléchargements et les exports continuent de fonctionner.

Limites actuelles

• Ni chiffrement ni envoi automatique des sauvegardes : les copier ailleurs et les chiffrer vous revient.
• Pas d'envoi d'un fichier de sauvegarde depuis le dashboard : une copie venue d'ailleurs se place dans le dossier des sauvegardes avec la commande indiquée plus haut.
• Les fichiers gateway.db.pre-restore-... ne sont jamais supprimés automatiquement.