Matrix Synapse PostgreSQL 데이터베이스 백업 및 복원 방법

안정적인 Synapse 복구는 읽을 수 있는 PostgreSQL 덤프 파일, 깨끗한 대상 데이터베이스, 그리고 해당 홈서버 파일이 필요합니다. 일반적인 단일 데이터베이스 설치의 경우, Synapse 자체 백업 가이드에서는 PostgreSQL의 사용자 지정 덤프 형식을 권장하며, 해당 파일의 내용은 제외합니다 e2e_one_time_keys_json. 새롭게 생성된 빈 데이터베이스에 복원하십시오. 이전 설치에서 남은 테이블 위에 덤프 파일을 덮어쓰지 마십시오. 복원된 데이터베이스에서 Synapse가 정상적으로 시작되는지, 그리고 로컬 미디어와 서명 키가 있는지 확인하십시오.

이 가이드에서는 Linux 호스트, `postgreSQL`이라는 이름의 데이터베이스 synapse, 그리고 `database role`이라는 이름의 데이터베이스 역할을 가정합니다 synapse_user. 사용 환경에 맞는 데이터베이스, 역할, 백업 경로, 서비스 이름 및 구성 경로로 바꿔주세요. Docker Compose, Kubernetes, 관리형 PostgreSQL 및 다중 데이터베이스 Synapse 배포 환경에서는 각 환경에 맞는 명령어를 사용해야 합니다.

데이터베이스 덤프가 보호하는 것과 보호하지 못하는 것

pg_dumpPostgreSQL 데이터베이스 하나를 일관된 스냅샷으로 캡처하므로 덤프가 실행되는 동안 PostgreSQL과 Synapse는 온라인 상태를 유지할 수 있습니다. 사용자 지정 형식 아카이브( -Fc)는 를 사용하여 검사하고 복원할 수 있습니다 pg_restore. Synapse 가이드에서는 일회용 키 테이블 데이터를 제외할 것을 특별히 권장합니다. 이전에 사용했던 키를 복원하면 클라이언트가 키를 다시 수신하게 되어 메시지 복호화 오류가 발생할 수 있습니다. 테이블 정의는 아카이브에 여전히 나타날 수 있습니다. 아카이브 목록을 확인할 때는 나열된 테이블에 행이 포함되어 있다고 가정하기보다는 테이블 데이터 항목을 찾으십시오.

데이터베이스 덤프만으로는 홈서버 백업이 완벽하지 않습니다. 데이터베이스 덤프 homeserver.yaml와 해당 덤프에서 참조하는 모든 파일, 서버 서명 키, 미디어 저장소 디렉터리도 함께 백업해야 합니다. Synapse 백업 가이드에서는 홈서버에 유일한 사본이 저장될 수 있으므로 로컬에 업로드된 미디어를 중요하게 여긴다고 명시하고 있습니다. 구성에서 데이터베이스 항목이 두 개 이상 사용되는 경우, Synapse에서 사용하는 모든 데이터베이스에 대해 덤프를 생성해야 합니다.

시작하기 전에

구성된 데이터베이스 이름, 사용자, 호스트, 포트 및 Synapse에서 데이터베이스를 하나만 사용하는지 여러 개 사용하는지 확인하십시오.
PostgreSQL 클라이언트 유틸리티인 `PostgreSQL` pg_dump, `PostgreSQL` pg_restore, `PostgreSQL`이 설치되어 createdb있고 psqlPostgreSQL 서버와 호환되는지 확인하십시오.
충분한 여유 공간이 있는 안전한 백업 위치를 선택하십시오. 덤프 파일에는 개인 메시지와 계정 데이터가 포함될 수 있으므로 접근을 제한하고 저장 중 및 전송 중인 백업 파일을 암호화하십시오.
Synapse 구성 디렉터리, 서명 키 경로 및 기타 정보를 기록합니다 media_store_path. 셸 기록, 채팅 또는 로그에 비밀 정보를 노출하지 않고 백업합니다.
복구 테스트 방법을 결정하세요. 격리된 호스트 또는 스테이징 데이터베이스에서 테스트 복원을 수행하는 것이 단순히 덤프 명령을 성공적으로 실행하는 것보다 더 강력한 증거가 될 수 있습니다.

PostgreSQL 백업을 생성하고 확인합니다.

1. 대상 데이터베이스 및 역할을 확인합니다.

자체 관리형 PostgreSQL 호스트에서는 PostgreSQL 관리자 계정으로 접속하여 데이터베이스 목록과 관계를 확인하십시오. 샘플 구성에서 복사한 가상의 이름을 사용하지 마십시오. 홈서버에서 원격 또는 관리형 데이터베이스를 사용하는 경우, 승인된 연결 방법을 사용하고 덤프 계정에 필요한 읽기 권한이 있는지 확인하십시오.

Synapse 데이터베이스 관계와 synapse_user 소유자를 나열하는 PostgreSQL 터미널 화면입니다. — 터미널에서 Synapse 관계 및 소유자를 확인하면 백업 명령이 의도한 데이터베이스를 대상으로 하는지 확인할 수 있습니다.

2. 사용자 지정 형식의 덤프 생성

백업 계정 또는 관리자만 읽을 수 있는 디렉터리를 생성하십시오. 아래 예시는 pg_dump로컬 PostgreSQL 운영 체제 계정으로 실행되어 보호된 경로에 쓰기를 수행합니다. 실제 사용 환경에 맞는 쓰기 가능한 경로로 변경하십시오.

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

데이터베이스가 원격인 경우, 보호된 파일이나 libpq 환경 변수와 같이 사용 환경에서 승인된 방법을 사용하여 연결 설정을 제공하십시오 .pgpass. 명령줄에 암호를 직접 입력하지 마십시오. 일회용 키 테이블을 다르게 처리해야 하는 명확한 이유가 문서로 입증된 경우가 아니면 제외 옵션을 유지하십시오.

터미널에서 e2e_one_time_keys_json 데이터를 제외한 사용자 지정 형식으로 pg_dump를 실행한 후 파일 목록을 표시합니다. — 백업 명령은 일회용 키 데이터를 제외하고 나중에 pg_restore를 사용하여 검사할 수 있도록 사용자 지정 형식의 아카이브를 생성합니다.

3. 아카이브를 확인하고 체크섬을 보존하십시오.

덤프 파일이 존재하고, 크기가 0이 아니며, PostgreSQL 아카이브 형식으로 읽을 수 있는지 확인하십시오. 목록 확인이 성공적으로 완료되면 복원이 완료되거나 홈서버가 사용자에게 서비스를 제공할 수 있음을 보장하는 것은 아닙니다.

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

백업 레코드 옆에 체크섬을 저장한 다음 덤프 파일을 별도의 시스템이나 백업 서비스로 복사합니다. 복사 후 체크섬을 다시 계산하고 값을 비교합니다. 운영 환경 복구를 위해서는 정기적인 백업을 예약하고, 여러 세대의 백업 파일을 보존하고, 암호화하고, 주기적인 복원 훈련을 실행해야 합니다.

깨끗한 데이터베이스로 복원

4. Synapse를 중지하고 빈 대상 위치를 준비합니다.

복원을 진행하려면 Synapse를 먼저 중지하여 데이터베이스 교체 또는 테스트 중에 Synapse가 다시 연결되지 않도록 해야 합니다. 아래 서비스 이름은 일부 패키지 설치에서 흔히 사용되지만, 실제 이름은 다를 수 있습니다. Docker 사용자는 Compose 프로젝트를 통해 Synapse 서비스를 중지해야 하며, 오케스트레이션 배포의 경우 일반적인 유지 관리 절차를 따르십시오. PostgreSQL 자체는 중지할 필요가 없습니다.

데이터베이스 복원 전에 Synapse 서비스가 중지되었음을 보여주는 Linux 터미널 화면입니다. — 데이터베이스를 복원된 복사본으로 전환하기 전에 Synapse 애플리케이션을 중지하십시오. 호스트에 구성된 서비스 이름을 사용하십시오.

복원 시에는 새롭고 비어 있는 데이터베이스를 사용하십시오. 기존 Synapse 데이터베이스 또는 이미 테이블이 포함된 데이터베이스에 덮어쓰기 복원을 수행하지 마십시오. 롤백을 위해 현재 데이터베이스를 보존해야 하는 경우, 데이터베이스를 그대로 두고 임시 데이터베이스 이름으로 복원한 다음 Synapse 구성을 변경하기 전에 유효성을 검사하십시오.

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

데이터베이스 소유자와 로케일은 Synapse 설정 요구 사항과 일치해야 합니다. 대상 이름이 이미 존재하는 경우, 작업을 중지하고 사용할 데이터베이스를 확인하십시오. 데이터베이스를 삭제해도 안전하다고 가정하지 마십시오. 필요한 PostgreSQL 역할을 먼저 생성하십시오. 단일 데이터베이스에는 pg_dump클러스터 전체 역할이 포함되지 않으므로 새 PostgreSQL 클러스터로 이동하는 관리자는 별도로 보호된 전역 변수 백업을 생성해야 할 수도 있습니다 pg_dumpall --globals-only.

터미널에서 C 로케일, 템플릿 0, synapse_user 소유권으로 빈 UTF8 PostgreSQL 데이터베이스를 생성합니다. — 대상 위치를 Synapse에서 요구하는 인코딩, 로케일 및 소유자로 설정된 빈 데이터베이스로 생성합니다.

5. 아카이브를 복원하고 일회용 키를 처리합니다.

사용자 지정 아카이브를 비어 있는 대상 위치에 로드합니다. 명시적 오류 옵션을 사용하면 복원 과정에서 오류가 발생했을 때 복원이 중단됩니다. 오류가 발생하면 복원이 계속 진행되어 불완전한 결과를 남기게 되어 오류를 쉽게 알아차릴 수 있습니다.

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

덤프 파일에서 해당 행이 제외되지 않은 경우 e2e_one_time_keys_json, 복원된 데이터베이스에 연결하여 Synapse를 시작하기 전에 해당 테이블을 비우십시오. 이는 해당 행이 포함된 백업에 대해 Synapse에서 제공하는 복구 안전 장치입니다. 실제 운영 중인 데이터베이스에서 이 명령을 함부로 실행하지 마십시오. 해당 테이블의 모든 행이 삭제됩니다.

PostgreSQL 터미널에서 pg_restore를 실행하여 사용자 지정 형식의 Synapse 아카이브를 Synapse 데이터베이스에 로드합니다. — 새로운 빈 대상 데이터베이스를 생성한 후에만 아카이브를 복원하고, 계속 진행하기 전에 오류 메시지를 검토하십시오.

Synapse에 연결된 psql 터미널에 TRUNCATE e2e_one_time_keys_json이 표시됩니다. — 복원된 덤프에 일회용 키 행이 포함된 경우에만 이 기능을 사용하십시오. 테이블이 완전히 지워질 때까지 Synapse는 중지된 상태로 유지해야 합니다.

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

권장 제외 조건을 사용했다면 복원 결과에는 이전의 일회성 키 행이 포함되지 않으므로 이 잘라내기 단계는 불필요합니다. 테이블 항목은 pg_restore --list데이터가 없는 테이블 정의를 나타낼 수 있습니다. TABLE DATA아카이브 내용을 검토할 때 해당 항목을 확인하십시오. 가장 안전한 운영 기록은 사용한 정확한 덤프 명령입니다.

Synapse를 복구하고 복구 여부를 확인하십시오.

6. 관련 파일을 복원하고 Synapse를 시작합니다.

재시작하기 전에 복원된 구성이 의도한 데이터베이스를 가리키고 있는지, 그리고 Synapse 프로세스에서 예상되는 서명 키와 미디어 저장소를 사용할 수 있는지 확인하십시오. 임시 데이터베이스 이름으로 복원한 경우, 데이터베이스 설정을 안전하게 업데이트하고 파일의 유효성을 검사한 다음, 일반적인 배포 프로세스를 사용하여 활성화하십시오. 새 인스턴스가 검사를 통과할 때까지 이전 데이터베이스와 이전 구성을 보관하십시오.

배포 환경에 맞는 명령어를 사용하여 서비스를 시작하세요. systemd 호스트에서는 서비스 상태와 최근 로그를 확인하십시오. 컨테이너에서는 컨테이너 상태와 로그를 확인하십시오. 실행 중인 프로세스는 초기 신호일 뿐이며, 사용자가 채팅방을 읽거나, 메시지를 보내거나, 첨부 파일을 가져올 수 있다는 것을 보장하는 것은 아닙니다.

PostgreSQL 아카이브 목록을 검토하고 Synapse 시작 및 서비스 상태 명령을 표시하는 터미널 화면입니다. — 복원 후 아카이브 및 서비스 로그를 확인하고, 실제 클라이언트 작동 여부를 검증한 후 복구가 완료되었음을 선언하십시오.

7. 사용자가 의존하는 기능을 테스트하십시오.

Synapse가 데이터베이스 마이그레이션, 권한, 로케일 또는 연결 오류 없이 시작되는지 확인하십시오.
테스트 계정으로 로그인하여 기존 방을 읽어보세요. 유지 관리 플랜에 따라 테스트 메시지를 보낼 수도 있습니다.
배포 환경에 연동 기능이 포함되어 있다면 연동 및 애플리케이션 서비스 동작을 확인하십시오.
로컬에 업로드된 첨부 파일이나 아바타를 열어 미디어 저장소가 복원된 데이터베이스와 일치하는지 테스트하십시오.
Synapse 로그와 PostgreSQL 로그를 확인하여 시작 후 반복적으로 발생하는 오류를 점검하십시오. 첫 번째 성공적인 상태 점검 결과만 확인하는 것이 아닙니다.

미디어 파일, 참조된 구성 또는 역할이 누락된 경우에도 복원이 기술적으로 성공할 수 있습니다. 사용자가 첨부 파일이 누락된 것을 확인하는 경우, 구성된 미디어 저장소를 확인하고 해당 로컬 미디어 백업을 복원하십시오. Synapse에 연결할 수 없는 경우, 복원된 데이터베이스 소유자, 자격 증명, 호스트, 데이터베이스 이름, 로케일 및 활성 구성 파일을 비교하십시오.

일반적인 오류 신호 및 방법 변경 시점

신호	다음으로 확인해야 할 사항
`pg_restore`기존 관계 또는 소유권 오류를 보고합니다.	대상 위치가 비어 있고 필요한 역할이 존재하는지 확인하십시오. 새 데이터베이스에 복원하십시오. `--clean`내용을 보존해야 하는 데이터베이스에 대한 바로 가기로 사용하지 마십시오.
dump 명령이 0이 아닌 종료 코드를 반환하거나 읽을 수 없는 파일을 생성합니다.	클라이언트/서버 호환성, 권한, 디스크 공간, 대상 권한 및 PostgreSQL 로그를 확인하십시오. 새 덤프를 생성하고 유효성을 검사한 후에 사용하십시오.
Synapse가 시작되었지만 이전 일회용 키가 포함되어 있습니다.	Synapse를 중지하고 문서화된 데이터 삭제 절차를 따른 후 클라이언트에 서비스를 제공하도록 허용하십시오.
룸 기능은 작동하지만 로컬 연결에 문제가 있습니다.	일치하는 로컬 미디어 저장소 및 구성을 복원하십시오. PostgreSQL 덤프에는 업로드된 미디어 파일이 포함되어 있지 않습니다.
복구 시간 또는 데이터베이스 크기가 허용 범위를 초과했습니다.	PostgreSQL의 다른 백업 방식(예: 기본 백업 및 WAL 아카이빙을 사용한 특정 시점 복구)을 복구 시점 및 복구 시간 목표와 비교하여 평가하십시오.

논리적 덤프는 소규모 및 중규모 배포 환경에서 휴대성이 좋고 사용이 간편하지만, 데이터베이스 규모가 커짐에 따라 복원하는 데 시간이 오래 걸릴 수 있습니다. 대규모 또는 고가용성 서비스의 경우, PostgreSQL의 최신 백업 문서를 참조하여 검증된 물리적 백업 또는 특정 시점 복구 설계를 계획하십시오. 별도의 휴대성 또는 감사 목적이 있는 경우 독립적인 논리적 덤프를 보관하십시오. 두 방법 모두 PostgreSQL 외부에 저장된 파일은 보호하지 못하며, 이러한 파일은 별도로 백업해야 합니다.

터미널에서 synapse.dump 파일의 SHA-256 체크섬을 계산하고 별도의 백업 위치에 저장된 사본 목록을 보여줍니다. — Synapse 호스트에서 아카이브를 복사한 후 체크섬을 비교하여 전송 또는 저장 위치 변경 사항을 감지합니다.

복구 체크리스트

덤프 파일은 읽기 가능하며 pg_restore --list체크섬이 호스트 외부에 있는 복사본과 일치합니다.
복원 작업은 예상했던 인코딩, 로케일, 소유자 및 역할을 가진 새롭고 비어 있는 데이터베이스에 수행되었습니다.
일회성 키 행이 제외되었거나 Synapse가 다시 시작되기 전에 테이블이 잘렸습니다.
구성 파일, 서명 키 및 필요한 로컬 미디어는 호환 가능한 백업에서 복원되었습니다.
Synapse 로그는 서비스에 필요한 만큼 깨끗하며, 회의실 및 미디어에 대한 클라이언트 수준 검사도 통과했습니다.
복구 훈련을 통해 문서화된 복구 단계를 확인하고 실제 복구 시간을 측정했습니다.

공식 참고 자료

Synapse 백업 가이드 — 데이터베이스별 권장 사항, 일회용 키 처리, 구성, 서명 키 및 미디어 저장소.
Synapse: PostgreSQL 사용하기 — 데이터베이스 설정 및 구성 세부 정보.
PostgreSQL: pg_dump , pg_restore 및 PostgreSQL 백업 및 복원 - 아카이브 옵션 및 보다 폭넓은 백업 전략.

본 문서는 2026년 10월 6일에 확인되었습니다. 명령어 이름과 서비스 관리 방식은 운영 체제, 컨테이너 이미지, PostgreSQL 버전 및 Synapse 배포 방식에 따라 다를 수 있습니다. 사용하시는 버전과 패키징 방식에 맞는 문서를 참조하여 지침을 확인하십시오.