Sauvegarder et restaurer

Ce guide couvre les cinq choses que les gens font réellement avec les sauvegardes : en prendre une, en récupérer une copie, déplacer un espace de travail, en remettre une en place et conserver des copies hors de la machine. Pour la forme exacte de chaque artefact et de chaque opération, consultez la référence sur la sauvegarde.

Tout ce qui suit se trouve dans Paramètres → Serveur → Sauvegarde et restauration.

Prérequis

Un client complet — l’application de bureau ou l’application Web. Un téléphone associé ne peut déclencher aucune de ces opérations, par conception.
Pour créer, lister, télécharger ou supprimer un instantané de l’installation : le propriétaire de l’installation.
Pour les opérations par espace de travail : admin de cet espace de travail pour exporter, propriétaire pour l’importer ou le supprimer.
Pour les téléchargements et les téléversements : une connexion directe au serveur. Le relais intermédié transporte des trames RPC, pas des transferts de fichiers, et les commandes de transfert se désactivent avec une note lorsque vous passez par lui.

Ce que couvre une sauvegarde

Les deux artefacts sont des bases de données uniquement :

Un instantané de l’installation est un répertoire horodaté : manifest.json, global.db et un <workspaceId>/workspace.db par espace de travail.
Une exportation d’espace de travail est ce seul fichier workspace.db.

Ni l’un ni l’autre ne transporte le reste du répertoire de données : secrets.json (clés d’association, identifiants de fournisseurs, SSO), le dossier blobs/ d’un espace de travail (images collées dans les messages), skills/, agents/, chat_credentials/, l’audio des réunions enregistrées ou les images de rig. Une partie de tout cela est jetable et une autre ne l’est pas — le tableau complet se trouve dans la référence, et c’est à cela que sert la section sur les copies hors machine.

Créer un instantané de toute l’installation

Ouvrez Paramètres → Serveur → Sauvegarde et restauration.
Sous Instantanés de l’installation, appuyez sur Sauvegarder maintenant.
La notification indique le répertoire qui a été écrit, sur l’hôte du serveur. Le nouvel instantané apparaît au sommet de la liste.

Le serveur continue de fonctionner pendant toute l’opération. Chaque fichier est écrit avec VACUUM INTO, ce qui garantit la cohérence par rapport à une base de données active : aucune fenêtre de maintenance n’est nécessaire et il n’est pas utile d’arrêter les agents.

Chaque ligne de la liste indique l’horodatage, la taille sur le disque, le nombre d’espaces de travail capturés et si l’instantané est Complet ou Incomplet. « Incomplet » signifie que le manifeste est absent ou qu’il nomme des fichiers qui ne sont pas là — une sauvegarde interrompue par un plantage ou un disque plein. Ces instantanés restent listés volontairement : un instantané que vous ne voyez pas est un instantané que vous croyez avoir. Un instantané incomplet ne peut pas restaurer une installation complète, mais les fichiers d’espace de travail qu’il contient peuvent tout de même être adoptés un à la fois.

Une ligne peut aussi indiquer n espaces de travail non capturés. Il s’agit d’un espace de travail enregistré, mais dans lequel rien n’a jamais été écrit (aucun fichier n’existe encore), ou dont la copie a échoué — vérifiez le journal du serveur.

Planifier les sauvegardes d’espaces de travail et leur conservation

Ouvrez Paramètres → Pipelines → Modèles de pipeline pour l’espace de travail et trouvez Workspace backup. Sa planification activée s’exécute chaque dimanche à 03:00 UTC : Back up workspace, suivi de Delete backups older than (30 jours par défaut). Le second nœud ne s’exécute qu’après la réussite de la sauvegarde. Vous pouvez modifier le nombre de jours de conservation sur le nœud ou désactiver la planification. Si le serveur est hors ligne à l’heure prévue, la planification rattrape son retard une seule fois à son retour, plutôt que de rejouer chaque semaine manquée.

Les sauvegardes d’espaces de travail résident sur le serveur sous backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. Le nœud de conservation ne supprime que les anciennes sauvegardes de cet espace de travail ; il ne supprime jamais les instantanés de l’installation ni les sauvegardes des autres espaces de travail. Ces fichiers ne contiennent que des bases de données. Pour une conservation hors machine, copiez-les indépendamment.

Ces sauvegardes sont distinctes de la liste Instantanés de l’installation. Pour en restaurer une, utilisez Données des espaces de travail → Importer avec le chemin workspace.db de la sauvegarde, côté serveur. L’importation remplace la base de données actuelle de cet espace de travail ; exportez-la d’abord si vous pourriez avoir besoin d’annuler la restauration.

Supprimer un instantané de l’installation

Sous Instantanés de l’installation, dépliez l’instantané, même s’il est incomplet, et utilisez Supprimer l’instantané dans la section de danger. Confirmez son nom. Le répertoire de l’instantané est entièrement et définitivement supprimé du serveur ; téléchargez-le d’abord si vous en voulez une copie. Un pipeline de sauvegarde d’espace de travail ne supprime jamais ces instantanés.

Récupérer une copie sur votre propre machine

Les chemins affichés dans la page se trouvent sur la machine qui exécute cc_server. Lorsque ce n’est pas la machine devant laquelle vous êtes assis, utilisez les boutons Télécharger :

À côté de chaque espace de travail, sous Données des espaces de travail → Télécharger, pour un seul fichier .db.
À côté de chaque instantané, sous Instantanés de l’installation → Télécharger, pour l’instantané complet sous forme de .zip.

Sur ordinateur, vous choisissez l’emplacement du fichier et la notification l’indique ; sur le Web, il aboutit dans les téléchargements du navigateur. Dans les deux cas, la progression est exprimée en octets, car ce sont les deux charges utiles qui atteignent des gigaoctets.

Les deux produisent une copie fraîche au moment où vous appuyez sur le bouton, la diffusent en continu, puis suppriment la copie du serveur — un téléchargement ne consiste pas à « récupérer le fichier créé plus tôt par le bouton d’exportation ».

Décompresser une archive d’instantané reproduit exactement la disposition de l’instantané, et c’est ce qui fait d’une restauration une simple copie en retour.

Déplacer un espace de travail vers une autre installation

Un espace de travail correspond à un fichier de base de données, donc le transférer est une opération sur fichier.

Sur le serveur source, Paramètres → Serveur → Sauvegarde et restauration → Données des espaces de travail, dépliez l’espace de travail et appuyez sur Télécharger.
Sur le serveur de destination, créez (ou choisissez) l’espace de travail qui le recevra.
Dépliez cet espace de travail, puis, sous Restaurer depuis cet appareil, appuyez sur Choisir un fichier et l’envoyer. Choisissez le fichier .db que vous avez téléchargé.

Si les deux serveurs sont la même machine que celle devant laquelle vous êtes assis, Enregistrer sur le serveur suivi d’Importer → Choisir un fichier produit le même résultat sans aller-retour ; les chemins de la boîte de dialogue d’importation sont résolus sur l’hôte du serveur.

Deux situations sont autorisées et journalisées plutôt que refusées : importer un fichier dont l’identifiant d’espace de travail enregistré diffère de celui de la cible (c’est ainsi qu’on duplique un espace de travail ou qu’on le restaure sous un nouvel identifiant), et importer un fichier provenant d’une autre installation. Dans ce second cas, les appareils associés et les identifiants d’utilisateur du fichier appartiennent à l’installation d’origine et ne se résoudront pas sur celle-ci — les données propres à l’espace de travail sont intactes, mais vérifiez de nouveau l’adhésion après son adoption.

Les jetons des robots de clavardage résident à côté de la base de données, pas à l’intérieur, de sorte qu’un espace de travail que vous remettez à quelqu’un d’autre ne transporte aucun identifiant actif. L’installation qui le reçoit reconnecte les siens.

Restaurer un espace de travail à partir d’un instantané

Sous Instantanés de l’installation, dépliez l’instantané voulu.
Repérez la ligne de l’espace de travail et appuyez sur Restaurer.
Confirmez. Tout ce que cet espace de travail a fait depuis la création de l’instantané est perdu.

Il s’agit de la même opération qu’une importation, dirigée vers la copie du fichier de cet espace de travail contenue dans l’instantané — délibérément, pour qu’aucun second mécanisme ne puisse traiter le même fichier différemment.

Une ligne peut indiquer N’existe plus sur ce serveur, avec Restaurer désactivé : l’instantané contient un espace de travail que cette installation n’a plus. Récupérez-le manuellement — créez un espace de travail, puis, sous Données des espaces de travail, importez-y le fichier à partir de <snapshot path>/<old workspace id>/workspace.db. L’instantané déplié affiche son propre Chemin sur le serveur dans un champ copiable, et le titre de la ligne est l’ancien identifiant d’espace de travail : vous avez donc les deux moitiés de ce chemin sous les yeux.

Restaurer une installation complète

Il n’existe aucun bouton pour cela, et il ne devrait pas y en avoir : cette opération remplace les bases de données que le serveur en cours d’exécution garde ouvertes.

Arrêtez cc_server. Si vous utilisez l’application de bureau avec son serveur intégré, quittez l’application.

Copiez le contenu de l’instantané par-dessus le répertoire de données. La disposition de l’instantané reproduit celle des données actives, il s’agit donc d’une simple copie :

# macOS default; see the CLI reference for other platforms
DATA_DIR="$HOME/Library/Application Support/control-center"
SNAPSHOT="$DATA_DIR/backups/2026-07-28T09-12-33-000Z"

cp "$SNAPSHOT/global.db" "$DATA_DIR/global.db"
for d in "$SNAPSHOT"/*/; do
  id=$(basename "$d")
  mkdir -p "$DATA_DIR/$id"
  cp "$d/workspace.db" "$DATA_DIR/$id/workspace.db"
done

Supprimez les fichiers -wal et -shm qui se trouvent à côté des bases de données que vous avez remplacées. Ils appartiennent aux anciens fichiers, et un fichier résiduel à côté d’une base de données restaurée constitue un risque de corruption.
Redémarrez le serveur.

L’instantané ne contient aucun secrets.json : une installation restaurée sur un hôte neuf conserve donc ses données, mais pas ses identifiants. Les appareils associés, les jetons de fournisseurs et les paramètres SSO doivent être rétablis, ou restaurés depuis l’endroit où vous avez conservé ce fichier. Une restauration sur le même hôte, où secrets.json n’a jamais été perdu, conserve tout.

Copier les sauvegardes hors de la machine

Un instantané sur le même disque que la base de données qu’il a copiée vous protège d’une mauvaise importation, pas d’une défaillance du disque. Rien dans Control Center n’envoie de copie où que ce soit, cette partie vous revient donc.

Synchroniser les instantanés

Les instantanés sont immuables une fois écrits et nommés selon leur horodatage, de sorte que n’importe quel outil de synchronisation les traite bien. Excluez transfer/, qui est un atelier pour les téléchargements et les téléversements en cours :

DATA_DIR="$HOME/Library/Application Support/control-center"

# To another host over ssh
rsync -a --delete --exclude 'transfer/' \
  "$DATA_DIR/backups/" backup-host:/srv/control-center-backups/

# To object storage
aws s3 sync --exclude 'transfer/*' \
  "$DATA_DIR/backups/" s3://my-bucket/control-center/backups/

# Or with deduplication, encryption and its own retention
restic backup --exclude 'transfer' "$DATA_DIR/backups"

--delete reproduit sur la destination votre élagage local. Omettez-le si vous voulez que la destination conserve les instantanés plus longtemps que l’hôte.

Inclure ce qu’un instantané omet

Pour pouvoir reconstruire l’installation et pas seulement ses données, copiez aussi ces éléments. Ce sont des fichiers ordinaires, que vous pouvez copier sans danger pendant que le serveur fonctionne :

rsync -a \
  "$DATA_DIR/secrets.json" \
  backup-host:/srv/control-center-backups/config/

rsync -a --relative \
  "$DATA_DIR"/./*/chat_credentials \
  "$DATA_DIR"/./*/blobs \
  "$DATA_DIR"/./*/skills \
  "$DATA_DIR"/./*/agents \
  backup-host:/srv/control-center-backups/workspace-files/

secrets.json a les permissions 0600 et contient toutes les clés d’association, tous les identifiants de fournisseurs et tous les paramètres SSO de l’installation. L’endroit où il aboutit doit être au moins aussi protégé que l’hôte du serveur — chiffré au repos, et non un compartiment que quiconque peut lire.

Omettez spaces/ (arbres de travail en copie à l’écriture, reprovisionnés à partir de vos dépôts), pr_clones/ (un cache), models/ (retéléchargés), media_cache/ et rigs/ (état de la machine, et volumineux). L’audio des réunions enregistrées sous meetings/ vaut la peine d’être inclus si vous conservez les réunions.

Planifier un instantané complet de l’installation à l’extérieur de l’application

Le pipeline intégré ne sauvegarde qu’un seul espace de travail. Pour un instantané complet de l’installation sans surveillance, il n’existe aucune sous-commande CLI, et l’appel RPC d’instantané exige un client complet associé qui soit le propriétaire de l’installation. Une minuterie côté hôte peut utiliser VACUUM INTO sur les bases de données actives :

#!/usr/bin/env bash
set -euo pipefail

DATA_DIR="${CC_SERVER_DATA_DIR:-$HOME/.local/share/control-center}"
DEST="/srv/control-center-snapshots/$(date -u +%Y-%m-%dT%H-%M-%SZ)"
mkdir -p "$DEST"

sqlite3 "$DATA_DIR/global.db" "VACUUM INTO '$DEST/global.db'"

for db in "$DATA_DIR"/*/workspace.db; do
  id=$(basename "$(dirname "$db")")
  mkdir -p "$DEST/$id"
  sqlite3 "$db" "VACUUM INTO '$DEST/$id/workspace.db'"
done

Exécutez-le en tant que le même utilisateur que celui qui possède le répertoire de données, à partir de cron ou d’une minuterie systemd, puis synchronisez DEST à l’extérieur de l’hôte. VACUUM INTO exige SQLite 3.27 ou une version plus récente.

Écrivez-le à l’extérieur de <dataDir>/backups/. Un répertoire fabriqué à la main à cet endroit n’a pas de manifest.json : l’application le listerait comme un instantané incomplet et la liste cesserait d’être un relevé fidèle de ce que le serveur lui-même a produit.

Élaguer les anciens instantanés complets de l’installation

Vous pouvez supprimer des instantanés de l’installation un par un dans l’application. Pour appliquer une politique de conservation côté hôte, gardez le répertoire des sauvegardes d’espaces de travail séparé des instantanés de l’installation :

find "$DATA_DIR/backups" -mindepth 1 -maxdepth 1 -type d \
  ! -name exports ! -name transfer ! -name workspace-backups \
  -mtime +30 -exec rm -rf {} +

Vérifiez la sortie d’une exécution avec -print avant d’ajouter -exec. Conservez-en plus d’un : la défaillance contre laquelle vous vous protégez est souvent « la dernière sauvegarde a aussi le problème ».

Vérifier qu’une sauvegarde est bonne

Une sauvegarde que personne n’a restaurée n’est qu’une hypothèse.

Vérification rapide — le fichier s’ouvre et ses pages sont intactes :

sqlite3 "$SNAPSHOT/global.db" 'PRAGMA integrity_check;'   # expects: ok

Vérification réelle — adoptez-la. Créez un espace de travail jetable sur une installation qui n’est pas en production, importez-y un fichier d’espace de travail et regardez si les espaces, les tickets et les messages attendus s’y trouvent. Cela emprunte le même chemin qu’une vraie restauration, y compris la reconstruction du FTS, et c’est la seule vérification qui vous dit que la sauvegarde est restaurable et pas seulement lisible.

Faites-le une fois au moment de mettre en place les sauvegardes, puis de nouveau chaque fois que vous changez l’endroit où elles sont stockées.

Dépannage

Symptôme	Cause et solution
Les commandes de téléchargement et de téléversement sont désactivées avec une note au sujet d’un relais	Vous êtes connecté par le relais intermédié, qui ne transporte aucun transfert de fichiers. Connectez-vous directement
« Le serveur a refusé »	Rôle. Créer ou lister un instantané de l’installation exige l’opérateur de l’installation. Télécharger un espace de travail exige le rôle admin, le restaurer exige le rôle propriétaire, et le zip d’un instantané complet exige l’opérateur de l’installation
« Ce serveur n’a aucune interface de sauvegarde »	Aucun port de sauvegarde n’est câblé sur l’hôte — c’est un serveur de démonstration. Les opérations sont absentes plutôt que refusées
« Le fichier dépasse ce que le serveur accepte »	Les téléversements sont plafonnés à 8 GiB. Placez le fichier sur l’hôte du serveur et utilisez plutôt Importer → Choisir un fichier
Importation refusée : ce n’est pas une base de données d’espace de travail Control Center	Le fichier n’a pas de ligne `workspace_meta` — ce n’est pas une exportation d’espace de travail, ou il est tronqué. Rien n’a été remplacé
Un instantané est listé comme Incomplet	Son manifeste est absent ou nomme des fichiers manquants. Créez-en un nouveau ; entre-temps, adoptez les fichiers d’espace de travail qu’il contient un par un
Un instantané indique que des espaces de travail n’ont pas été capturés	Rien n’a jamais été écrit dans ces espaces de travail, ou leur copie a échoué. Vérifiez le journal du serveur
Une installation restaurée n’a aucun identifiant de forge ni de SSO	`secrets.json` ne se trouve pas dans un instantané. Restaurez-le depuis l’endroit où vous l’avez conservé, ou reconnectez les fournisseurs
Des images collées manquent dans un espace de travail restauré	Les blobs résident à côté de la base de données, pas dedans. Copiez aussi `<workspaceId>/blobs/`

Guides connexes

Exécuter un serveur sans interface : d’où vient le répertoire de données
Se connecter à un serveur distant : connexions directes ou relayées
Associer un appareil : l’identifiant avec lequel les routes de transfert signent

Concepts et référence connexes

Sauvegarde, export et import : chaque opération, route, champ et limite
Espaces de travail et isolation : pourquoi un espace de travail correspond à un seul fichier
CLI cc_server : la disposition du répertoire de données