Hacer copia de seguridad y restaurar

Esta guía cubre las cinco cosas que la gente hace de verdad con las copias de seguridad: crear una, recogerla, mover un espacio de trabajo, reponerlo y guardar copias fuera de la máquina. Para conocer la forma exacta de cada artefacto y cada operación, consulta la referencia de copias de seguridad.

Todo lo que hay aquí está en Ajustes → Servidor → Copia de seguridad y restauración.

Requisitos previos

Un cliente completo — la aplicación de escritorio o la web. Un teléfono emparejado no puede desencadenar nada de esto, por diseño.
Para crear, listar, descargar o eliminar una instantánea de la instalación: el propietario de la instalación.
Para las acciones por espacio de trabajo: administrador de ese espacio de trabajo para exportar, propietario para importarlo o eliminarlo.
Para las descargas y las subidas: una conexión directa al servidor. El relé intermediado transporta tramas RPC, no transferencias de archivos, y los controles de transferencia se desactivan con una nota cuando estás en una.

Qué cubre una copia de seguridad

Ambos artefactos son solo bases de datos:

Una instantánea de la instalación es un directorio con marca de tiempo: manifest.json, global.db y un <workspaceId>/workspace.db por cada espacio de trabajo.
Una exportación de espacio de trabajo es ese único archivo workspace.db.

Ninguno de los dos incluye el resto del directorio de datos: secrets.json (claves de emparejamiento, credenciales de proveedores, SSO), el blobs/ de un espacio de trabajo (imágenes pegadas en los mensajes), skills/, agents/, chat_credentials/, el audio de reuniones grabadas o las imágenes de rigs. Parte de eso es prescindible y parte no — la tabla completa está en la referencia, y cubrirlo es para lo que sirve la sección de fuera de la máquina.

Crear una instantánea de toda la instalación

Abre Ajustes → Servidor → Copia de seguridad y restauración.
En Instantáneas de la instalación, pulsa Crear copia ahora.
El aviso emergente indica el directorio que se ha escrito, en el host del servidor. La nueva instantánea aparece al principio de la lista.

El servidor sigue funcionando en todo momento. Cada archivo se escribe con VACUUM INTO, que es consistente frente a una base de datos activa, así que no hay ventana de mantenimiento ni necesidad de detener agentes.

Cada fila de la lista muestra la marca de tiempo, el tamaño en disco, cuántos espacios de trabajo se capturaron y si la instantánea está Completa o Incompleta. Incompleta significa que falta el manifiesto o que nombra archivos que no están — una copia de seguridad interrumpida por un fallo o por un disco lleno. Aun así se listan a propósito: una instantánea que no ves es una que crees tener. Una instantánea incompleta no puede restaurar toda la instalación, pero los archivos de espacio de trabajo que sí contiene se pueden adoptar de uno en uno.

Una fila también puede indicar n espacios de trabajo no capturados. O bien un espacio de trabajo registrado pero en el que nunca se ha escrito (todavía no hay archivo), o bien uno cuya copia falló — revisa el registro del servidor.

Programar copias de seguridad del espacio de trabajo y su retención

Abre Ajustes → Pipelines → Plantillas de pipeline para el espacio de trabajo y busca Workspace backup. Su programación, si está activada, se ejecuta todos los domingos a las 03:00 UTC: Back up workspace, seguido de Delete backups older than (30 días por defecto). El segundo nodo solo se ejecuta después de que la copia se complete correctamente. Puedes cambiar los días de retención en el nodo o desactivar la programación. Si el servidor está apagado a la hora programada, la programación se pone al día una vez cuando vuelve, en lugar de repetir cada semana perdida.

Las copias de seguridad de espacios de trabajo se guardan en el servidor en backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. El nodo de retención solo elimina copias antiguas de este espacio de trabajo; nunca elimina instantáneas de la instalación ni copias de otros espacios de trabajo. Estos archivos son solo de base de datos. Para retenerlos fuera de la máquina, cópialos por separado.

Estas copias de seguridad son independientes de la lista Instantáneas de la instalación. Para restaurar una, usa Datos del espacio de trabajo → Importar con la ruta workspace.db del lado del servidor de la copia. Importar sustituye la base de datos actual de ese espacio de trabajo, así que expórtala antes si puede que necesites deshacer la restauración.

Eliminar una instantánea de la instalación

En Instantáneas de la instalación, despliega la instantánea, incluso una incompleta, y usa Eliminar instantánea en la sección de peligro. Confirma su nombre. El directorio completo de la instantánea se elimina del servidor de forma permanente; descárgala antes si necesitas una copia. Un pipeline de copias de seguridad de espacios de trabajo nunca elimina estas instantáneas.

Recoger una copia en tu propia máquina

Las rutas que muestra la página están en la máquina que ejecuta cc_server. Cuando esa no es la máquina en la que estás, usa los botones Descargar:

Junto a cada espacio de trabajo, en Datos del espacio de trabajo → Descargar, para un solo archivo .db.
Junto a cada instantánea, en Instantáneas de la instalación → Descargar, para toda la instantánea como un .zip.

En escritorio eliges dónde acaba el archivo y el aviso emergente lo indica; en la web va a las descargas del navegador. En ambos casos los dos indican el progreso en bytes, porque son las dos cargas útiles que llegan a los gigabytes.

Ambos generan una copia nueva en el momento en que pulsas el botón, la transmiten en streaming y eliminan después la copia del servidor — una descarga no es «buscar el archivo que creó antes el botón de exportar».

Descomprimir un archivo de instantánea reproduce exactamente la estructura de la instantánea, que es lo que hace que restaurarla sea una simple copia de vuelta.

Mover un espacio de trabajo a otra instalación

Un espacio de trabajo es un solo archivo de base de datos, así que entregarlo es una operación con archivos.

En el servidor de origen, Ajustes → Servidor → Copia de seguridad y restauración → Datos del espacio de trabajo, despliega el espacio de trabajo y pulsa Descargar.
En el servidor de destino, crea (o elige) el espacio de trabajo que lo va a recibir.
Despliega ese espacio de trabajo y, en Restaurar desde este dispositivo, pulsa Elegir un archivo y subirlo. Elige el .db que descargaste.

Si ambos servidores son la misma máquina en la que estás, Guardar en el servidor más Importar → Elegir archivo hacen lo mismo sin el viaje de ida y vuelta; las rutas del diálogo de importación se resuelven en el host del servidor.

Hay dos cosas que se permiten y se registran en lugar de rechazarse: importar un archivo cuyo id de espacio de trabajo registrado difiere del destino (así es como duplicas un espacio de trabajo o lo restauras con un id nuevo) e importar un archivo de una instalación distinta. En este segundo caso, los dispositivos emparejados y los ids de usuario del archivo pertenecen a la instalación de la que vino y no se resolverán en esta — los datos propios del espacio de trabajo están intactos, pero vuelve a comprobar la pertenencia después de adoptarlo.

Los tokens del bot de chat están junto a la base de datos, no dentro de ella, así que un espacio de trabajo que entregas a otra persona no lleva credenciales activas. La instalación receptora vuelve a conectar las suyas.

Restaurar un espacio de trabajo desde una instantánea

En Instantáneas de la instalación, despliega la instantánea que quieras.
Busca la fila del espacio de trabajo y pulsa Restaurar.
Confirma. Todo lo que ese espacio de trabajo haya hecho desde que se tomó la instantánea se pierde.

Es la misma operación que una importación, apuntada a la copia que la instantánea guarda del archivo de ese espacio de trabajo — de forma deliberada, para que no haya un segundo mecanismo que pudiera tratar el mismo archivo de otra manera.

Una fila puede indicar Ya no está en este servidor, con Restaurar desactivado: la instantánea contiene un espacio de trabajo que esta instalación ya no tiene. Recupéralo a mano — crea un espacio de trabajo y luego, en Datos del espacio de trabajo, importa en él desde <snapshot path>/<old workspace id>/workspace.db. La instantánea desplegada muestra su propia Ruta en el servidor en un campo de copia, y el título de la fila es el id del espacio de trabajo antiguo, así que tienes delante las dos mitades de esa ruta.

Restaurar toda la instalación

No hay ningún botón para esto, y no debería haberlo: sustituye las bases de datos que el servidor en ejecución tiene abiertas.

Detén cc_server. Si usas la aplicación de escritorio con su servidor integrado, cierra la aplicación.

Copia el contenido de la instantánea sobre el directorio de datos. La estructura de la instantánea refleja la activa, así que es una copia sin más:

# 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

Elimina los archivos -wal y -shm que estén junto a las bases de datos que has sustituido. Pertenecen a los archivos antiguos y uno obsoleto junto a una base de datos restaurada es un riesgo de corrupción.
Vuelve a iniciar el servidor.

La instantánea no contiene secrets.json, así que una instalación restaurada en un host nuevo conserva sus datos pero no sus credenciales: los dispositivos emparejados, los tokens de proveedores y los ajustes de SSO hay que volver a establecerlos, o restaurarlos desde dondequiera que guardaras ese archivo. Restaurar en el mismo host, donde secrets.json nunca se perdió, lo conserva todo.

Copiar las copias de seguridad fuera de la máquina

Una instantánea en el mismo disco que la base de datos que copió te protege de una importación mala, no del disco. Nada en Control Center envía una copia a ningún sitio, así que esta parte es cosa tuya.

Sincronizar las instantáneas

Las instantáneas son inmutables una vez escritas y se nombran por marca de tiempo, así que cualquier herramienta de sincronización las maneja bien. Excluye transfer/, que es un banco de trabajo para descargas y subidas en curso:

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 refleja tu limpieza local en el remoto. Quítalo si quieres que el remoto conserve instantáneas durante más tiempo que el host.

Incluir lo que deja fuera una instantánea

Para poder reconstruir la instalación y no solo sus datos, copia también estos. Son archivos normales, seguros de copiar mientras el servidor está en ejecución:

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 tiene permisos 0600 y contiene todas las claves de emparejamiento, las credenciales de proveedores y los ajustes de SSO de la instalación. Allí donde acabe debe estar al menos tan protegido como el host del servidor — cifrado en reposo y no en un bucket que cualquier otro pueda leer.

Omite spaces/ (worktrees con copy-on-write, reaprovisionados desde tus repos), pr_clones/ (una caché), models/ (se vuelven a descargar), media_cache/ y rigs/ (estado de la máquina, y grandes). El audio de reuniones grabadas en meetings/ merece la pena incluirlo si conservas reuniones.

Programar una instantánea de toda la instalación fuera de la aplicación

El pipeline integrado solo hace copia de seguridad de un espacio de trabajo. Para una instantánea de toda la instalación sin intervención, no hay ningún subcomando de la CLI, y el RPC de instantáneas requiere un cliente completo emparejado que sea el propietario de la instalación. Un temporizador del host puede usar VACUUM INTO sobre las bases de datos activas:

#!/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

Ejecútalo como el mismo usuario que es propietario del directorio de datos, desde cron o un temporizador de systemd, y sincroniza DEST fuera del host después. VACUUM INTO necesita SQLite 3.27 o posterior.

Escríbelo fuera de <dataDir>/backups/. Un directorio hecho a mano ahí no tiene manifest.json, así que la aplicación lo listaría como una instantánea incompleta y la lista dejaría de ser un registro honesto de lo que produjo el propio servidor.

Purgar instantáneas antiguas de toda la instalación

Puedes eliminar instantáneas de la instalación concretas en la aplicación. Para una política de retención del lado del host, mantén el directorio de copias de seguridad de espacios de trabajo separado de las instantáneas de la instalación:

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

Comprueba la salida de una ejecución con -print antes de añadir -exec. Conserva más de una: el fallo del que te proteges suele ser «la última copia de seguridad también tiene el problema».

Comprobar que una copia de seguridad es buena

Una copia de seguridad que nadie ha restaurado es una hipótesis.

Comprobación barata — el archivo se abre y sus páginas están intactas:

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

Comprobación real — adóptala. Crea un espacio de trabajo desechable en una instalación que no sea de producción, importa en él un archivo de espacio de trabajo y mira si están los espacios, los tickets y los mensajes que esperas. Eso ejercita el mismo camino que sigue una restauración real, incluida la reconstrucción de FTS, y es la única comprobación que te dice que la copia de seguridad es restaurable y no solo legible.

Hazlo una vez cuando configures las copias de seguridad, y de nuevo siempre que cambies dónde se almacenan.

Solución de problemas

Síntoma	Causa y solución
Los controles de descarga y subida están desactivados con una nota sobre un relé	Estás conectado a través del relé intermediado, que no transporta transferencias de archivos. Conéctate directamente
«El servidor lo rechazó»	Rol. Crear o listar una instantánea de la instalación necesita el operador de la instalación. Descargar un espacio de trabajo necesita administrador, restaurar uno necesita propietario, un zip de instantánea completa necesita el operador de la instalación
«Este servidor no expone ninguna superficie de copia de seguridad»	El host no tiene ningún puerto de copia de seguridad conectado — un servidor de demostración. Las operaciones están ausentes en lugar de rechazadas
«El archivo supera el tamaño que acepta el servidor»	Las subidas tienen un límite de 8 GiB. Pon el archivo en el host del servidor y usa mejor Importar → Elegir archivo
Import refused: not a Control Center workspace database	El archivo no tiene ninguna fila `workspace_meta` — no es una exportación de espacio de trabajo, o está truncado. No se sustituyó nada
Una instantánea aparece como Incompleta	Falta su manifiesto o nombra archivos ausentes. Crea una nueva; mientras tanto, adopta de ella los archivos de espacio de trabajo individuales
Una instantánea dice que no se capturaron espacios de trabajo	En esos espacios de trabajo nunca se ha escrito, o su copia falló. Revisa el registro del servidor
Una instalación restaurada no tiene credenciales del host de código ni de SSO	`secrets.json` no está en una instantánea. Restáuralo desde donde lo guardaras, o vuelve a conectar los proveedores
A un espacio de trabajo restaurado le faltan las imágenes pegadas	Los blobs están junto a la base de datos, no dentro de ella. Copia también `<workspaceId>/blobs/`

Guías relacionadas

Ejecutar un servidor headless: de dónde viene el directorio de datos
Conectar a un servidor remoto: conexiones directas frente a las que pasan por el relé
Emparejar un dispositivo: la credencial con la que firman las rutas de transferencia

Conceptos y referencia relacionados

Copia de seguridad, exportación e importación: cada operación, ruta, campo y límite
Espacios de trabajo y aislamiento: por qué un espacio de trabajo es un solo archivo
cc_server CLI: la estructura del directorio de datos