Respaldo y restauración

MonoPbx respalda Postgres (una instantánea consistente), ClickHouse (registros de llamadas, calidad, eventos, auditoría y registros de la aplicación), los secretos de instalación, incluida la clave maestra, la configuración que no es secreta y, si lo pide, las grabaciones y los buzones de voz. Todo se cifra con una frase de paso que usted elige y se escribe en un directorio local, en un servicio compatible con S3 o en Google Cloud Storage. Para restaurar en un host nuevo se necesitan dos cosas: el respaldo y su frase de paso.

:::warning Guarde la frase de paso MonoPbx no puede recuperarla. Guarde una copia fuera del servidor. Sin ella, el respaldo no sirve. :::

Qué contiene un respaldo

Parte	Contenido
postgres	Todas las tablas: empresas, usuarios, extensiones, troncales, configuración, secretos cifrados, certificados y la propia configuración de respaldos.
clickhouse	Registros de llamadas, tramos, calidad de llamadas, eventos de llamadas, registro de auditoría y registros de la aplicación. Opcional.
secrets	La clave maestra y su id, el par de claves de firma JWT, el par de claves del relay y el secreto de aprovisionamiento. Las contraseñas de la base de datos y el token de configuración no se incluyen; pertenecen al host.
config	El entorno que no es secreto y los archivos de configuración que indique. Una restauración los extrae para que usted los revise, pero no los aplica.
objects	Grabaciones y buzones de voz. Opcional, y siempre es una copia completa. En instalaciones grandes use mejor el control de versiones o la replicación del bucket.

No se incluyen a propósito: las sesiones y los tokens de renovación (una restauración cierra la sesión de todos), las colas de eventos pendientes y el historial de ejecuciones de respaldo. Valkey no se respalda; contiene estado en vivo que se reconstruye al iniciar.

Un respaldo es un directorio backups/<id>/ en el destino. Un conjunto sin manifest.json está incompleto y nunca se lista ni se restaura.

Seguridad

La frase de paso (de al menos 12 caracteres) se convierte en una clave con Argon2id. Cada parte se cifra con AES-256-GCM en fragmentos autenticados, así que cualquier cambio, truncamiento o reordenamiento impide abrirla. El manifiesto indica el tamaño y el SHA-256 de cada parte, por lo que la integridad se puede verificar sin la frase de paso. La frase de paso nunca se lee desde la línea de comandos; use un archivo con permisos 0600, la entrada estándar, el entorno o una solicitud interactiva.

Hacer un respaldo

Docker Compose

El paquete incluye un servicio de una sola ejecución mpbx-ops (perfil ops, que nunca inicia up):

cd deploy/compose/prod
umask 077; openssl rand -base64 24 > backup.pass      # keep a copy OFF this host
docker compose run --rm --user "$(id -u):$(id -g)" -v "$PWD/backup.pass:/run/backup.pass:ro" \
    mpbx-ops backup --passphrase-file /run/backup.pass --prune

El destino por omisión es ./backups (MPBX_BACKUP_DIR en .env). Cópielo a un lugar que sobreviva al host. En una instalación en VM, ejecute Compose con sudo mpbx-ctl compose ....

Programado

mpbx run incluye un programador. Configure el horario y el destino una vez con la API y cada nodo revisa el reloj; uno de ellos ejecuta cada periodo. No se necesita un trabajo de cron.

PUT /api/v1/system/backups/settings
{"enabled": true, "schedule": "daily", "run_hour": 2,
 "retention": {"keep_last": 7, "keep_daily": 7, "keep_weekly": 4, "keep_monthly": 6},
 "target": {"backend": "s3", "bucket": "pbx-backups", "prefix": "mpbx",
            "region": "eu-central-1", "access_key_id": "...", "secret_access_key": "..."},
 "passphrase": "..."}

POST   /api/v1/system/backups/settings/check-target   writes, reads back and deletes a test file
POST   /api/v1/system/backups                         back up now (202 and a run to poll)
GET    /api/v1/system/backups                         the sets on the target
GET    /api/v1/system/backups/runs/{run_id}           poll a run
POST   /api/v1/system/backups/{id}/verify
DELETE /api/v1/system/backups/{id}

Estas rutas requieren system.settings:read o system.settings:write, que tienen el Propietario del sistema y el Administrador del sistema. El destino y la frase de paso solo se escriben y se guardan cifrados. Un respaldo programado fallido se reintenta después de 15 minutos, con tres intentos por periodo.

Ejemplos de destino: {"backend":"local","root":"/var/backups/mpbx"}, {"backend":"s3",...} (agregue endpoint y path_style para MinIO u otros servicios compatibles con S3) y {"backend":"gcs","bucket":"...","service_account_path":"..."}. Evite usar el bucket que guarda sus grabaciones si puede: un respaldo junto a los datos que protege no sobrevive a la pérdida de ese bucket.

Verificar

mpbx backup verify latest --target ...                         # sizes and SHA-256 of every part
mpbx backup verify latest --target ... --passphrase-file ...   # also decrypts every chunk
mpbx restore latest --target ... --passphrase-file ... --dry-run   # a restore rehearsal

Ejecute la verificación completa después de cambiar la frase de paso, el destino o la versión.

Restaurar en un host nuevo

1. Instale como de costumbre y ejecute mpbx init. Esto crea secretos nuevos y las bases de datos. No cree un administrador ni inicie mpbx todavía.
2. Inicie solo las bases de datos: docker compose up -d --wait postgres valkey clickhouse.
3. Haga que el respaldo sea legible en el host y ejecute:

docker compose run --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" -v "$PWD/backup.pass:/run/backup.pass:ro" \
    mpbx-ops restore latest --passphrase-file /run/backup.pass --sink env-file:/work/.env \
    --extract-config /work/restored-config
docker compose up -d --wait

La restauración se detiene en el primer problema. Primero verifica la frase de paso (una incorrecta no cambia nada), verifica cada parte y exige que esta versión conozca exactamente las migraciones que tiene el respaldo (MPBX-BACKUP-SCHEMA-MISMATCH: restaure con la versión que hizo el respaldo y después actualice). Se niega a sobrescribir una base de datos que ya tiene usuarios, salvo con --force; reemplaza Postgres en una sola transacción, luego ClickHouse, y escribe al final los secretos de la aplicación.

Después de la restauración, todos vuelven a iniciar sesión. La clave de recuperación de la clave maestra restaurada es la que se guardó al crear la instalación original, no la que mostró el host nuevo. Elimine cualquier línea MPBX_SETUP_TOKEN_* que mpbx init haya dejado en .env.

También es posible volver a un estado anterior de una instalación en funcionamiento con POST /api/v1/system/backups/{id}/restore (con la frase de paso del propio respaldo y el id del respaldo como confirmación), pero solo para un respaldo con la misma clave maestra. Reinicie el PBX cuando termine la ejecución.

Límites

• Las tablas de ClickHouse son consistentes individualmente, no entre tablas.
• Los respaldos de objetos son copias completas; todavía no hay modo incremental.
• Un respaldo solo se restaura sobre la misma versión de esquema.
• Solo se ejecuta un respaldo o una restauración a la vez por instalación.
• Las restauraciones de prueba automáticas y periódicas están planeadas, no implementadas.