가이드

작성자 Matt Connor 2026-08-14

Matrix Synapse 홈 서버 VPS 구축 및 운영 가이드

Q: 홈 서버에 낯선 사람이 등록하지 못하게 하려면 어떻게 해야 하는가?

enable_registration를 기본값인 false으로 유지하고 register_new_matrix_user을 사용하여 계정을 생성하십시오. 이 방법으로 감당하기 어려워지면 enable_registration: true와 registration_requires_token: true을 함께 설정하고, POST /_synapse/admin/v1/registration_tokens/new를 통해 생성된 토큰을 배포하십시오. 단순히 Synapse의 시작 거부 경고를 피하기 위해 enable_registration_without_verification: true를 설정해서는 안 됩니다. 개방된 홈 서버는 스팸 발송지가 될 수 있으며, 다른 관리자들이 귀하의 도메인 전체를 차단하는 결과로 이어질 수 있습니다.

Matrix Synapse를 VPS에 설치하고 안정적으로 유지하는 핵심 전략을 다룹니다. 1 vCPU와 2 GB RAM 환경에서의 사이징, Postgres 최적화, 미디어 보관 정책, 가입 방지 설정 및 백업 방법을 상세히 설명합니다.

Matrix Synapse 홈 서버를 안정적으로 유지하는 방법

Matrix Synapse는 설치하기는 쉽지만 방치하기도 쉽습니다. 설치 과정은 apt 저장소 하나, 설정 파일 하나, 리버스 프록시 블록 하나, DNS 레코드 하나면 충분합니다. 하지만 1년 동안 홈 서버를 건강하게 유지하는 것은 다른 차원의 작업입니다. 실제 데이터베이스 사용, 주기적으로 정리되는 미디어 저장소, 외부인의 무분별한 가입 방지, 그리고 서버의 양대 구성 요소를 모두 포함하는 백업이 필요합니다.

이 가이드는 Ubuntu 24.04 LTS를 대상으로 하며, Synapse 프로젝트가 Debian 및 Ubuntu를 위해 직접 관리하는 matrix.org apt 저장소에서 Synapse를 설치합니다. 패키지 버전은 몇 주마다 변경되므로 여기서는 특정 버전 번호를 명시하지 않습니다. 아래의 모든 경로와 옵션은 최신 Synapse 공식 문서를 따릅니다.

사이징: 1 vCPU와 2 GB RAM이 실제로 제공하는 성능

2026년 8월 기준으로 게시된 사이징 페이지들은 일반적으로 Synapse 홈 서버의 사양을 1 vCPU와 2 GB RAM으로 권장합니다. 이는 개인용 서버, 소수의 사용자, 작은 규모의 방, 그리고 활발한 공개 방이 없는 환경이라는 한 가지 경우에만 정직한 수치입니다. Synapse 문서는 다른 경우에 대해 명확히 밝히고 있습니다. 문서는 "#matrix:matrix.org와 같은 대규모 공개 방에 참여하려면 최소 1GB의 여유 RAM이 필요하다"고 명시합니다. 여기서 여유 RAM이란 Python, Postgres, 커널이 사용하는 메모리를 제외한 공간을 의미합니다.

방 하나가 사이징을 바꿀 수 있는 이유는 참여 방식 때문입니다. 로컬 사용자가 방에 참여하면, 귀하의 홈 서버는 해당 방의 완전한 참여자가 됩니다. 서버는 방에 있는 다른 모든 서버로부터 모든 이벤트를 수신하고, 각 이벤트의 서명을 검증하며, 방의 상태를 로컬에 저장합니다. 대규모 공개 방은 수백 개의 서버에 걸쳐 수천 명의 멤버가 있으므로, 사용자가 해당 방을 다시 열지 않더라도 서버는 지속적으로 이 작업을 수행합니다. 나중에 방에서 나가더라도 이미 저장된 기록은 삭제되지 않습니다.

Synapse RAM의 대부분은 캐시에 사용됩니다. caches 섹션에는 모든 캐시를 한 번에 조정하는 global_factor이 있으며, SYNAPSE_CACHE_FACTOR 환경 변수도 동일한 역할을 합니다. 이 값을 높이면 RAM을 사용하여 데이터베이스 쿼리를 줄일 수 있습니다. 값을 낮추면 RAM을 절약하는 대신 CPU와 Postgres의 작업량이 늘어납니다. Postgres 또한 자체적인 메모리를 필요로 하므로, 2 GB 사양의 서버에서는 두 프로세스가 동일한 메모리 공간을 두고 경쟁하게 됩니다.

소규모 플랜을 위한 두 가지 실용적인 규칙이 있습니다. 첫째, 스왑(swap)을 추가하십시오. 스왑이 Synapse를 빠르게 만들지는 않지만, 대규모 방에 참여하는 동안 커널이 프로세스를 강제 종료하는 것을 방지합니다. 둘째, 첫 주부터 디스크 사용량을 모니터링하십시오. 미디어 저장소와 방 상태 테이블은 제한 없이 증가하며, 둘 다 디스크 공간을 차지하기 때문입니다.

Postgres를 선택해야 하는 이유와 SQLite가 한계에 부딪히는 이유

Debian 패키지는 기본적으로 SQLite를 사용합니다. 이는 첫 부팅 시에는 적합하지만, 다른 사용자가 함께 사용하는 서버에는 부적절합니다. SQLite는 한 번에 하나의 쓰기 작업만 허용합니다. 페더레이션 트래픽과 클라이언트 요청이 동시에 쓰기를 시도하면, 가벼운 요청이 느린 요청 뒤에서 대기하게 됩니다. 이로 인해 사용자는 애플리케이션이 무작위로 몇 초간 멈추는 현상을 겪게 됩니다.

두 번째 이유는 구조적인 문제입니다. Synapse의 worker 프로세스는 여러 CPU 코어를 활용하기 위한 공식적인 방법이며, worker를 사용하려면 Postgres가 필수입니다. SQLite를 계속 사용하면 성능 저하뿐만 아니라 향후 확장성도 포기하게 됩니다.

나중에 마이그레이션하는 것도 지원되지만, 이 과정에서 서비스 중단이 발생하므로 사용자가 늘어나기 전에 미리 수행하십시오. Synapse는 SQLite 데이터베이스를 준비된 Postgres 데이터베이스로 복사하는 synapse_port_db를 제공합니다.

synapse_port_db --sqlite-database homeserver.db --postgres-config homeserver-postgres.yaml

데이터베이스를 Synapse와 함께 컨테이너에서 실행하고 싶다면, Docker에서 데이터베이스를 실행할지 호스트에서 실행할지에 따른 장단점을 고려하십시오.

Ubuntu 24.04에 Synapse 설치하기

sudo apt install -y lsb-release wget apt-transport-https
sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/matrix-org.list
sudo apt update
sudo apt install matrix-synapse-py3

Ubuntu 24.04에서 lsb_release -cs은 noble을 출력하며, matrix.org 저장소는 noble 제품군을 배포합니다. Ubuntu 자체 아카이브에 있는 matrix-synapse 패키지는 사용하지 마십시오. Synapse 프로젝트는 해당 빌드가 공식 릴리스보다 뒤처져 있고 알려진 보안 취약점이 포함되어 있으므로 사용하지 말 것을 권장합니다.

설치 프로그램은 서버 이름을 요구하며, 입력한 내용은 /etc/matrix-synapse/conf.d/server_name.yaml에 기록됩니다. 신중하게 입력하십시오. server_name은 모든 사용자 ID(@alice:example.com)에서 콜론 뒤에 오는 부분이며, 서버가 생성하는 모든 대화방에 포함됩니다. 나중에 이를 변경해도 기존 데이터는 이전되지 않으며, 완전히 다른 홈 서버가 생성됩니다. Synapse가 실제로는 matrix.example.com에서 실행되더라도, 서버 이름은 example.com과 같은 도메인 주소를 사용하십시오. 위임(Delegation)을 통해 두 주소를 연결하며, 이에 대해서는 다음 섹션에서 다룹니다.

이 패키지는 matrix-synapse 사용자로 Synapse를 실행하며, 데이터를 /var/lib/matrix-synapse 아래에 보관하고, /etc/matrix-synapse/homeserver.yaml을 읽은 뒤 /etc/matrix-synapse/conf.d/의 모든 파일을 순차적으로 읽습니다. 사용자 설정은 conf.d에 작은 파일 단위로 작성하십시오. 패키지 업그레이드 시 해당 파일들은 변경되지 않고 유지됩니다.

sudo systemctl restart matrix-synapse
systemctl status matrix-synapse
sudo journalctl -u matrix-synapse -n 100 --no-pager

정상적으로 시작되면 리스너가 활성화된 후 조용해집니다. systemd 유닛은 서비스가 종료되면 몇 초 뒤에 자동으로 재시작하므로, Synapse가 거부하는 설정이 있으면 유닛이 시작과 종료를 반복하는 루프에 빠지게 됩니다. 저널의 마지막 줄을 확인하면 거부된 키의 이름을 알 수 있습니다.

Synapse를 Postgres에 연결하기

sudo apt install -y postgresql
sudo -u postgres createuser --pwprompt synapse_user
sudo -u postgres createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse_user synapse

로캘은 단순한 장식 요소가 아닙니다. Synapse는 서로 다른 COLLATE 및 CTYPE 값으로 생성된 데이터베이스에서는 시작을 거부합니다. 데이터베이스 설정에서 allow_unsafe_locale를 지정하지 않으면 이러한 문제가 발생하며, 이후 권장되는 복구 방법은 데이터를 덤프한 뒤 올바르게 생성된 데이터베이스로 다시 로드하는 것뿐입니다. 처음부터 올바르게 생성하십시오.

database:
  name: psycopg2
  txn_limit: 10000
  args:
    user: synapse_user
    password: secretpassword
    dbname: synapse
    host: localhost
    port: 5432
    cp_min: 5
    cp_max: 10

모든 설정 파일에서 database: 키를 정확히 하나만 유지하십시오. conf.d 아래에 두 번째 복사본을 추가하는 대신 homeserver.yaml 내부의 SQLite 블록을 교체하십시오. 이렇게 하면 어떤 설정이 활성 상태인지 혼동할 일이 없습니다. 재시작 후 Synapse가 실제로 Postgres를 사용 중인지 확인하십시오:

sudo -u postgres psql synapse -c "SELECT count(*) FROM users;"

숫자가 출력된다면 Synapse가 해당 데이터베이스에 스키마를 성공적으로 구축한 것입니다. 존재하지 않는 관계(relation)에 대한 오류가 발생한다면 여전히 SQLite 파일에 기록하고 있다는 뜻이므로, 편집한 설정 파일이 실제로 읽히고 있지 않은 것입니다.

리버스 프록시, TLS 및 .well-known 파일 페더레이션 요구 사항

Synapse는 localhost에 바인딩된 8008 포트에서 일반 HTTP로 대기합니다. TLS와 공개 포트는 앞단에 위치한 리버스 프록시가 담당합니다.

listeners:
- port: 8008
  tls: false
  type: http
  x_forwarded: true
  bind_addresses:
  - '::1'
  - '127.0.0.1'
  resources:
  - names:
    - client
    - federation
    compress: false

x_forwarded: true은 프록시가 설정한 X-Forwarded-For 헤더를 Synapse가 신뢰하도록 지시합니다. 이 설정이 없으면 모든 클라이언트가 127.0.0.1에서 접속한 것으로 간주됩니다. 이로 인해 속도 제한(rate limiting) 기능은 모든 사용자를 하나의 매우 바쁜 로컬 사용자로 인식하여 전체 접속을 차단하게 됩니다.

location ~ ^(/_matrix|/_synapse/client) {
    proxy_pass http://localhost:8008;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host:$server_port;
    client_max_body_size 50M;
    proxy_http_version 1.1;
}

Synapse 문서에는 이 블록과 관련하여 많은 사용자가 며칠씩 고생하게 만드는 경고가 하나 있습니다. proxy_pass의 포트 뒤에 /을 포함하여 경로를 추가하지 마십시오. nginx는 URI를 정규화하는데, 이 과정에서 송신 서버가 서명한 바이트 값이 변경됩니다. 결과적으로 일반 클라이언트 요청은 정상 작동하더라도 페더레이션 요청은 서명 검증에 실패하게 됩니다.

client_max_body_size은 최소한 Synapse의 max_upload_size과 같거나 커야 합니다. nginx의 설정값이 더 작으면, 해당 크기를 초과하는 업로드는 Synapse에 도달하기 전에 nginx가 413 Request Entity Too Large 오류로 거부합니다. 따라서 Synapse 로그에는 실패 원인이 기록되지 않습니다.

인증서 자체는 Certbot and Let's Encrypt on Ubuntu 24.04를 따르십시오. 프록시 선택이 고민된다면 reverse proxy comparison에서 각 프록시의 TLS 처리 방식을 확인할 수 있습니다.

위임(Delegation)은 Synapse가 matrix.example.com에서 실행되는 동안 server_name이 example.com로 유지되도록 합니다. 도메인 루트에서 다음 두 파일을 제공하십시오.

location /.well-known/matrix/server {
    default_type application/json;
    return 200 '{"m.server": "matrix.example.com:443"}';
}

location /.well-known/matrix/client {
    default_type application/json;
    add_header Access-Control-Allow-Origin '*';
    return 200 '{"m.homeserver": {"base_url": "https://matrix.example.com"}}';
}

서버 파일은 다른 홈 서버에 페더레이션 트래픽을 보낼 위치를 알려주며, 이를 통해 페더레이션이 기본 포트인 8448 대신 443 포트로 실행됩니다. 클라이언트 파일은 Matrix 클라이언트에 @alice:example.com을 지원하는 URL을 알려줍니다. 클라이언트 파일에서는 Access-Control-Allow-Origin 헤더가 중요합니다. 브라우저 기반 클라이언트는 이를 교차 출처(cross-origin)로 가져오기 때문에, 해당 헤더가 없으면 브라우저가 응답을 차단하여 클라이언트가 홈 서버를 찾을 수 없다는 오류를 보고합니다.

두 파일 모두 example.com 자체에서 유효한 TLS를 통해 제공되어야 합니다. 파일을 확인한 다음 외부에서 어떻게 보이는지 점검하십시오.

curl -s https://example.com/.well-known/matrix/server
curl -s https://matrix.example.com/_matrix/federation/v1/version

첫 번째 명령은 작성한 JSON을 반환합니다. 두 번째 명령은 서버 구현체와 버전을 명시한 JSON 객체를 반환하며, 이는 프록시가 페더레이션 경로를 통해 Synapse에 정상적으로 도달함을 증명합니다. 마지막으로 https://federationtester.matrix.org의 Matrix 페더레이션 테스터를 통해 도메인을 확인하십시오. 이 도구는 실제 원격 서버가 거치는 경로와 동일한 경로를 따라 검사를 수행합니다.

페더레이션 여부 결정하기: 의도적으로 선택하십시오

페더레이션은 Matrix의 핵심이자 운영 비용의 대부분을 차지하는 요소입니다. 페더레이션 홈 서버는 들어본 적 없는 서버로부터의 연결을 수락하고, 이벤트를 수신하며, 미디어를 캐싱하고, 사용자가 참여하는 모든 방의 상태를 저장합니다. 이는 기본 설정이 아니라 위협 모델에 따른 결정입니다.

사용자가 다른 홈 서버의 사람들과 소통해야 하거나, 이동 가능한 식별자(portable identity)가 Matrix를 선택한 이유라면 페더레이션을 사용하십시오. 서버가 단일 팀을 위해 존재하고 모든 계정이 본인 소유라면 페더레이션을 사용하지 마십시오. 폐쇄형 서버는 저장 데이터가 적고 수신하는 데이터도 적으며, 공격 대상이 될 가능성도 훨씬 낮습니다.

페더레이션을 비활성화하는 대신 제한하려면 Synapse의 허용 목록(allow list) 기능을 사용하십시오:

federation_domain_whitelist:
- lon.example.com
- nyc.example.com

문서에서는 원치 않는 트래픽이 Python 내부까지 도달하지 않도록 방화벽에서 페더레이션 리스너를 차단할 것을 권장합니다. 페더레이션을 완전히 끄려면 리스너 resources 목록에서 federation를 제거하고, /.well-known/matrix/server을 게시하지 않으며, 8448 포트를 닫아 두십시오.

Matrix를 운영하는 이유가 사내 팀 채팅이며 페더레이션이 전혀 필요 없다면, Synapse를 도입하기 전에 다른 자체 호스팅 Slack 대안들과 운영 비용을 비교해 보십시오. Docker Compose 기반의 Rocket.Chat은 다른 조직의 방 상태를 저장할 필요가 없으므로 더 작은 사양의 서버에서도 팀 채팅 서비스를 운영할 수 있습니다.

미디어 저장소는 디스크 공간을 점유하는 주원인입니다

사용자가 업로드한 파일은 디스크에 영구적으로 저장됩니다. 다른 홈 서버의 사용자가 게시한 파일은 귀하의 클라이언트가 해당 파일을 표시하는 즉시 서버로 가져와 캐시되며, Synapse는 이미지 썸네일도 생성하므로 사진 한 장이 여러 개의 파일로 늘어납니다. 기본적으로는 어떤 파일도 자동으로 삭제되지 않습니다.

저장소 위치를 찾고 용량을 측정하십시오:

grep media_store_path /etc/matrix-synapse/homeserver.yaml
sudo du -sh /var/lib/matrix-synapse/media_store

사용 중인 설정 파일에 명시된 경로를 측정하십시오. Debian 패키지는 Synapse 데이터를 /var/lib/matrix-synapse 아래에 보관하므로, 저장소는 일반적으로 해당 위치에 있습니다. 그런 다음 conf.d에서 보존 정책을 설정하십시오:

media_retention:
  local_media_lifetime: 90d
  remote_media_lifetime: 14d

이 두 줄은 설정 방식이 다르므로 주의 깊게 읽어야 합니다. remote_media_lifetime는 캐시를 만료시키며, 삭제된 파일은 원본을 소유한 서버에서 다시 가져올 수 있습니다. local_media_lifetime는 귀하의 사용자가 업로드한 파일을 해당 기간이 지나면 영구적으로 삭제합니다. 채팅에서 문서를 공유하고 내년에도 이를 확인하려는 팀은 해당 파일을 잃게 됩니다. 많은 서버가 원격 미디어 값만 설정합니다.

일회성 정리를 수행하려면 관리자 API에 밀리초 단위의 Unix 타임스탬프를 전달하십시오:

BEFORE_TS=$(date -d '30 days ago' +%s%3N)
curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://matrix.example.com/_synapse/admin/v1/purge_media_cache?before_ts=$BEFORE_TS"

POST /_synapse/admin/v1/purge_media_cache은 해당 타임스탬프 이전에 마지막으로 액세스한 원격 미디어 캐시를 삭제합니다. POST /_synapse/admin/v1/media/delete?before_ts=<ms>은 동일한 규칙에 따라 로컬 미디어를 삭제합니다. 연합 서버의 경우 원격 캐시가 차지하는 비중이 보통 더 크므로, 원격 미디어 정리를 먼저 수행한 후 용량을 다시 측정하십시오.

두 가지 설정이 동일한 디스크 공간에 영향을 줍니다. max_upload_size은 단일 업로드 크기를 제한하며, nginx의 client_max_body_size 설정과 일치시켜야 합니다. url_preview_enabled: true은 클라이언트가 링크 미리보기를 표시할 수 있도록 서버가 원격 페이지를 가져오게 하며, 이는 대역폭을 소모하고 업로드되지 않은 콘텐츠의 썸네일까지 저장하게 만듭니다.

홈 서버를 발견하기 전에 가입 기능을 닫으십시오

스캐너는 며칠 내로 열려 있는 홈 서버를 찾아냅니다. 계정 생성이 자유로워지면 귀하의 서버는 연합된 모든 방에서 스팸 발송지가 되며, 상대 측 관리자들은 귀하의 도메인 전체를 차단하게 됩니다. 차단 목록은 수동으로 관리되므로, 서버를 정리한 뒤에도 평판 훼손은 오랫동안 지속됩니다.

Synapse는 기본적으로 가입이 닫힌 상태로 제공됩니다. enable_registration은 기본값이 false이며, registration_requires_token은 기본값이 false입니다. 또한 Synapse는 enable_registration_without_verification: true를 추가로 설정하지 않는 한, 가입 기능이 활성화되어 있고 검증 단계가 없으면 시작을 거부합니다. 이러한 거부는 의도된 것이므로, 시작 오류를 없애기 위해 이 설정을 억지로 켜지 마십시오.

원하는 계정은 수동으로 생성하십시오:

sudo register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008

이 명령은 사용자 이름, 비밀번호, 그리고 계정을 서버 관리자로 설정할지 여부를 묻습니다. 이 명령은 -c로 전달한 설정 파일에서 registration_shared_secret을 읽어옵니다. 따라서 공유 비밀(shared secret)을 찾을 수 없다는 오류가 발생하면, 해당 비밀이 포함된 파일을 -c로 지정하십시오.

수동으로 계정을 생성하는 방식이 한계에 다다르면, 가입 토큰(registration tokens)을 사용하는 것이 중간 단계의 해결책입니다. 토큰은 신규 사용자가 가입 시 반드시 제시해야 하는 문자열이며, 각 토큰에는 사용 횟수 제한을 설정할 수 있습니다.

enable_registration: true
registration_requires_token: true

curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"uses_allowed": 1}' \
  https://matrix.example.com/_synapse/admin/v1/registration_tokens/new

본문에서 token를 생략하면 Synapse가 토큰을 생성하여 반환합니다. GET /_synapse/admin/v1/registration_tokens은 현재 활성화된 토큰 목록을 보여줍니다. 두 호출 모두 서버 관리자 계정의 액세스 토큰이 필요하며, 이는 위에서 생성한 관리자 사용자로 로그인하여 얻을 수 있습니다.

이미 다른 곳에서 계정을 관리하는 조직이라면 로컬 비밀번호를 완전히 생략할 수 있습니다. Synapse는 OIDC(OpenID Connect) 제공자를 통해 로그인을 위임할 수 있기 때문입니다. 예를 들어 자체 호스팅 SSO 제공자로 Authentik 사용하기를 참고하십시오. 이렇게 하면 사용자의 가입과 탈퇴를 한곳에서 관리할 수 있습니다.

서버를 실제로 재구축할 수 있는 백업

Synapse 백업은 세 부분으로 구성되며, 이 중 하나라도 누락되면 아무도 사용할 수 없는 서버가 복구됩니다.

Postgres 데이터베이스: 모든 이벤트, 계정, 방 정보를 보관합니다.
미디어 저장소 디렉터리: 업로드된 모든 파일을 보관합니다.
/etc/matrix-synapse: 설정 파일과 서버의 서명 키를 보관합니다.

서명 키는 사람들이 자주 잊는 부분입니다. 이는 홈 서버가 이벤트에 서명할 때 사용하는 개인 키이며, 원격 서버는 일치하는 공개 키를 사용하여 이벤트를 검증합니다. grep signing_key_path /etc/matrix-synapse/homeserver.yaml를 실행하여 키의 위치를 확인하십시오. 이 키를 분실하면 기존 방들이 알고 있는 서버와 동일한 서버임을 증명할 수 없는 상태로 복구됩니다.

sudo -u postgres pg_dump --format=custom --file=/var/backups/synapse-$(date +%F).dump synapse
sudo tar czf /var/backups/synapse-etc-$(date +%F).tgz -C /etc matrix-synapse

먼저 데이터베이스를 덤프한 다음 미디어 저장소를 복사하십시오. 미디어 파일은 한 번 기록되면 ID로 참조되므로, 덤프 이후에 수행한 미디어 복사본에는 추가 파일만 포함될 뿐 누락된 파일은 발생하지 않습니다. 반대로 수행하면 복구된 데이터베이스가 백업에 포함되지 않은 파일을 참조하게 될 수 있습니다.

세 부분 모두 VPS 외부로 전송하십시오. 오프사이트 스냅샷을 사용하는 restic은 이러한 방식에 적합합니다. 미디어 저장소는 용량이 크지만 실행 간 변경 사항이 거의 없으므로, 중복 제거(deduplication)를 통해 각 스냅샷의 크기를 작게 유지할 수 있기 때문입니다.

그런 다음 복구 과정을 연습하십시오. 복구해 본 적 없는 백업은 가설에 불과합니다. 두 번째 VPS를 구축하고 동일한 패키지를 설치한 뒤, 설정을 복구하고, 동일한 인코딩과 로캘로 데이터베이스를 생성하십시오. 그 후 pg_restore으로 덤프를 삽입하고, 미디어 저장소를 복사한 다음 로그인하십시오. 소요 시간을 기록해 두십시오. 그 숫자가 귀하의 실제 복구 시간입니다.

상태 테이블이 커질 때: 압축

Synapse는 방 상태를 상태 그룹(state groups)으로 저장하며, 페더레이션 서버에서는 state_groups_state가 데이터베이스에서 가장 큰 객체가 되는 경우가 많습니다. 변경하기 전에 먼저 측정하십시오:

sudo -u postgres psql synapse -c "SELECT pg_size_pretty(pg_database_size('synapse'));"
sudo -u postgres psql synapse -c "SELECT pg_size_pretty(pg_total_relation_size('state_groups_state'));"

해당 테이블이 데이터베이스의 대부분을 차지한다면, 프로젝트에서 제공하는 압축 도구인 rust-synapse-compress-state를 사용하십시오. 이 도구는 방 상태의 의미를 변경하지 않으면서 상태 그룹 계층 구조를 더 적은 행으로 다시 작성합니다. Rust로 빌드되어 있습니다:

sudo apt install -y build-essential libssl-dev pkg-config git
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
git clone https://github.com/matrix-org/rust-synapse-compress-state.git
cd rust-synapse-compress-state/synapse_auto_compressor
cargo build --release

./target/release/synapse_auto_compressor -p postgresql://synapse_user:secretpassword@localhost/synapse -c 500 -n 100

-c은 한 번에 처리할 상태 그룹의 개수이며, -n은 이번 실행에서 처리할 해당 청크의 개수입니다. 자동 압축기는 진행 상황을 기록하므로 다음 실행 시 중단된 지점부터 계속할 수 있으며, 덕분에 안전하게 스케줄링할 수 있습니다. 문서에 따르면 변경 사항은 추가 전용(append-only) 테이블에 대한 트랜잭션으로 적용되므로 Synapse가 실행 중일 때도 수행할 수 있습니다. 단, 처음 실행하기 전에는 반드시 데이터베이스를 백업하십시오.

Postgres와 관련하여 한 가지 놀라운 점이 있습니다. 행을 삭제해도 공간은 파일 시스템이 아닌 Postgres가 재사용할 수 있도록 반환되므로, 대규모 압축 후에도 df의 크기는 줄어들지 않을 수 있습니다. VACUUM FULL를 실행하면 공간이 반환되지만, 이 작업은 테이블에 대해 배타적 잠금(exclusive lock)을 걸고 테이블 크기와 거의 동일한 여유 디스크 공간을 필요로 하므로, 즉흥적으로 실행하기보다는 유지보수 작업으로 스케줄링하십시오.

서버 상태가 정상인지 확인하는 점검 항목

systemctl status matrix-synapse
curl -s https://example.com/.well-known/matrix/server
curl -s https://matrix.example.com/_matrix/federation/v1/version
sudo -u postgres psql synapse -c "SELECT pg_size_pretty(pg_database_size('synapse'));"
sudo du -sh /var/lib/matrix-synapse/media_store

서버가 정상이라는 것은 유닛이 활성화되어 있고 재시작 중이 아니며, 위임 파일이 m.server 값을 반환하고, 페더레이션 버전 엔드포인트가 JSON을 반환하며, 두 가지 크기 수치를 지난달 데이터와 비교할 수 있는 상태를 의미합니다. 많은 관리자가 크기 점검을 건너뛰곤

FAQ

Matrix Synapse 서버에는 RAM이 얼마나 필요한가?

사용자가 적고 방 규모가 작으며 대규모 공개 방에 참여하지 않는 개인용 홈 서버라면 2 GB로도 운영이 가능하며, 2026년 8월 기준 대부분의 권장 사양 문서에서도 이를 제시합니다. Synapse 문서에서는 사용자가 #matrix:matrix.org와 같은 대규모 공개 방에 참여할 경우, 서버가 해당 방의 상태를 저장하고 트래픽을 지속적으로 처리해야 하므로 기존 메모리 외에 최소 1 GB의 여유 RAM을 추가로 확보할 것을 권장합니다. 2 GB 플랜을 사용하는 경우, 대규모 방 참여 시 커널에 의해 프로세스가 종료되는 것을 방지하기 위해 스왑(swap)을 반드시 설정하십시오.

SQLite 대신 PostgreSQL을 사용해야 하는가?

사용자가 몇 명 이상이라면 반드시 사용해야 합니다. SQLite는 한 번에 하나의 쓰기 작업만 허용하므로, 부하가 발생하면 페더레이션 트래픽과 클라이언트 요청이 서로를 차단하여 요청이 수 초간 지연되는 현상이 발생합니다. 여러 CPU 코어를 활용하는 공식적인 방법인 Synapse 워커 프로세스 또한 PostgreSQL을 요구합니다. 추후 synapse_port_db을 사용하여 마이그레이션할 수 있으나 서비스 중단 시간이 발생하므로, 사용자를 받기 전에 --encoding=UTF8 --locale=C --template=template0를 사용하여 데이터베이스를 생성하십시오.

Synapse의 디스크 사용량이 계속 증가하는 이유는 무엇인가?

특정 디렉터리와 테이블 때문입니다. 미디어 저장소는 서버가 참여 중인 방에 업로드된 모든 파일(원격 사용자의 미디어 캐시 및 생성된 썸네일 포함)을 보관하며, media_retention을 설정하기 전까지는 아무것도 만료되지 않습니다. state_groups_state 테이블은 페더레이션 서버의 방 상태 정보와 함께 증가하며, rust-synapse-compress-state를 통해 이를 줄일 수 있습니다. 무엇을 먼저 해결할지 결정하기 전에 media_store_path에서 du -sh을 실행하고 SELECT pg_size_pretty(pg_total_relation_size('state_groups_state'));을 사용하여 두 항목의 크기를 각각 측정하십시오.

홈 서버에 낯선 사람이 등록하지 못하게 하려면 어떻게 해야 하는가?

enable_registration를 기본값인 false으로 유지하고 register_new_matrix_user을 사용하여 계정을 생성하십시오. 이 방법으로 감당하기 어려워지면 enable_registration: true와 registration_requires_token: true을 함께 설정하고, POST /_synapse/admin/v1/registration_tokens/new를 통해 생성된 토큰을 배포하십시오. 단순히 Synapse의 시작 거부 경고를 피하기 위해 enable_registration_without_verification: true를 설정해서는 안 됩니다. 개방된 홈 서버는 스팸 발송지가 될 수 있으며, 다른 관리자들이 귀하의 도메인 전체를 차단하는 결과로 이어질 수 있습니다.

홈 서버를 페더레이션해야 하는가?

페더레이션은 기본값이 아니라 노출 범위에 대한 결정입니다. 사용자가 다른 홈 서버의 사람들과 소통해야 한다면 페더레이션을 활성화하십시오. 특정 팀만을 위한 서버라면 페더레이션을 끄는 것이 좋습니다. 페더레이션을 하지 않는 서버는 저장 데이터가 적고, 수신 트래픽이 적으며, 악용 사례도 훨씬 적기 때문입니다. 중간 단계로 federation_domain_whitelist을 설정하여 페더레이션 대상을 지정된 파트너 도메인으로 제한할 수 있으며, Synapse 문서에서는 애플리케이션 계층의 확인에만 의존하지 말고 페더레이션 리스너에 방화벽을 적용할 것을 권장합니다.

#matrix#synapse#self-hosting #postgresql#federation