CasaOS의 Matrix Synapse에 “컨테이너가 비정상 상태입니다”가 표시되면, 무작정 재설치하기보다 컨테이너 로그와 생성된 homeserver.yaml부터 확인하세요. Synapse에는 공식 Docker 이미지가 제공되지만, 프로덕션 홈서버를 운영하려면 영구 구성 및 데이터 저장소, 적절한 서버 이름, PostgreSQL, HTTPS 및 연합(federation) 계획도 필요합니다.
SQLite는 테스트용으로는 사용할 수 있지만, 최신 Synapse 문서에서는 거의 모든 실제 설치 환경에 PostgreSQL을 권장합니다. 구성, 데이터베이스, 권한 또는 시작 마이그레이션에 문제가 있으면 컨테이너가 시작되더라도 비정상 상태로 남을 수 있습니다.
공식 Synapse 이미지 사용
최신 Synapse 설치 가이드에서는 ghcr.io/element-hq/synapse를 공식 컨테이너 이미지로 안내합니다.
초기 구성 생성
일반적인 시작 전에 영구 디렉터리를 만들고 구성을 한 번 생성하세요.
mkdir -p /DATA/AppData/synapse
docker run --rm -it -v /DATA/AppData/synapse:/data -e SYNAPSE_SERVER_NAME=matrix.example.com -e SYNAPSE_REPORT_STATS=no ghcr.io/element-hq/synapse:latest generate예시 도메인은 계속 사용할 Matrix 서버 이름으로 바꾸세요.
컨테이너가 비정상 상태인 이유 확인
docker ps -a | grep synapse
docker inspect synapse --format '{{json .State.Health}}'
docker logs --tail 200 synapseYAML 오류, 누락된 파일, 권한 오류, 데이터베이스 연결 오류 또는 완료되지 않는 마이그레이션을 확인하세요.
프로덕션에서는 PostgreSQL 사용
최신 Synapse PostgreSQL 가이드에서 지원되는 데이터베이스 설정을 설명합니다. PostgreSQL 데이터를 영구적으로 저장하고 Synapse 상태 데이터와 함께 백업하세요.
계획 없이 나중에 server_name을 변경하지 마세요
Matrix ID는 @user:example.com처럼 서버 이름을 바탕으로 생성됩니다. 사용자를 초대하기 전에 장기간 사용할 도메인을 선택하세요.
실제 사용에는 HTTPS가 필요합니다
Synapse는 일반적으로 HTTP(보통 포트 8008)로 내부에서 수신 대기합니다. 클라이언트와 연합을 위해 원시 컨테이너 포트를 공개하는 대신 HTTPS를 지원하는 리버스 프록시를 사용하세요.
연합에는 추가 DNS 및 프록시 요구 사항이 있습니다
다른 Matrix 서버와 통신하려면 공개 서버 이름, HTTPS 및 연합 검색을 올바르게 구성하세요. 로컬 전용 테스트는 훨씬 간단하게 구성할 수 있습니다.
컨테이너 외에도 백업해야 합니다
homeserver.yaml, 서명 키, 업로드된 미디어 및 PostgreSQL 데이터베이스를 보존하세요. 이미지를 다시 가져오는 것만으로는 홈서버의 신원이 복원되지 않습니다.
Docker 문제 해결 가이드에서 일반적인 컨테이너 디버깅 방법을 확인할 수 있습니다.
영구 데이터 폴더의 파일 소유권 확인
컨테이너 로그에 homeserver.yaml, 서명 키 또는 미디어를 읽는 중 권한 거부가 표시되면, 이미지가 요구하는 UID/GID에 맞게 연결된 Synapse 데이터 디렉터리의 소유권을 수정하세요. CasaOS 데이터 트리 전체를 모든 사용자가 쓰기 가능하도록 설정하지 마세요.
상태를 판단하기 전에 데이터베이스 마이그레이션이 완료될 때까지 기다리기
업그레이드 후 또는 PostgreSQL에 처음 연결할 때 Synapse가 스키마 마이그레이션을 실행하는 데 시간이 걸릴 수 있습니다. 컨테이너를 반복해서 재시작하기보다 로그를 확인하세요. 마이그레이션이 중단되면 진단이 더 어려워질 수 있습니다.
리버스 프록시 전에 로컬 API 테스트
HTTPS, DNS 또는 연합을 추가하기 전에 CasaOS 호스트에서 내부 Synapse HTTP 엔드포인트가 응답하는지 확인하세요. 로컬 API가 비정상이면 리버스 프록시로 해결할 수 없습니다.
FAQ
Synapse가 비정상 상태인 이유는 무엇인가요?
로그와 상태 출력에서 구성, 권한, 데이터베이스 또는 마이그레이션 오류를 확인하세요. 원문 스레드에는 검증된 단일 원인이 제시되지 않았습니다.
SQLite를 사용할 수 있나요?
테스트용으로는 사용할 수 있습니다. 최신 Synapse 문서에서는 거의 모든 프로덕션 설치에 PostgreSQL을 권장합니다.
Synapse는 내부적으로 어떤 포트를 사용하나요?
일반적인 Docker 구성에서는 리버스 프록시 뒤에서 클라이언트/서버 API에 포트 8008을 사용합니다.
Element가 필요한가요?
아니요. Synapse는 홈서버이고, Element는 사용할 수 있는 클라이언트/웹 프런트엔드 중 하나입니다.
