Sauvegarder et restaurer

Ce guide couvre les cinq choses que l’on fait réellement avec les sauvegardes : en créer une, la récupérer, déplacer un espace de travail, en remettre un 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 de sauvegarde.

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

Prérequis

Un client complet — l’application de bureau ou 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 actions par espace de travail : le rôle admin de cet espace de travail pour exporter, propriétaire pour l’importer ou le supprimer.
Pour les téléchargements et les envois : une connexion directe au serveur. Le relais intermédié transporte des trames RPC, pas des transferts de fichiers, et les contrôles de transfert se désactivent avec une note lorsque vous passez par un relais.

Ce que couvre une sauvegarde

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

Un instantané de l’installation est un répertoire horodaté : manifest.json, global.db et un <workspaceId>/workspace.db par espace de travail.
Un export 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’appairage, identifiants de fournisseurs, SSO), les 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 rigs. Une partie est jetable, une autre non — le tableau complet se trouve dans la référence, et c’est à cela que sert la section 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 en haut de la liste.

Le serveur continue de fonctionner pendant toute l’opération. Chaque fichier est écrit avec VACUUM INTO, qui est cohérent face à une base de données active : il n’y a donc ni fenêtre de maintenance, ni besoin d’arrêter les agents.

Chaque ligne de la liste affiche l’horodatage, la taille sur 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 désigne des fichiers qui ne sont pas là — une sauvegarde interrompue par un plantage ou par un disque plein. Ces instantanés restent listés à dessein : un instantané que vous ne voyez pas est un instantané que vous croyez posséder. Un instantané incomplet ne peut pas restaurer toute l’installation, mais les fichiers d’espace de travail qu’il contient peuvent encore être adoptés un par un.

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 (le fichier n’existe pas encore), ou d’un espace de travail dont la copie a échoué — consultez le journal du serveur.

Programmer les sauvegardes d’espace de travail et leur rétention

Ouvrez Paramètres → Pipelines → Modèles de pipeline pour l’espace de travail et recherchez Workspace backup. Sa programmation, si elle est 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 rétention sur le nœud ou désactiver la programmation. Si le serveur est hors ligne à l’heure prévue, la programmation se rattrape une fois à son retour, au lieu de rejouer chaque semaine manquée.

Les sauvegardes d’espace de travail résident sur le serveur sous backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. Le nœud de rétention ne supprime que les anciennes sauvegardes de cet espace de travail ; il ne supprime jamais les instantanés de l’installation ni les sauvegardes d’autres espaces de travail. Ces fichiers ne contiennent que des bases de données. Pour une rétention 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 côté serveur de la sauvegarde. L’import remplace la base de données actuelle de cet espace de travail : exportez-la d’abord si vous risquez d’avoir besoin d’annuler la restauration.

Supprimer un instantané de l’installation

Sous Instantanés de l’installation, dépliez l’instantané, y compris incomplet, et utilisez Supprimer l’instantané dans la zone sensible. Confirmez son nom. Le répertoire entier de l’instantané est définitivement supprimé du serveur ; téléchargez-le d’abord si vous avez besoin d’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 sur la page se trouvent sur la machine qui exécute cc_server. Lorsque ce n’est pas la machine sur laquelle vous êtes, 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é entier sous forme de .zip.

Sur ordinateur, vous choisissez où le fichier atterrit et la notification l’indique ; sur le web, il va dans les téléchargements du navigateur. Dans les deux cas, la progression est indiquée en octets, parce que ce sont les deux charges utiles qui atteignent les gigaoctets.

Les deux génèrent une copie fraîche au moment où vous appuyez sur le bouton, la diffusent en flux, 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’export ».

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

Déplacer un espace de travail vers une autre installation

Un espace de travail est un seul fichier de base de données : le transmettre est donc 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 et, sous Restaurer depuis cet appareil, appuyez sur Choisir un fichier et l’envoyer. Choisissez le .db que vous avez téléchargé.

Si les deux serveurs sont la machine sur laquelle vous êtes, Enregistrer sur le serveur puis Importer → Choisir un fichier font la même chose sans aller-retour ; les chemins de la boîte de dialogue d’import sont résolus sur l’hôte du serveur.

Deux cas sont autorisés et journalisés plutôt que refusés : importer un fichier dont l’identifiant d’espace de travail enregistré diffère de la cible (c’est ainsi que vous dupliquez un espace de travail ou le restaurez sous un nouvel identifiant), et importer un fichier provenant d’une autre installation. Dans ce second cas, les appareils associés et les identifiants utilisateur du fichier appartiennent à l’installation d’origine et ne se résoudront pas sur celle-ci — les données propres de l’espace de travail sont intactes, mais revérifiez les appartenances après l’avoir adopté.

Les jetons de robot de chat se trouvent à côté de la base de données, pas dedans : un espace de travail que vous confiez à quelqu’un d’autre ne transporte donc aucun identifiant actif. L’installation qui le reçoit reconnecte les siens.

Restaurer un espace de travail depuis un instantané

Sous Instantanés de l’installation, dépliez l’instantané souhaité.
Trouvez la ligne de l’espace de travail et appuyez sur Restaurer.
Confirmez. Tout ce que cet espace de travail a fait depuis la prise de l’instantané est perdu.

Il s’agit de la même opération qu’un import, pointé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 ne possède plus. Ramenez-le manuellement — créez un espace de travail, puis, sous Données des espaces de travail, importez-y depuis <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 toute une installation

Il n’existe aucun bouton pour cela, et il ne devrait pas y en avoir : l’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 embarqué, quittez l’application.

Copiez le contenu de l’instantané par-dessus le répertoire de données. L’arborescence de l’instantané reflète celle de l’installation active : 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 tout fichier -wal et -shm situé à côté des bases de données que vous avez remplacées. Ils appartiennent aux anciens fichiers, et un fichier obsolète à côté d’une base de données restaurée constitue un risque de corruption.
Redémarrez le serveur.

L’instantané ne contient pas de 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’un mauvais import, pas du disque. Rien dans Control Center n’expédie de copie où que ce soit : cette partie vous revient.

Synchroniser les instantanés

Les instantanés sont immuables une fois écrits et nommés par horodatage, si bien que tout outil de synchronisation les gère sans problème. Excluez transfer/, qui est un atelier pour les téléchargements et les envois 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 reflète votre élagage local sur le distant. Retirez-le si vous voulez que le distant conserve les instantanés plus longtemps que l’hôte.

Inclure ce qu’un instantané laisse de côté

Pour pouvoir reconstruire l’installation et pas seulement ses données, copiez aussi ces éléments. Ce sont des fichiers ordinaires, que l’on peut copier sans risque pendant que le serveur tourne :

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 est en 0600 et contient chaque clé d’appairage, identifiant de fournisseur et paramètre SSO de l’installation. Partout où il atterrit doit être au moins aussi protégé que l’hôte du serveur — chiffré au repos, et pas dans un bucket que d’autres peuvent lire.

Ignorez spaces/ (arbres de travail copy-on-write, reprovisionnés depuis 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.

Programmer un instantané de toute l’installation en dehors de l’application

Le pipeline intégré ne sauvegarde qu’un seul espace de travail. Pour un instantané de toute l’installation sans intervention, 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. Un minuteur 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 sous le même utilisateur que celui qui possède le répertoire de données, depuis cron ou un minuteur systemd, puis synchronisez DEST hors de l’hôte. VACUUM INTO nécessite SQLite 3.27 ou une version ultérieure.

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

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

Vous pouvez supprimer des instantanés de l’installation individuellement dans l’application. Pour une politique de rétention côté hôte, gardez le répertoire des sauvegardes d’espace de travail distinct 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 panne contre laquelle vous vous protégez est souvent « la dernière sauvegarde aussi a 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 simple — 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 hors 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 restauration réelle, y compris la reconstruction FTS, et c’est la seule vérification qui vous dit que la sauvegarde est restaurable et pas seulement lisible.

Faites-le une fois lorsque vous mettez en place les sauvegardes, et de nouveau chaque fois que vous changez l’endroit où elles sont stockées.

Dépannage

Symptôme	Cause et solution
Les contrôles de téléchargement et d’envoi sont désactivés avec une note sur un relais	Vous êtes connecté via le relais intermédié, qui ne transporte aucun transfert de fichier. 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, en restaurer un exige le rôle propriétaire, et un zip d’instantané complet exige l’opérateur de l’installation
« Ce serveur n’expose aucune surface de sauvegarde »	L’hôte n’a aucun port de sauvegarde câblé — un serveur de démonstration. Les opérations sont absentes plutôt que refusées
« Le fichier dépasse la taille acceptée par le serveur »	Les envois sont plafonnés à 8 GiB. Placez le fichier sur l’hôte du serveur et utilisez plutôt Importer → Choisir un fichier
Import refused: not a Control Center workspace database	Le fichier n’a aucune ligne `workspace_meta` — ce n’est pas un export d’espace de travail, ou il est tronqué. Rien n’a été remplacé
Un instantané est listé comme Incomplet	Son manifeste est absent ou désigne des fichiers manquants. Créez-en un nouveau ; en attendant, adoptez-en les fichiers d’espace de travail individuels
Un instantané signale que des espaces de travail n’ont pas été capturés	Ces espaces de travail n’ont jamais reçu d’écriture, ou leur copie a échoué. Consultez le journal du serveur
Une installation restaurée n’a plus d’identifiants d’hébergeur de code ni de SSO	`secrets.json` ne figure 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 tient dans un seul fichier
cc_server CLI : l’organisation du répertoire de données