PostgreSQL 덤프를 사용하여 Matrix Synapse를 안전하게 복원하세요
pg_dump를 사용하여 Synapse를 백업하고, 서명 키와 미디어를 보호하고, 오래된 일회용 키를 재사용하지 않고 깨끗한 PostgreSQL 데이터베이스에 복원하세요.
Synapse 데이터베이스 백업 시 PostgreSQL의 사용자 지정 덤프 형식을 사용하고, 일회용 키 테이블은 제외한 후, 새로 생성된 빈 데이터베이스에 복원하십시오. 데이터베이스 덤프만으로는 완전한 홈서버 백업이 아닙니다. Synapse의 구성, 서명 키 및 로컬 미디어도 함께 백업해야 합니다. 2026년 10월 10일 기준 Synapse의 공식 백업 지침에서는 기존 테이블에 덮어쓰기 복원이나 이전 종단 간 암호화 일회용 키 복원을 절대 권장하지 않습니다.
검증 완료: pg_dump PostgreSQL이 온라인 상태를 유지하는 동안 일관된 스냅샷이 생성됩니다. 덤프 실행 중 Synapse를 중지할 필요가 없습니다. 데이터베이스 전용 덤프에는 Synapse의 미디어 저장소 파일, homeserver.yaml참조된 구성 파일 또는 서버 서명 키가 포함되지 않습니다. 이러한 파일은 별도의 보호된 백업 세트에 보관하십시오. Synapse는 로컬에 업로드된 콘텐츠와 동적 썸네일이 비활성화된 경우 로컬 썸네일을 보존해야 할 데이터로 식별합니다. 원격 미디어 및 URL 미리보기 캐시는 일반적으로 가져오거나 재구축할 수 있습니다.
조치: 복구 계획을 수립하기 전에 활성 데이터베이스 이름, PostgreSQL 역할, Synapse 구성 디렉터리, 서명 키 경로 및 미디어 저장소 경로를 확인하십시오. 서버에 구성된 경로를 사용하세요. 이러한 경로는 패키지, 컨테이너 및 배포 환경에 따라 다를 수 있습니다.
흔히 잘못 알려진 사실: SQL 덤프가 성공했다고 해서 홈서버 전체를 복구할 수 있다는 보장은 없습니다. 조치 사항: 데이터베이스, 구성 및 서명 키, 그리고 필요한 로컬 저장 매체를 백업하고, 주기적으로 이들을 함께 복원하는 테스트를 진행하십시오.
아래 명령어는 PostgreSQL 명령줄 도구가 설치되어 있고, 데이터베이스 이름이 인 Linux 호스트이며 synapse, postgres운영 체제 계정으로 PostgreSQL 명령어를 실행할 수 있는 권한이 있다고 가정합니다. 데이터베이스 이름과 경로는 사용 환경에 맞게 변경하십시오. 덤프 파일은 충분한 여유 공간이 있는 안전한 저장소에 저장하십시오. 개인 메시지 및 계정 데이터가 포함될 수 있습니다.
Synapse에서 이전 백업에서 재생해서는 안 된다고 표시된 테이블의 내용을 제외하고 덤프를 생성합니다.
sudo -u postgres pg_dump -Fc --exclude-table-data=e2e_one_time_keys_json synapse > /secure-backups/synapse.dump-FcPostgreSQL의 사용자 지정 아카이브 형식을 선택하는데, 이 형식은 일반 SQL에 적합하며 pg_restore일반적으로 일반 SQL보다 크기가 작습니다. 이 제외는 테이블 데이터에만 영향을 미치며 테이블 정의 자체는 제거하지 않습니다.
파일이 존재하고 비어 있지 않은지 확인한 다음, 아카이브의 목차를 나열하십시오.
ls -lh /secure-backups/synapse.dump
sudo -u postgres pg_restore --list /secure-backups/synapse.dump목록은 PostgreSQL이 아카이브 구조를 읽을 수 있음을 확인시켜 줄 뿐, 모든 행을 복원할 수 있거나 다른 백업 파일이 완전하다는 것을 증명하는 것은 아닙니다. 더 강력한 검사를 위해서는 덤프 파일을 별도의 백업 저장소로 복사한 후 전송 후 체크섬을 확인하십시오.
흔히 잘못 알려진 사실: 스냅샷을 찍을 때마다 Synapse를 중지해야 한다는 것입니다 pg_dump. Synapse 공식 페이지에 따르면 일반 pg_dump스냅샷은 Synapse나 PostgreSQL을 중지하지 않아도 일관성을 유지합니다. 조치: 논리적 백업을 수행하는 동안에는 서비스를 온라인 상태로 유지하고, 전체 복원을 위한 유지 관리 기간을 계획하십시오.
복원은 교체 작업입니다. 먼저 Synapse와 모든 Synapse 워커 프로세스를 중지하여 복구가 진행되는 동안 대상에 연결하거나 쓰기 작업을 수행하지 못하도록 하십시오. 데이터베이스 변경 명령을 실행하기 전에 대상 데이터베이스 이름과 덤프 형식을 확인하십시오.
Synapse 구성에서 사용하는 소유자로 UTF-8 인코딩을 적용하여 새 데이터베이스를 생성합니다. 다음은 예시 역할을 사용합니다 synapse_user.
sudo -u postgres createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse_user synapse데이터베이스 이름이 이미 존재하는 경우, 무턱대고 복원하지 마십시오. 복구 절차에 따라 기존 데이터베이스의 내용을 확인하고 별도의 복구 가능한 백업이 있는지 확인한 후에만 기존 데이터베이스를 보존하거나 삭제하십시오.
아카이브를 빈 데이터베이스에 로드합니다.
sudo -u postgres pg_restore --dbname=synapse /secure-backups/synapse.dump명령의 종료 상태와 PostgreSQL 출력을 확인하십시오. Synapse를 시작하기 전에 오류를 조사하십시오. --clean기존 테이블이 있는 운영 데이터베이스를 덮어쓰는 바로 가기 옵션과 같은 것은 사용하지 마십시오. Synapse는 기존 테이블로 인해 오류나 미묘한 불일치가 발생할 수 있다고 경고합니다.
덤프 파일에서 일회용 키 데이터가 제외되지 않은 경우, 시작하기 전에 해당 데이터를 삭제하십시오. 복원된 데이터베이스에 연결하고 다음 명령을 실행하십시오.
sudo -u postgres psql --dbname=synapse -c 'TRUNCATE e2e_one_time_keys_json;'Synapse는 이전 일회용 키를 복원하면 클라이언트가 이미 사용한 키를 재사용하게 되어 메시지 복호화에 문제가 발생할 수 있기 때문에 이 예외 사항을 문서화합니다. 키를 삭제하면 클라이언트는 새 키를 업로드해야 합니다. 권장되는 제외 절차를 따랐다면 테이블에 복원된 행이 없으므로 이 추가적인 잘라내기 작업은 불필요합니다.
흔히 잘못 알려진 사실: 모든 데이터베이스 테이블을 한꺼번에 안전하게 롤백할 수 있다. 조치:e2e_one_time_keys_json 백업 시 해당 테이블을 제외 하거나 복원 후 테이블을 잘라내십시오. 단, Synapse 프로세스가 시작되기 전에 이 작업을 수행해야 합니다.
가능한 경우 동일한 복구 지점에서 일치하는 구성, 서명 키 및 필요한 로컬 미디어 파일을 복원하십시오. 원래 서명 키는 보관하십시오. Synapse는 이벤트 및 페더레이션 요청에 서명하는 데 이 키를 사용합니다. 서명 키를 교체해야 하는 경우 Synapse의 서명 키 지침을 따르고 이전 공개 키를 이전 서명 키로 구성하십시오. 시점이 크게 다른 데이터베이스, 미디어 및 구성은 동일한 상태를 나타내지 않을 수 있으므로 복구 계획의 일관성을 확인하십시오.
복구 및 일회용 키 처리가 완료된 후에만 Synapse와 관련 워커 프로세스를 시작하십시오. 서비스 로그를 검토하여 데이터베이스 연결 실패, 스키마 누락 또는 권한 오류, 백그라운드 업데이트 문제 등을 확인하십시오. 그런 다음 테스트 계정으로 로그인하여 알려진 회의실의 최근 사용 기록을 확인하고 로컬에 업로드된 첨부 파일을 열어보십시오. 배포 환경이 페더레이션 및 애플리케이션 서비스에 의존하는 경우 해당 서비스도 확인하십시오. 이러한 검사는 실제 작동 여부를 확인하는 간단한 테스트이며, 모든 회의실이나 미디어 객체가 복구되었음을 보장하는 것은 아닙니다.
배포 환경에 따라 명령 경로, 서비스 이름, 데이터베이스 역할, 컨테이너 오케스트레이션 및 백업 보존 기간이 달라집니다. 이 절차는 PostgreSQL의 논리적 덤프 및 복원에 대한 내용이며, 특정 시점 복구, PostgreSQL 클러스터 전체 역할 또는 고가용성 장애 조치 설계는 다루지 않습니다. 운영 시스템의 경우 Synapse 백업 문서 와 PostgreSQL 백업 및 복원 문서를 참조하여 사용 중인 PostgreSQL 버전 및 복구 목표에 맞는 방법을 확인하십시오. 복원 테스트 날짜, 소프트웨어 버전 및 결과를 기록하십시오. 테스트되지 않은 아카이브를 복구 가능한 백업으로 간주하지 마십시오.
pg_dump를 사용하여 Synapse를 백업하고, 서명 키와 미디어를 보호하고, 오래된 일회용 키를 재사용하지 않고 깨끗한 PostgreSQL 데이터베이스에 복원하세요.
Mjölnir를 전용 Matrix 계정, 암호화된 관리실, Docker Compose, 정책 목록 및 권한 검사와 함께 설정하십시오.
기존 프록시를 건너뛰고 Synapse에 내장된 슬라이딩 동기화 기능을 구성하십시오. 클라이언트 검색을 확인한 다음 호환되는 전화기에서 회의실 목록 로딩 및 재연결 동작을 측정하십시오.
Element Web을 정적 사이트로 배포하고, Matrix 홈서버를 가리키도록 설정하고, HTTPS를 추가하고, Nginx를 구성하여 오래된 파일 없이 업데이트를 제공하도록 하십시오.
64비트 라즈베리 파이 4에 Conduit를 설치하여 영구 데이터 저장, HTTPS 연동, 보호된 회원가입, 그리고 홈서버 작동 여부 확인 기능을 구성합니다.
Element 또는 Matrix API를 사용하여 권한, Synapse 명명 및 연동을 확인하고 Matrix 회의실에 도메인에서 쉽게 공유할 수 있는 주소를 부여하세요.
coturn과 Synapse를 일치하는 TURN 자격 증명으로 구성하고, 필요한 릴레이 포트를 열고, Matrix 클라이언트가 릴레이 후보를 가져올 수 있는지 확인합니다.
Docker Compose, PostgreSQL, 비공개 설정 파일, 그리고 HTTPS를 통해 노출하기 전에 필요한 검사 기능을 사용하여 Synapse 홈 서버를 영구적으로 설정합니다.
Element 웹 배포에 브랜드 이름, 사용자 지정 색상 및 로그인 자산을 설정하는 동시에 Element 브랜드로 유지되는 부분을 파악하세요.
Synapse가 프로세스별 파일 열기 제한에 도달했는지 진단하고, 해당 서비스 또는 워커에 대한 systemd 드롭인을 설정하고, 실제 제한을 확인합니다.