Como fazer backup e restaurar um banco de dados PostgreSQL do Matrix Synapse

Uma recuperação confiável do Synapse começa com um dump do PostgreSQL legível, um banco de dados de destino limpo e os arquivos correspondentes no servidor de origem. Para uma instalação típica com um único banco de dados, o próprio guia de backup do Synapse recomenda o formato de dump personalizado do PostgreSQL e exclui o conteúdo de `/etc/ e2e_one_time_keys_jsonsynapse/`. Restaure em um banco de dados vazio recém-criado; não sobreponha um dump a tabelas deixadas por uma instalação anterior. Em seguida, confirme se o Synapse inicia com o banco de dados restaurado e se a mídia local e as chaves de assinatura estão presentes.

Este guia passo a passo pressupõe um host Linux, um banco de dados PostgreSQL chamado <nome_do_banco_de_dados> synapsee uma função de banco de dados chamada < synapse_usernome_da_função_de_banco_de_dados>. Substitua o banco de dados, a função, o caminho de backup, o nome do serviço e os caminhos de configuração usados ​​em sua implantação. Implantações do Docker Compose, Kubernetes, PostgreSQL gerenciado e Synapse com vários bancos de dados exigem comandos equivalentes para seus respectivos ambientes.

O que um despejo de banco de dados protege — e o que ele não protege.

pg_dumpO comando captura um banco de dados PostgreSQL em um snapshot consistente, permitindo que o PostgreSQL e o Synapse permaneçam online durante a execução do dump. Um arquivo de formato personalizado ( -Fc) pode ser inspecionado e restaurado com pg_restore. O guia do Synapse recomenda especificamente a exclusão de dados de tabelas com chaves de uso único: restaurar chaves antigas pode fazer com que os clientes recebam chaves novamente e causar erros de descriptografia de mensagens. A definição da tabela ainda pode aparecer no arquivo; ao verificar a lista de arquivos, procure por entradas de dados de tabela em vez de presumir que uma tabela listada contenha linhas.

Um simples dump do banco de dados não constitui um backup completo do servidor doméstico. É importante também manter homeserver.yamlquaisquer arquivos referenciados por ele, a chave de assinatura do servidor e o diretório de armazenamento de mídia. O guia de backup do Synapse considera as mídias carregadas localmente como importantes, pois o servidor doméstico pode conter a única cópia. Se sua configuração utiliza mais de um banco de dados, planeje um dump para cada banco de dados usado pelo Synapse.

Antes de começar

• Confirme o nome do banco de dados configurado, o usuário, o host, a porta e se o Synapse usa um ou vários bancos de dados.
• Verifique se os utilitários de cliente PostgreSQL pg_dump, como `postgresql-client` pg_restore, ` createdbpostgresql-client-lib` e `postgresql-client-cli`, psqlestão instalados e são compatíveis com o seu servidor PostgreSQL.
• Escolha um destino de backup protegido com espaço livre suficiente. Os arquivos de despejo de memória podem conter mensagens privadas e dados de contas; restrinja o acesso e criptografe os backups em repouso e em trânsito.
• Registre o diretório de configuração do Synapse, o caminho da chave de assinatura e media_store_pathfaça backup dos segredos sem expô-los no histórico do shell, no chat ou nos logs.
• Decida como você testará a recuperação. Um teste de restauração em um host isolado ou em um banco de dados de teste é uma evidência mais forte do que apenas um comando de despejo bem-sucedido.

Crie e verifique o backup do PostgreSQL.

1. Confirme o banco de dados e a função de destino.

Em um servidor PostgreSQL autogerenciado, conecte-se como administrador do PostgreSQL e inspecione a lista de bancos de dados e seus relacionamentos. Não confie em um nome fictício copiado de uma configuração de exemplo. Se o seu servidor doméstico usa um banco de dados remoto ou gerenciado, utilize o método de conexão aprovado e verifique se a conta de despejo possui o acesso de leitura necessário.

2. Criar um dump em formato personalizado

Crie um diretório que somente a conta de backup ou os administradores possam ler. O exemplo abaixo é executado pg_dumpcomo a conta local do sistema operacional PostgreSQL e grava em um caminho protegido. Altere o caminho para um que exista e seja gravável em sua configuração.

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

Se o seu banco de dados for remoto, forneça as configurações de conexão usando o método aprovado em seu ambiente, como um .pgpassarquivo protegido ou variáveis ​​de ambiente do libpq. Evite inserir a senha diretamente na linha de comando. Mantenha a opção de exclusão, a menos que você tenha um motivo específico e documentado para lidar com a tabela de chaves de uso único de forma diferente.

3. Verifique o arquivo e preserve um checksum.

Confirme se o arquivo de despejo existe, se tem um tamanho diferente de zero e se pode ser lido como um arquivo PostgreSQL. Uma listagem bem-sucedida é uma primeira verificação útil, mas não comprova que a restauração será concluída ou que o servidor doméstico completo poderá atender aos usuários.

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

Armazene o checksum ao lado do registro de backup e, em seguida, copie o dump para um sistema separado ou serviço de backup. Recalcule o checksum após a cópia e compare os valores. Para objetivos de recuperação em produção, agende backups regulares, mantenha várias gerações, criptografe-as e execute simulações de restauração periodicamente.

Restaurar para um banco de dados limpo

4. Pare o Synapse e prepare um destino vazio.

Para uma restauração, pare o Synapse primeiro para que ele não possa se reconectar enquanto o banco de dados estiver sendo substituído ou testado. O nome do serviço abaixo é comum em algumas instalações de pacotes, mas pode variar; usuários do Docker devem parar o serviço Synapse por meio de seu projeto Compose, e implantações orquestradas devem usar seu procedimento de manutenção normal. O próprio PostgreSQL não precisa ser parado.

Use um banco de dados novo e vazio para a restauração. Não restaure sobre um banco de dados Synapse existente ou um que já contenha tabelas. Se precisar preservar o banco de dados atual para reversão, deixe-o intacto e restaure com um nome de banco de dados temporário. Em seguida, valide os dados antes de alterar a configuração do Synapse.

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

O proprietário e a localidade do banco de dados devem corresponder aos requisitos da sua configuração do Synapse. Se o nome de destino já existir, pare e confirme qual banco de dados você pretende usar; não presuma que excluí-lo seja seguro. Crie primeiro todas as funções necessárias do PostgreSQL. Um banco de dados único pg_dumpnão inclui funções para todo o cluster, portanto, um administrador que migra para um novo cluster PostgreSQL também pode precisar de um backup de variáveis ​​globais protegido separadamente, feito com [comando/método específico] pg_dumpall --globals-only.

5. Restaurar o arquivo e gerenciar chaves de uso único.

Carregue o arquivo personalizado nesse destino vazio. A opção de erro explícito faz com que a restauração seja interrompida ao encontrar um erro, em vez de continuar e deixar um resultado incompleto que pode passar despercebido.

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

Se o seu backup não excluiu a tabela e2e_one_time_keys_json, conecte-se ao banco de dados restaurado e trunque essa tabela antes de iniciar o Synapse. Essa é a medida de segurança de recuperação documentada pelo Synapse para backups que incluem essas linhas. Não execute o comando em um banco de dados ativo sem necessidade: ele remove todas as linhas dessa tabela.

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

Se você utilizou a exclusão recomendada, a restauração não conterá linhas antigas de chave única e esta etapa de truncamento será desnecessária. Uma entrada de tabela pg_restore --listpode representar uma definição de tabela sem seus dados. Verifique as TABLE DATAentradas ao revisar o conteúdo do arquivo; o registro operacional mais seguro é o comando de despejo exato utilizado.

Restaure o Synapse e verifique se está recuperado.

6. Restaure os arquivos complementares e inicie o Synapse.

Antes de reiniciar, certifique-se de que a configuração restaurada aponte para o banco de dados correto e que a chave de assinatura e o armazenamento de mídia esperados estejam disponíveis para o processo do Synapse. Se você restaurou com um nome de banco de dados temporário, atualize as configurações do banco de dados com segurança, valide o arquivo e use seu processo de implantação normal para ativá-lo. Mantenha o banco de dados antigo e a configuração anterior disponíveis até que a nova instância passe nas verificações.

Inicie o serviço usando o comando apropriado para sua implementação. Em um host systemd, verifique o status do serviço e os logs recentes. Em contêineres, verifique a integridade e os logs do contêiner. Um processo em execução é um sinal inicial, não uma prova de que os usuários podem ler salas, enviar mensagens ou recuperar anexos.

7. Testar as funções em que os usuários dependem.

• Confirme se o Synapse inicia sem erros de migração de banco de dados, permissão, idioma ou conexão.
• Faça login com uma conta de teste e leia as salas existentes; envie uma mensagem de teste se o seu plano de manutenção permitir.
• Verifique o comportamento da federação e do serviço de aplicativos se esses recursos fizerem parte da sua implementação.
• Abra um anexo ou avatar carregado localmente que você saiba que está salvo para testar se o armazenamento de mídia corresponde ao banco de dados restaurado.
• Verifique os logs do Synapse e do PostgreSQL em busca de erros recorrentes após a inicialização, e não apenas após a primeira verificação de integridade bem-sucedida.

Uma restauração pode ser tecnicamente bem-sucedida mesmo que faltem arquivos de mídia, configurações referenciadas ou funções. Se os usuários virem anexos ausentes, verifique o armazenamento de mídia configurado e restaure o backup de mídia local correspondente. Se o Synapse não conseguir se conectar, compare o proprietário do banco de dados restaurado, as credenciais, o host, o nome do banco de dados, a localidade e o arquivo de configuração ativo.

Sinais comuns de falha e quando alterar o método

Os dumps lógicos são portáteis e simples para muitas implementações de pequeno e médio porte, mas podem levar tempo para serem restaurados à medida que o banco de dados cresce. Para um serviço de grande porte ou de alta disponibilidade, consulte a documentação de backup atual do PostgreSQL e planeje um backup físico testado ou um projeto de recuperação pontual. Mantenha um dump lógico independente se ele atender a uma necessidade específica de portabilidade ou auditoria. Nenhum dos métodos protege arquivos armazenados fora do PostgreSQL, a menos que esses arquivos sejam copiados separadamente.

Lista de verificação para recuperação

• O arquivo de despejo pode ser lido pg_restore --liste seu checksum corresponde à cópia fora do host.
• A restauração foi realizada em um banco de dados novo e vazio, com a codificação, localidade, proprietário e funções esperados.
• Linhas com chaves de uso único foram excluídas ou a tabela foi truncada antes da reinicialização do Synapse.
• Os arquivos de configuração, a chave de assinatura e a mídia local necessária foram restaurados a partir de backups compatíveis.
• Os registros do Synapse estão suficientemente limpos para o serviço, e as verificações em nível de cliente são aprovadas para salas e mídia.
• Um exercício de restauração confirmou as etapas de recuperação documentadas e mediu o tempo real de restauração.

Referências oficiais

• Guia de backup do Synapse — dicas específicas para cada banco de dados, gerenciamento de chaves de uso único, configuração, chaves de assinatura e armazenamento de mídia.
• Synapse: Usando PostgreSQL — detalhes de configuração e instalação do banco de dados.
• PostgreSQL: pg_dump , pg_restore e backup e restauração do PostgreSQL — opções de arquivamento e estratégias de backup mais abrangentes.

Documentação verificada em 6 de outubro de 2026. Os nomes dos comandos e o gerenciamento de serviços variam de acordo com o sistema operacional, a imagem do contêiner, a versão do PostgreSQL e a implantação do Synapse. Confirme as instruções consultando a documentação para as versões e o método de empacotamento que você está utilizando.