Fichiers et archives

La recette la plus courte du catalogue : récupérer l'archive, la décompresser, regarder ce qui en est sorti. Deux étapes, une sonde.

C'est aussi la recette la plus facile à rendre inutile. Une sonde qui se contente de dire « il y a des fichiers » signe un vert qui ne prouve rien. Cette page dit quoi lui demander.

Voir comment adapter le bloc fetch et comment trouver les seuils.

La sauvegarde en entrée

Une archive, produite chaque nuit, dans un dossier que le runner peut lire : storage_2026-09-02T03-00.tar.gz.

L'étape unpack accepte tar.gz, tar.bz2, tar.xz, gzip (un seul fichier), zip. Le modèle Archive Files de l'interface propose aussi auto, qui devine le format d'après le nom du fichier.

Le plan

{
  "steps": [
    {
      "type": "fetch",
      "name": "Récupérer les fichiers Docmost",
      "config": {
        "source": "local",
        "path": "/backups/docmost/files",
        "file_pattern": "storage_*.tar.gz",
        "selection_strategy": "latest_modified",
        "max_age": "3h",
        "output": "storage.tar.gz"
      }
    },
    {
      "type": "unpack",
      "name": "Extraire l'archive",
      "config": {
        "format": "tar.gz",
        "input": "storage.tar.gz",
        "output": "."
      }
    }
  ],
  "probes": [
    {
      "name": "dossier_present",
      "type": "filesystem-canary",
      "timeout": 60,
      "config": {
        "RESTOREPROOF_CANARY_PATH": "storage",
        "RESTOREPROOF_CANARY_MIN_FILES": "1",
        "RESTOREPROOF_CANARY_MIN_TOTAL_SIZE": "1024"
      }
    }
  ]
}

Ce que la sonde prouve

Le canari (filesystem-canary) répond à trois questions différentes, et vous pouvez les poser toutes en même temps — elles s'additionnent, elles ne se remplacent pas.

• Ce fichier est-il là ? RESTOREPROOF_CANARY_PATH nomme un chemin, relatif à l'espace de travail. C'est ce que la restauration devait ramener.
• L'arborescence a-t-elle fondu ? RESTOREPROOF_CANARY_MIN_FILES et RESTOREPROOF_CANARY_MIN_TOTAL_SIZE (en octets) sont des planchers. Ce sont eux qui attrapent la sauvegarde qui rétrécit en silence : les fichiers nommés sont toujours là, mais il n'y en a plus que quarante au lieu de douze mille.
• Y a-t-il des fichiers de ce genre ? RESTOREPROOF_CANARY_PATTERN prend un motif, par exemple *.sql.

Deux réserves sur les planchers : le comptage porte sur tout l'espace de travail, y compris l'archive téléchargée, et les dossiers ne comptent pas comme des fichiers.

Un nom de fichier ne prouve pas son contenu

Un fichier vide portant le bon nom se restaure aussi bien que le vrai. Pour aller plus loin, RESTOREPROOF_CANARY_FILES prend une liste JSON, où chaque entrée peut demander davantage que l'existence :

{
  "RESTOREPROOF_CANARY_FILES": "[{\"path\":\"config/settings.json\",\"contains\":\"db_host\",\"min_size\":100}]"
}

Les clés acceptées pour chaque entrée :

Clé	Ce qu'elle exige
path	le chemin, relatif à l'espace de travail
contains	le fichier contient ce texte
matches	le fichier correspond à cette expression régulière
min_size	le fichier pèse au moins tant d'octets
expected_hash	l'empreinte SHA-256 du fichier est exactement celle-ci
must_be_file	ce doit être un fichier, pas un dossier

Les contrôles de contenu lisent au plus 8 Mio par fichier. Au-delà, le message le dit, plutôt que d'affirmer que le texte est absent.

Exemple réel, sur une sauvegarde de dépôts Git : trois chemins nommés, plus les deux planchers.

{
  "name": "depot_clonable",
  "type": "filesystem-canary",
  "timeout": 60,
  "config": {
    "RESTOREPROOF_CANARY_FILES": "[{\"path\":\"repositories/demo/demo.git/HEAD\"},{\"path\":\"repositories/demo/demo.git/refs\"},{\"path\":\"repositories/demo/demo.git/objects\"}]",
    "RESTOREPROOF_CANARY_MIN_FILES": "10",
    "RESTOREPROOF_CANARY_MIN_TOTAL_SIZE": "10240"
  }
}

Un canari sans question échoue exprès

Si vous ne renseignez aucune de ces cinq variables, la sonde passe au rouge et vous donne les chiffres qu'elle a comptés. Ce n'est pas une panne : c'est l'étape de réglage. RestoreProof le signale comme tel et vous propose de reprendre ces chiffres comme seuils.

C'est délibéré. Le canari avait autrefois un mode « est-ce qu'il y a quelque chose ? » : il passait au vert sur un unique fichier vide, et l'exécution signait une preuve qui ne prouvait rien.

Trouver les bons nombres

Lancez un essai avec un canari sans seuils, ou avec des seuils volontairement bas. Il compte. L'écran vous propose ensuite MIN_FILES et MIN_TOTAL_SIZE 5 % en dessous de ce qu'il a mesuré. Vous confirmez.

Ne recopiez pas 1 et 1024 : ce sont les planchers de la démonstration, choisis pour ne jamais passer au rouge à tort. Ils attrapent l'effondrement, pas la dérive.

Vérifier une archive sans la décompresser

La sonde archive-integrity ouvre une archive de bout en bout et vérifie qu'elle se lit. Elle n'a de sens que dans un plan sans étape unpack : dès qu'un plan décompresse, l'étape unpack a déjà tout parcouru avant la première sonde, et une archive corrompue a déjà fait échouer l'étape. Garder les deux revient à payer une seconde décompression complète pour reprouver ce qui l'est déjà.

Son usage, c'est celui-ci : confirmer qu'une archive reste ouvrable, sans la restaurer.

{
  "steps": [
    {
      "type": "fetch",
      "name": "Récupérer l'archive",
      "config": { "source": "source_profile", "source_id": "<identifiant de votre source>" }
    }
  ],
  "probes": [
    {
      "name": "archive_readable",
      "type": "archive-integrity",
      "timeout": 120,
      "config": { "RESTOREPROOF_ARCHIVE_PATH": "*.tar.gz" }
    }
  ]
}

RESTOREPROOF_ARCHIVE_PATH accepte un motif, ou plusieurs noms séparés par des virgules. L'archive nommée qui manque est un échec, pas un détail : « le fichier que je sauvegarde toutes les nuits n'est pas dans la sauvegarde » est exactement la réponse que ce produit existe pour donner.

Et ensuite

Les recettes qui combinent une base et une arborescence de fichiers sont sur Applications auto-hébergées. Les certificats TLS, qui sont des fichiers dont on vérifie l'identité plutôt que le volume, sont sur LDAP, MongoDB, certificats.