Sauvegarde et restauration

Une fois que votre instance est en cours d'utilisation, créez une sauvegarde avant de mettre à niveau ou de déplacer des serveurs. Première demande.

SubLane peut exporter une instance en cours d'exécution, vérifier une sauvegarde et la restaurer dans un nouveau répertoire. Paramètres du système → Sauvegarde et restauration La récupération n'écrase jamais l'instance en cours d'exécution; passer à des données restaurées est un redémarrage explicite de l'opérateur.

Ce qui est inclus

Les nouvelles sauvegardes sont des fichiers age binaires chiffrés par mot de passe. Après déchiffrement, l’archive gzip/tar contient :

• sublane.db: une cohérence SQLite instantané, y compris les données WAL engagées.
• credentials.key: la clé de chiffrement correspondante pour les identifiants d'abonnement et les clés de passerelle récupérables.
• manifest.json: version format, temps de création, SubLane construire la version, la version schéma, les tailles de fichiers et les montants de contrôle SHA-256.

Utilisateurs, hachages de mot de passe, API les clés, comptes d'abonnement, pools, permissions, catalogues, paramètres, dossiers de demande, résumés d'utilisation, cooldowns et dossiers d'affinité sont inclus. Les sessions de navigateur sont capturées dans la sauvegarde mais effacées dans un répertoire restauré. OAuth Les tentatives ne sont pas incluses.

Les nouvelles exportations exigent un mot de passe de 12 à 128 caractères. SubLane ne le conserve pas. Gardez-le séparément : sa perte empêche la récupération de la sauvegarde chiffrée. Les anciennes archives .tar.gz non chiffrées restent vérifiables et restaurables sans mot de passe, mais contiennent des clés lisibles et doivent rester privées.

Ligne de commande

Exécutez les commandes d'un répertoire avec suffisamment d'espace libre pour l'instantané de la base de données et l'archive compressée:

mkdir -p backups
./bin/sublane backup --password-stdin --output ./backups/team.sublane-backup.tar.gz.age < /secure/backup-password
./bin/sublane backup verify --password-stdin --input ./backups/team.sublane-backup.tar.gz.age < /secure/backup-password
./bin/sublane restore --password-stdin --input ./backups/team.sublane-backup.tar.gz.age --data-dir ./data-restored < /secure/backup-password

backup lit SUBLANE_DATA_DIR ou ./data, avec une option --data-dir Surveiller. restore toujours nécessite un nouveau répertoire explicite; même un répertoire vide existant est rejeté. Le répertoire parent doit exister. Les fichiers d'archives existants et les répertoires de restauration ne sont jamais remplacés. JSON résultat avec l'opération, chemin et métadonnées de sauvegarde. sublane --help liste les commandes.

Les commandes de maintenance ne démarrent pas HTTP serveur, SDK les agents d'exécution, OAuth, ou des vérifications de libération automatique, et ne dépendent pas de l'adresse du serveur / configuration publique-URL. Ils ont une limite de quinze minutes et répondent à SIGINT/SIGTERM. Les instantanés de base de données sont limités à 4 GiB et l'archive IO utilise des tampons limités.

Après une restauration réussie:

1. Arrêter le courant SubLane de service.
2. Gardez son répertoire de données original intact.
3. Démarrer SubLane avec le répertoire restauré:

SUBLANE_DATA_DIR=./data-restored ./bin/sublane

4. Connectez-vous à nouveau et vérifiez les utilisateurs attendus, les pools, les clés et les états de compte avant de reprendre le trafic d'équipe.

Le répertoire original est disponible pour le retour en arrière en arrêtant SubLane et de commutation SUBLANE_DATA_DIR retour. Ne pas exécuter deux instances de passerelle contre le même répertoire de données. La restauration retourne tous les états stockés à l'instantané : les révocations de clés ultérieures, les modifications de mot de passe et les nouveaux enregistrements ne sont pas inclus. Un fournisseur d'abonnement peut avoir invalider les anciens jetons de rafraîchissement depuis la sauvegarde; réautoriser les comptes affectés si nécessaire.

Interface Web

Seuls les administrateurs activés peuvent utiliser la page ou ses paramètres. Les mutations nécessitent l'origine exacte du navigateur, et l'exportation revérifie la session de l'administrateur après la préparation du fichier.

• Télécharger la sauvegarde crée et télécharge une archive complète pendant que l'instance reste disponible.
• Vérifier la sauvegarde vérifie le fichier sélectionné et affiche son temps de création, SubLane version et taille de la base de données.
• Préparer la restauration charge et valide à nouveau le fichier, puis crée <current data directory>/restore-ready. La page affiche le chemin complet et les instructions de redémarrage. L'instance actuelle continue à fonctionner avec ses données d'origine jusqu'à ce que l'opérateur commute les répertoires.

Un système existant restore-ready path bloque une autre préparation. Inspectez-la sur le serveur ou utilisez le CLI avec une nouvelle cible différente. Aucun répertoire ne peut être écrasé via le web API. Si les données de récupération ont été préparées mais que l'écriture de l'audit en direct a échoué, le répertoire est conservé et la page signale l'échec de l'audit; inspectez-le avant de réessayer.

Les téléchargements et téléchargements sur le Web sont limités à 256 millions de fichiers compressés; les sauvegardes plus importantes nécessitent la CLI. Une opération d'exportation/vérification/restauration fonctionne à la fois par serveur. Le téléchargement, le traitement et le téléchargement ont limité les délais. Les fichiers temporaires sont supprimés après l'achèvement, la défaillance ou l'annulation normale. .sublane-backup-* directory; supprimer les répertoires restants de mise en place seulement quand aucune opération de sauvegarde n'est en cours.

Les exportations et les restaurations préparées sont vérifiées sans enregistrer le contenu des archives, les noms de fichiers, les chemins du système de fichiers ou les identifiants. Cache-Control: no-store. Les flux de page téléchargent à partir du fichier sélectionné ; le navigateur reçoit l'archive téléchargée comme un blob temporaire et libère son URL après avoir commencé le téléchargement.

Exemple de sauvegarde et de restauration des commandes du navigateur :

Docker Compose

Pour exporter et vérifier à l'intérieur du conteneur en circulation:

docker compose -f docker.compose.yaml exec sublane sh -c 'mkdir -p /data/backups'
docker compose -f docker.compose.yaml exec -T sublane sublane backup --password-stdin --output /data/backups/team.sublane-backup.tar.gz.age < /secure/backup-password
docker compose -f docker.compose.yaml exec -T sublane sublane backup verify --password-stdin --input /data/backups/team.sublane-backup.tar.gz.age < /secure/backup-password
docker compose -f docker.compose.yaml cp sublane:/data/backups/team.sublane-backup.tar.gz.age ./team.sublane-backup.tar.gz.age

Pour la récupération, copiez une sauvegarde dans un emplacement privé enregistrable visible à l'intérieur du conteneur, puis préparez un répertoire séparé:

docker compose -f docker.compose.yaml exec -T sublane sublane restore --password-stdin --input /data/backups/team.sublane-backup.tar.gz.age --data-dir /data/restore-ready < /secure/backup-password

L'action de restauration web produit la même cible. Compose outrance, par exemple docker.compose.restore.yaml:

services:
  sublane:
    environment:
      SUBLANE_DATA_DIR: /data/restore-ready

Ensuite, arrêtez le processus original et commencez par le rebord :

docker compose -f docker.compose.yaml stop sublane
docker compose -f docker.compose.yaml -f docker.compose.restore.yaml up -d

Pour un contenant déjà arrêté, utiliser docker compose -f docker.compose.yaml run --rm --no-deps sublane ... au lieu de exec pour exécuter des commandes de maintenance contre son volume de données nommé. Gardez la préséance sélectionnée dans les commandes de déploiement suivantes. Ne supprimez pas le volume nommé pendant cette procédure.

Validation et comportement d'échec

Vérification vérifie les entrées et tailles exactes des archives, les digests SHA-256, l'intégrité gzip, la version de schéma consolidé supportée, SQLite l'intégrité et les clés étrangères, les documents d'identité limités, le déchiffrement des identifiants de compte et crypté API keys. Liaisons de validation aussi cap individuel SQLite les valeurs et les instructions SQL à 1 MiB. Symlinks, chemin traversant, fichiers dupliqués/inattendus, fichiers manquants, archives tronquées et schémas futurs inconnus sont rejetés. Les schémas de développement plus anciens ne sont pas acceptés par cette compilation de prérelease.

Restaurer ferme et synchronise sa base de données/clé préparée avant de publier l'ensemble du nouveau répertoire avec une opération atomique sans remplacement. Linux et macOS nécessitent une prise en charge du système de fichiers pour cette opération; une opération non prise en charge échoue sans revenir à une écrasement. Aucune table de base de données supplémentaire ou migration de schéma n'est introduite par la prise en charge de sauvegarde. SQLite snapshot creation utilise le SQLite Sauvegarde en ligne API via le pilote Go épinglé, plutôt que de copier un fichier de base de données en direct.

Utilisation application/gzip ou application/octet-stream Les archives non valides retournent 400, une destination existante renvoie 409, des téléchargements surdimensionnés retournent 413 et un emplacement occupé retourne 429 avec Retry-After. Stockage et autres défaillances opérationnelles retournent les erreurs désinfectées 503.

credentials.key · Mot de passe de sauvegarde

Arrêtez l’instance existante, copiez sa clé d’origine vers un emplacement privé hors du dossier de données et attribuez-la à l’utilisateur du service. Supprimez l’ancienne copie uniquement après avoir vérifié le démarrage et une sauvegarde chiffrée.

SUBLANE_CREDENTIALS_KEY_FILE: Fichier de clé privé facultatif hors du dossier de données ; sans valeur, conserve l’emplacement existant.

Si vous stockez la clé séparément, déplacez le fichier credentials.key restauré vers un nouvel emplacement privé hors du répertoire de données et mettez à jour SUBLANE_CREDENTIALS_KEY_FILE avant de redémarrer. N’écrasez pas la clé de l’instance d’origine.

Utilisez 12 à 128 caractères. Conservez le mot de passe séparément ; il ne peut pas être réinitialisé en cas de perte. Obligatoire pour une sauvegarde chiffrée. Laissez vide pour les anciennes archives non chiffrées.

--key-file FILE · --password-stdin · scrypt: 18 (~256 MiB)

Lisez le mot de passe avec --password-stdin depuis un fichier privé d’une seule ligne, en mode 0600 ; ne le placez ni dans les arguments ni dans l’environnement.

L’interface envoie multipart/form-data, avec password avant file. Les anciens téléversements bruts restent acceptés sans mot de passe.

Migration automatique de la clé avec Compose

Le dépôt de l’application fournit scripts/separate-key.sh pour les déploiements Compose existants sous SubLane v0.12.0+. Enregistrez et examinez le script avant de l’exécuter sur l’hôte Docker. Exportez et vérifiez d’abord une sauvegarde de récupération chiffrée par mot de passe.

sudo bash scripts/separate-key.sh --dir /srv/sublane --key-dir /srv/sublane-secrets

--dir désigne le déploiement existant contenant docker.compose.yaml et son éventuel .env. --key-dir doit être un nouveau chemin absolu sur un stockage hôte persistant, hors du montage réel des données et du répertoire de récupération, avec un parent déjà existant. Les chemins ASCII usuels, espaces compris, sont acceptés. Il faut un hôte Linux local avec Docker rootful sans remappage userns ni SELinux, Compose, Bash, jq et GNU coreutils. Le service sain doit s’appeler sublane et son répertoire de données doit être la racine d’un montage bind ou d’un volume nommé accessible en écriture. Compose doit utiliser deux espaces pour indenter les services, une table de correspondance en bloc pour environment et une liste en bloc pour volumes. Les structures non prises en charge sont refusées avant l’arrêt du service.

Le script contrôle le projet, l’image, le montage, les permissions privées, la taille de 32 octets et l’empreinte de la clé d’origine. Il préserve le texte Compose et l’interpolation des variables, puis compare la configuration normalisée. Le nouveau répertoire hôte reste la propriété de root, en mode 0700 ; seul le fichier de clé 0600, appartenant à l’UID/GID du service, est monté en lecture seule. Les droits du service ne sont pas élevés.

Avant le basculement, après celui-ci et après la suppression de l’ancienne clé, le script crée et vérifie une sauvegarde chiffrée temporaire avec un nouveau mot de passe aléatoire. L’espace temporaire reste hors du répertoire de données et est supprimé ensuite. Prévoyez assez d’espace disque et de mémoire pour la KDF de sauvegarde. Ces contrôles ne conservent aucune sauvegarde de récupération. L’ancienne copie n’est supprimée qu’après validation de la configuration, de l’état de santé, de l’empreinte et des identifiants ; une nouvelle recréation et vérification confirme l’indépendance vis-à-vis de l’ancien fichier.

Après le début du basculement, les erreurs et signaux interceptables déclenchent une tentative de retour arrière. Il reste possible de revenir en arrière après une migration réussie :

sudo bash scripts/separate-key.sh --dir /srv/sublane --rollback

Les données privées de récupération restent dans /srv/sublane/.key-migration. Le retour arrière restaure la configuration d’origine et la clé correspondante, puis recrée et vérifie le service d’origine. Il refuse d’écraser une modification ultérieure de la configuration ou de l’environnement, ou une clé différente, et ne rétrograde jamais l’image ni la base de données. La clé externe et les données de récupération restent privées après le retour arrière. Une nouvelle migration refuse d’écraser des données ou destinations existantes : archivez les données vérifiées en lieu sûr et choisissez un nouveau répertoire de clé avant de réessayer.

Le script partage .update-lock avec l’installateur ; n’exécutez aucune autre opération de déploiement en parallèle. Après un arrêt forcé ou une coupure électrique, confirmez qu’aucune migration ni mise à jour ne tourne, supprimez uniquement le .update-lock vide abandonné, puis utilisez --rollback. Si le retour arrière ne peut pas être vérifié, le matériel de clé de récupération et un operation.log privé sont conservés. Gardez les deux répertoires jusqu’à la fin de la récupération. Les archives conservées et leurs mots de passe restent à gérer séparément.

Sauvegardes chiffrées automatiques

Activez les paramètres de déploiement ci-dessous. Répertoire privé (0700), mot de passe indépendant de 12–128 caractères dans un fichier ordinaire privé (0600, sans lien symbolique), séparé des données et des sauvegardes. Il est relu à chaque exécution.

export SUBLANE_BACKUP_DIR=/srv/sublane-backups
export SUBLANE_BACKUP_PASSWORD_FILE=/secure/sublane/backup-password
export SUBLANE_BACKUP_INTERVAL=24h
export SUBLANE_BACKUP_KEEP=7

Exécution au démarrage, puis attente de l’intervalle après chaque tentative. La nouvelle archive est entièrement vérifiée avant rotation des noms réservés scheduled- ; les archives manuelles et la nouvelle archive vérifiée sont conservées. Résultats dans les journaux du service. Aucun téléversement distant ou formulaire de planification ; désactivé en démonstration.

SUBLANE_BACKUP_INTERVAL: 1h–720h (default 24h). SUBLANE_BACKUP_KEEP: 1–365 (default 7).

Utilisez une destination de sauvegarde dédiée par instance.

Le paramètre facultatif SUBLANE_BACKUP_WEBHOOK_URL envoie à une destination HTTPS publique un événement JSON backup_failure borné par tentative échouée. Cette destination opérateur est propre à l’instance, séparée des alertes d’espace ; les échecs de livraison sont journalisés.

Avec Docker, utilisez les chemins du conteneur et montez le fichier privé et le répertoire de sauvegarde dédié accessible en écriture via une surcharge Compose locale ; autorisez l’utilisateur du service. Le tmpfs /tmp vaut 64 MiB par défaut. Les vérifications plus grandes nécessitent un montage privé séparé et TMPDIR dans la surcharge.