Sauvegardes et restauration

Une instance Tale récupérable demande plus qu’une archive de base de données. Conserve ses fichiers, la configuration des organisations, le dossier de déploiement et les clés de déchiffrement, avec la version qui a écrit les données. Définis d’abord la perte de données et la durée de reprise acceptables, puis vérifie que tes sauvegardes et ta procédure respectent ces objectifs.

Ce guide couvre les snapshots de volumes Docker de la CLI utilisée dans un workspace. Si tu gères Compose toi-même, prévois une sauvegarde des mêmes stockages. Les bases et buckets externes exigent des sauvegardes séparées et coordonnées.

Préparer un hôte de reprise vide

Récupère le workspace d’origine et vérifie que ta connexion Docker vise l’hôte de reprise. Garde les services arrêtés. Remplace your-project-id ci-dessous par l’ID d’origine de tale.json. Pour un snapshot de développement, utilise plutôt TALE_RESTORE_PREFIX="${TALE_RESTORE_PROJECT}-dev_". Les noms de production et de développement sont distincts ; si les deux existent, la CLI choisit la production en premier.

TALE_RESTORE_PROJECT=your-project-id
TALE_RESTORE_PREFIX="${TALE_RESTORE_PROJECT}_"
docker volume create --label "project=$TALE_RESTORE_PROJECT" "${TALE_RESTORE_PREFIX}config-data"
docker volume create --label "project=$TALE_RESTORE_PROJECT" "${TALE_RESTORE_PREFIX}backups"
docker volume inspect "${TALE_RESTORE_PREFIX}backups"

Ces commandes préparent les volumes de configuration et de sauvegarde sans démarrer de backend ni appliquer de migration. Avec ton système de sauvegarde, restaure le contenu complet de backups dans ce volume. Le point de montage affiché appartient à l’hôte Docker, qui peut être distant. Conserve la structure des répertoires et les manifestes des snapshots. tale restore doit ensuite afficher le snapshot attendu. Pendant la restauration effective, la CLI crée les autres volumes cibles manquants après avoir vérifié le snapshot.

Vérifier la portée du snapshot

tale backup capture les volumes du projet présents dans cet inventaire :

Un snapshot contient une archive et son fichier de somme SHA-256 pour chaque volume capturé. manifest.json, écrit en dernier, indique la version de la plateforme lorsqu’elle peut être déterminée. Un dossier sans manifeste est incomplet : il ne figure pas dans la liste de restauration et la rotation peut le supprimer après la création d’un snapshot complet plus récent. Les snapshots pris avant que la CLI capture le stockage de la passerelle ne contiennent pas d’archive de llm-gateway-data.

Conserve aussi le workspace qui contient tale.json, son .env et les fichiers de clés montés séparément. Garde notamment ENCRYPTION_SECRET_HEX et l’identité age nécessaire aux fichiers SOPS. Les espaces de travail des sandbox ne font pas partie de cet inventaire ; ajoute-les à ton plan si tu dois conserver leur état.

Créer et vérifier un snapshot

Exécute ces commandes dans le dossier du déploiement concerné :

tale status
tale backup
tale restore

backup affiche le résultat. Sans identifiant, restore liste seulement les snapshots disponibles, leur version enregistrée et l’éventuelle absence des fichiers ou du stockage de la passerelle. Note l’identifiant du snapshot avec ceux des sauvegardes externes.

Pendant l’archivage d’un volume, le processus suspend les conteneurs qui l’utilisent. Les imports, téléchargements, opérations de base et appels de modèle passant par la passerelle peuvent attendre pendant cette pause, dont la durée dépend de la quantité de données et du débit. Docker signale un conteneur suspendu comme unhealthy jusqu’à ce que sa sonde réussisse de nouveau. Après chaque archive, le processus attend donc que chaque conteneur sain avant la pause soit de nouveau signalé comme healthy, ce qui prend en général un intervalle de sonde. Si un conteneur ne se rétablit pas dans la limite des tentatives que permet sa sonde, le snapshot échoue. Ces archives correspondent à un état de reprise après arrêt brutal par volume, pas à une transaction atomique entre tous les stockages. Pour obtenir un point de reprise coordonné, arrête les écritures et tâches planifiées ou utilise une fenêtre de maintenance qui couvre aussi les stockages externes.

Un tale deploy qui change de version ou remplace la configuration de l’hôte prend un snapshot avant ses modifications. L’échec du snapshot interrompt ce déploiement. --skip-backup contourne cette protection ; utilise cette option uniquement si ton plan de reprise fournit déjà la sauvegarde nécessaire.

Conserver une copie hors de l’hôte

Les snapshots résident dans le volume Docker backups du projet. Une panne de l’hôte ou du disque peut détruire les données et les snapshots locaux ensemble. Copie les snapshots complets, la configuration du workspace et les clés dans ton système de sauvegarde externe protégé. Tale ne les transfère pas pour toi.

Utilise l’identifiant de projet de tale.json pour trouver le volume :

docker volume inspect <project-id>_backups

Le chemin de montage appartient à l’hôte Docker, qui peut être une VM ou une machine distante. Configure ton agent de sauvegarde à cet endroit sans supposer que le chemin existe sur ton poste. Vérifie que la copie externe contient manifest.json, toutes les archives qu’il cite et leurs fichiers de somme de contrôle.

La rotation locale garde les cinq snapshots les plus récents et ceux des 14 derniers jours. Un snapshot n’est supprimé que s’il dépasse les deux limites. Modifie BACKUP_KEEP_COUNT et BACKUP_KEEP_DAYS dans .env pour ajuster ces fenêtres ; configure séparément la rétention des copies externes.

Restaurer les données et leur version

1. Récupère le snapshot complet, le dossier de déploiement, les clés correspondantes et les sauvegardes externes. Sur un nouvel hôte, suis d’abord la préparation décrite plus haut.
2. Lance tale restore pour choisir un identifiant et lire sa version de plateforme. Si elle est inconnue, retrouve-la dans tes traces de déploiement avant de démarrer l’application.
3. Restaure avec le stack arrêté. --stop arrête les conteneurs du projet ; la CLI vérifie ensuite les sommes de contrôle et demande confirmation avant de remplacer les données. Utilise ta CLI actuelle, avant que l’étape 5 la change : une CLI antérieure à la capture du stockage de la passerelle ignore son archive.

tale restore <snapshot-id> --stop

4. Restaure les bases et buckets externes au point de reprise coordonné, sans rouvrir le trafic. Un snapshot marqué without blobs laisse le volume local de fichiers existant intact. Un snapshot marqué without gateway laisse llm-gateway-data intact et ne peut pas ramener la passerelle au stockage qu’elle avait avant sa mise à niveau ; la CLI le signale avant de demander confirmation. Si la passerelle a été mise à niveau après ce snapshot, remets ta propre copie du volume en place avant l’étape suivante, comme l’explique Mises à niveau.
5. Sélectionne la version indiquée dans le snapshot et déploie-la, y compris les services persistants :

tale update --version <snapshot-platform-version>
tale deploy --stop
tale status

La version compte : un backend plus récent peut appliquer des migrations dès son démarrage. Restaurer les données puis lancer une image actuelle choisie arbitrairement ne rétablit pas l’état enregistré. La CLI restaure les anciennes archives de configuration convex-data dans le volume actuel config-data.

Valider la reprise avant de rouvrir le trafic

Lors d’un exercice isolé, connecte-toi, ouvre une conversation connue, télécharge un ancien fichier, vérifie la configuration d’une organisation et lance une recherche contrôlée dans les connaissances. Vérifie l’accès aux secrets des fournisseurs et aux stockages externes sans déclencher de notifications ou d’automatisations de production. Note la période de données perdue, le temps de reprise et chaque étape manuelle.

Répète l’exercice après une modification importante du stockage, des clés ou du déploiement, et à la fréquence qu’imposent tes objectifs. Mises à niveau explique le choix de version ; Dépannage aide lorsqu’un service restauré ne devient pas opérationnel.