Cómo realizar copias de seguridad y restaurar una base de datos PostgreSQL de Matrix Synapse

Una recuperación confiable de Synapse comienza con un volcado de PostgreSQL legible, una base de datos de destino limpia y los archivos del servidor principal correspondientes. Para una instalación típica de una sola base de datos, la guía de copia de seguridad de Synapse recomienda el formato de volcado personalizado de PostgreSQL y excluye el contenido de e2e_one_time_keys_json. Restaura en una base de datos vacía recién creada; no sobrescribas las tablas dejadas por una instalación anterior con un volcado. Luego, confirma que Synapse se inicie con la base de datos restaurada y que los medios locales y las claves de firma estén presentes.

Este tutorial asume un host Linux, una base de datos PostgreSQL llamada synapsey un rol de base de datos llamado synapse_user. Sustituya la base de datos, el rol, la ruta de copia de seguridad, el nombre del servicio y las rutas de configuración que utilice su implementación. Las implementaciones de Docker Compose, Kubernetes, PostgreSQL administrado y Synapse con múltiples bases de datos requieren comandos equivalentes para su entorno.

Qué protege (y qué no protege) una copia de seguridad de la base de datos.

pg_dumpcaptura una base de datos PostgreSQL en una instantánea consistente, por lo que PostgreSQL y Synapse pueden permanecer en línea mientras se ejecuta el volcado. Un archivo de formato personalizado ( -Fc) se puede inspeccionar y restaurar con pg_restore. La guía de Synapse recomienda específicamente excluir los datos de tablas de clave de un solo uso: restaurar claves usadas antiguas puede hacer que los clientes reciban claves nuevamente y puede provocar errores de descifrado de mensajes. La definición de la tabla aún puede aparecer en el archivo; al revisar la lista de archivos, busque entradas de datos de tabla en lugar de asumir que una tabla listada contiene filas.

Una copia de seguridad de la base de datos por sí sola no es una copia de seguridad completa del servidor principal. Conserve también homeserver.yamllos archivos a los que hace referencia, la clave de firma del servidor y el directorio de almacenamiento de medios. La guía de copias de seguridad de Synapse considera importantes los medios cargados localmente, ya que el servidor principal podría contener la única copia. Si su configuración utiliza más de una entrada de base de datos, planifique una copia de seguridad para cada base de datos que utilice Synapse.

Antes de comenzar

• Confirme el nombre de la base de datos configurada, el usuario, el host, el puerto y si Synapse utiliza una o varias bases de datos.
• Compruebe que las utilidades de cliente de PostgreSQL pg_dump, pg_restore, createdb, y psqlestén instaladas y sean compatibles con su servidor PostgreSQL.
• Elija un destino de copia de seguridad protegido con suficiente espacio libre. Los volcados pueden contener mensajes privados y datos de cuenta; restrinja el acceso y cifre las copias de seguridad tanto en reposo como en tránsito.
• Registre el directorio de configuración de Synapse, la ruta de la clave de firma y media_store_path. Realice copias de seguridad de los secretos sin exponerlos en el historial de la consola, el chat o los registros.
• Decida cómo probará la recuperación. Una restauración de prueba en un host aislado o en una base de datos de prueba proporciona una evidencia más sólida que un comando de volcado exitoso por sí solo.

Cree y verifique la copia de seguridad de PostgreSQL.

1. Confirme la base de datos de destino y el rol.

En un servidor PostgreSQL autogestionado, conéctese como administrador de PostgreSQL e inspeccione la lista de bases de datos y sus relaciones. No utilice un nombre genérico copiado de una configuración de ejemplo. Si su servidor utiliza una base de datos remota o gestionada, use su método de conexión aprobado y verifique que la cuenta de volcado tenga los permisos de lectura necesarios.

2. Crea un volcado de formato personalizado.

Cree un directorio al que solo puedan acceder la cuenta de respaldo o los administradores. El ejemplo que se muestra a continuación se ejecuta pg_dumpcon la cuenta del sistema operativo local de PostgreSQL y escribe en una ruta protegida. Modifique la ruta para que exista y tenga permisos de escritura en su configuración.

sudo -u postgres pg_dump -Fc \
  --exclude-table-data e2e_one_time_keys_json \
  synapse -f /var/backups/synapse/synapse.dump

Si su base de datos es remota, proporcione la configuración de conexión mediante el método aprobado en su entorno, como un .pgpassarchivo protegido o variables de entorno de libpq. Evite introducir la contraseña directamente en la línea de comandos. Mantenga la opción de exclusión a menos que tenga una razón documentada y justificada para gestionar la tabla de claves de un solo uso de forma diferente.

3. Verifique el archivo y guarde una suma de comprobación.

Confirme que el archivo de volcado existe, que su contenido es distinto de cero y que se puede leer como un archivo PostgreSQL. Una lista exitosa es una primera comprobación útil, pero no garantiza que la restauración se complete ni que el servidor principal pueda atender a los usuarios.

sudo -u postgres pg_restore --list /var/backups/synapse/synapse.dump
sha256sum /var/backups/synapse/synapse.dump

Almacene la suma de verificación junto al registro de copia de seguridad y, a continuación, copie el volcado a un sistema o servicio de copia de seguridad independiente. Recalcule la suma de verificación después de la copia y compare los valores. Para la recuperación en producción, programe copias de seguridad periódicas, conserve varias generaciones, cifrelas y realice simulacros de restauración periódicos.

Restaurar en una base de datos limpia

4. Detén Synapse y prepara un destino vacío.

Para restaurar la base de datos, detenga primero Synapse para evitar que se reconecte mientras se reemplaza o prueba. El nombre del servicio que se muestra a continuación es común en algunas instalaciones de paquetes, pero puede variar. Los usuarios de Docker deben detener el servicio Synapse a través de su proyecto Compose, y quienes utilicen implementaciones orquestadas deben seguir su procedimiento de mantenimiento habitual. No es necesario detener PostgreSQL.

Utilice una base de datos nueva y vacía para la restauración. No restaure sobre una base de datos Synapse existente ni sobre una que ya contenga tablas. Si necesita conservar la base de datos actual para la reversión, déjela intacta y restáurela con un nombre de base de datos temporal; luego, valide la configuración antes de modificarla.

sudo -u postgres createdb \
  --encoding=UTF8 --locale=C --template=template0 \
  --owner=synapse_user synapse

El propietario de la base de datos y la configuración regional deben coincidir con los requisitos de su configuración de Synapse. Si el nombre de destino ya existe, deténgase y confirme qué base de datos pretende usar; no asuma que eliminarla es seguro. Cree primero los roles de PostgreSQL necesarios. Una base de datos única pg_dumpno incluye roles de clúster, por lo que un administrador que se traslade a un nuevo clúster de PostgreSQL también puede necesitar una copia de seguridad de variables globales protegida por separado realizada con pg_dumpall --globals-only.

5. Restaurar el archivo y gestionar las claves de un solo uso.

Cargue el archivo personalizado en ese destino vacío. La opción de error explícito hace que la restauración se detenga cuando encuentra un error, en lugar de continuar y dejar un resultado incompleto que es fácil pasar por alto.

sudo -u postgres pg_restore --exit-on-error \
  --dbname=synapse /var/backups/synapse/synapse.dump

Si la copia de seguridad no excluyó e2e_one_time_keys_jsonla tabla, conéctese a la base de datos restaurada y trunque dicha tabla antes de iniciar Synapse. Esta es la medida de seguridad de recuperación documentada por Synapse para las copias de seguridad que incluyen esas filas. No ejecute el comando en una base de datos activa sin precaución: eliminará todas las filas de esa tabla.

sudo -u postgres psql -d synapse \
  -c 'TRUNCATE e2e_one_time_keys_json;'

Si utilizó la exclusión recomendada, la restauración no contiene filas antiguas de clave única y este paso de truncamiento es innecesario. Una entrada de tabla pg_restore --listpuede representar la definición de una tabla sin sus datos. Verifique las TABLE DATAentradas al revisar el contenido del archivo; el registro operativo más seguro es el comando de volcado exacto utilizado.

Reinstala Synapse y verifica la recuperación.

6. Restaure los archivos complementarios e inicie Synapse.

Antes de reiniciar, asegúrese de que la configuración restaurada apunte a la base de datos correcta y de que la clave de firma y el almacén de medios esperados estén disponibles para el proceso Synapse. Si restauró con un nombre de base de datos temporal, actualice la configuración de la base de datos de forma segura, valide el archivo y utilice su proceso de implementación habitual para activarla. Mantenga la base de datos antigua y la configuración anterior disponibles hasta que la nueva instancia supere las comprobaciones.

Inicie el servicio con el comando adecuado para su implementación. En un host systemd, revise el estado del servicio y los registros recientes. En contenedores, revise el estado y los registros del contenedor. Un proceso en ejecución es una señal inicial, pero no una prueba de que los usuarios puedan leer salas, enviar mensajes o recuperar archivos adjuntos.

7. Prueba las funciones de las que dependen los usuarios.

• Confirme que Synapse se inicia sin errores de migración de base de datos, permisos, configuración regional o conexión.
• Inicia sesión con una cuenta de prueba y lee las salas existentes; envía un mensaje de prueba si tu plan de mantenimiento lo permite.
• Compruebe el comportamiento de la federación y del servicio de aplicaciones si esas características forman parte de su implementación.
• Abra un archivo adjunto o avatar que se haya subido localmente y del que se tenga constancia para comprobar que el almacén de medios coincide con la base de datos restaurada.
• Compruebe los registros de Synapse y de PostgreSQL en busca de errores repetidos después del inicio, no solo después de la primera comprobación de estado satisfactoria.

Una restauración puede ser técnicamente exitosa aunque falten archivos multimedia, configuraciones de referencia o roles. Si los usuarios observan que faltan archivos adjuntos, verifique el almacén de medios configurado y restaure la copia de seguridad local correspondiente. Si Synapse no puede conectarse, compare el propietario de la base de datos restaurada, las credenciales, el host, el nombre de la base de datos, la configuración regional y el archivo de configuración activo.

Señales de fallo comunes y cuándo cambiar de método.

Las copias de seguridad lógicas son portátiles y sencillas para muchas implementaciones pequeñas y medianas, pero su restauración puede llevar tiempo a medida que la base de datos crece. Para un servicio grande o de alta disponibilidad, consulte la documentación de copias de seguridad de PostgreSQL y planifique una copia de seguridad física probada o un diseño de recuperación a un punto en el tiempo. Mantenga una copia de seguridad lógica independiente si cumple con una necesidad de portabilidad o auditoría distinta. Ninguno de los métodos protege los archivos almacenados fuera de PostgreSQL a menos que se realicen copias de seguridad por separado.

Lista de verificación de recuperación

• El volcado es legible pg_restore --listy su suma de verificación coincide con la copia fuera del host.
• La restauración se realizó en una base de datos nueva y vacía con la codificación, la configuración regional, el propietario y los roles esperados.
• Se excluyeron las filas de clave de un solo uso o se truncó la tabla antes de reiniciar Synapse.
• Los archivos de configuración, la clave de firma y los medios locales necesarios se restauraron a partir de copias de seguridad compatibles.
• Los registros de Synapse están lo suficientemente limpios para el servicio, y las comprobaciones a nivel de cliente para salas y medios se realizan correctamente.
• Un simulacro de restauración ha confirmado los pasos de recuperación documentados y ha medido el tiempo real de restauración.

Referencias oficiales

• Guía de copia de seguridad de Synapse : consejos específicos para la base de datos, gestión de claves de un solo uso, configuración, firma de claves y almacenamiento de medios.
• Synapse: Uso de PostgreSQL : detalles de configuración y configuración de la base de datos.
• PostgreSQL: pg_dump , pg_restore y copia de seguridad y restauración de PostgreSQL : opciones de archivo y estrategias de copia de seguridad más amplias.

Documentación revisada el 6 de octubre de 2026. Los nombres de los comandos y la administración de servicios varían según el sistema operativo, la imagen del contenedor, la versión de PostgreSQL y la implementación de Synapse. Confirme las instrucciones con la documentación correspondiente a las versiones y el método de empaquetado que utilice.