사용자 지정 Matrix Room 별칭을 도메인에 설정하세요
Element 또는 Matrix API를 사용하여 권한, Synapse 명명 및 연동을 확인하고 Matrix 회의실에 도메인에서 쉽게 공유할 수 있는 주소를 부여하세요.
Matrix 룸에 와 같은 주소를 지정하려면 #support:example.com, 서버 이름이 인 홈서버에 로컬 룸 별칭을 생성한 example.com다음 Element에서 해당 별칭을 룸의 기본 주소로 선택하세요. 각 룸 별칭에 대해 별도의 DNS 레코드가 필요하지는 않지만, 기존 홈서버의 별칭 도메인은 DNS를 지정하는 것만으로는 변경할 수 없습니다.
룸 별칭 은 Matrix 룸의 영구 룸 ID (일반적으로 로 시작) 로 확인되는 읽기 쉬운 주소입니다 !. 하나의 룸은 여러 개의 별칭을 가질 수 있으며, 예를 들어 #support:example.com와 가 #help:example.com모두 동일한 룸을 가리킬 수 있습니다. 콜론 뒤의 텍스트는 해당 별칭을 확인하는 홈 서버를 나타내며, 모든 참가자를 호스팅하는 서버와 반드시 일치하는 것은 아닙니다.
Matrix는 별칭을 다음과 같은 형식으로 정의합니다 #localpart:server-name. Synapse의 경우, 이 server_name설정은 로컬에서 생성된 회의실 주소에 사용되는 도메인을 결정하며, Synapse 문서에 따르면 이 설정은 초기 설정 후에는 변경할 수 없습니다. 기존 서버 이름이 인 경우 , Element는 사용자가 해당 서버를 소유하고 있다는 이유만으로 matrix.example.com로컬 별칭을 로 변경하지 않습니다 . Matrix 식별자 사양 및 Synapse 구성 설명서를 참조하십시오 .#support:example.comexample.com
https://matrix.example.com주소가 설정되어 server_name있다고 가정합니다 example.com. 클라이언트 URL과 서버 이름은 다를 수 있습니다.support. 별칭은 해당 방을 생성하는 서버에서 고유해야 합니다.다음 경로는 2026년 10월에 확인한 Element 객실 설정 문서 의 객실 설정 용어와 일치합니다. 메뉴 위치는 Element 버전 및 다른 Matrix 클라이언트에 따라 다를 수 있습니다.
Element Web 또는 Element Desktop에서 대상 회의실을 엽니다. 회의실 정보 패널에서 회의실 설정을 선택 하거나 회의실의 세 점 메뉴에서 설정을 선택합니다 . 나중에 문제 해결을 위해 내부 회의실 ID가 필요한 경우 고급 섹션에서 ID를 찾아 문자를 변경하지 않고 복사합니다.
일반 설정 페이지 에서 '회의실 주소'를 찾은 다음 '로컬 주소'를 선택합니다. '회의실 주소' 필드 support에 'localpart'와 같은 별칭을 입력하고 '추가' 또는 그에 상응하는 '저장' 버튼을 선택합니다. 결과로 생성된 전체 주소가 'localpart'인지 확인합니다 . 만약 주소가 'localpart'로 끝난다면 작업을 중단하십시오. 이는 홈 서버 이름 문제이며, 회의실 설정에서 수정할 수 있는 오타가 아닙니다.#support:example.com:matrix.example.com
'회의실 주소' 항목 에서 '게시된 주소'를 찾아 '기본 주소 '로 설정하세요 #support:example.com. Element 설명서에 따르면 일반적으로 처음 생성된 로컬 주소가 자동으로 기본 주소로 선택됩니다. 회의실에 이미 여러 개의 별칭이 있는 경우 명시적으로 선택하는 것이 유용합니다.
기본 주소는 회의실의 정식 별칭 , 즉 회의실 상태에 표시되는 기본 주소입니다. 별칭 생성과 정식 별칭 선택은 관련이 있지만 서로 다른 작업입니다. Matrix는 대체 별칭도 지원합니다. 정식 별칭은 표시되기 전에 해당 회의실로 확인되어야 합니다.
공용 회의실 디렉터리에 이 회의실을 게시하려면 실제로 디렉터리 검색이 필요한 경우 에만 활성화하세요 . 주소를 설정하는 것만으로는 회의실이 공개되는 것이 아니며, 회의실 게시 설정은 참가 규칙과는 별개입니다. 비공개 또는 초대 전용 회의실은 모든 사람에게 참가 권한을 부여하지 않고도 기억하기 쉬운 별칭을 지정할 수 있습니다. 공용 커뮤니티 회의실의 경우 주소를 널리 공유하기 전에 디렉터리 설정과 회의실 참가 규칙을 모두 확인하세요.
관리자와 자동화 도구는 표준 Matrix 클라이언트-서버 API를 사용할 수 있습니다 . 아래 예제는 동일한 별칭을 생성합니다. Element가 이미 생성된 경우에는 실행 하지 마십시오#support:example.com . 실제 방 ID와 홈서버의 별칭 정책에 따라 허용된 사용자의 유효한 액세스 토큰으로 대체하십시오. 토큰은 암호처럼 취급해야 합니다.
curl --request PUT \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{"room_id":"!yourRoomId:example.com"}' \
'https://matrix.example.com/_matrix/client/v3/directory/room/%23support%3Aexample.com'
요청이 성공하면 200빈 JSON 객체와 함께 HTTP 응답이 반환됩니다. `<name>` %23과 `<name>` 부분은 각각 `<name>` 과 ` <name>` %3A의 URL 인코딩입니다 . PUT 요청은 별칭과 방을 매핑하는 작업을 수행하며, 방의 정식 별칭을 반드시 변경하는 것은 아닙니다 . API를 통해서만 별칭을 생성한 후, 해당 별칭을 기본 주소로 표시하려면 Element의 기본 주소 컨트롤로 돌아가십시오. 공유 셸 명령, 스크린샷 또는 지원 티켓에 실제 베어러 토큰을 붙여넣지 마십시오.#:
디렉터리 조회에는 로그인이 필요하지 않습니다. URL 호스트를 사용자가 접근 가능한 클라이언트 API 엔드포인트로 바꾸십시오.
curl --fail-with-body --silent --show-error \
'https://matrix.example.com/_matrix/client/v3/directory/room/%23support%3Aexample.com'
응답에는 room_id대상 회의실과 일치하는 값과 servers배열이 포함되어야 합니다. 이는 별칭 확인 기능을 테스트하는 것이지, 모든 원격 서버가 사용자 서버와 연동될 수 있는지 여부를 테스트하는 것이 아닙니다.
Synapse의 설정이 올바른지 확인하십시오 server_name. 이미 운영 중인 서버에서 별칭을 변경하려고 해당 값을 수정하지 마십시오. 서버의 ID와 기존 Matrix 식별자는 이 값에 따라 결정됩니다. 새롭게 구축할 경우, 사용자와 회의실을 생성하기 전에 원하는 서버 이름을 미리 정하십시오. 이미 다른 이름으로 운영 중인 경우, 새 별칭을 소유할 적절한 이름의 홈 서버를 마련할 수 없다면 기존 별칭 도메인을 사용하는 것이 더 안전할 수 있습니다.
HTTP 오류 403는 일반적으로 권한이 거부되었거나 서버 정책이 적용되었음을 나타냅니다. 사용자의 방 권한과 Synapse의 alias_creation_rules정책(규칙은 순서대로 평가되며, 명시적으로 비어 있는 목록은 모든 별칭 생성을 방지합니다)을 확인하십시오. HTTP 오류 409는 해당 별칭이 이미 존재함을 의미합니다. 기존 매핑을 덮어쓰기 전에 다른 로컬 파트를 선택하거나 기존 매핑을 조사하십시오. Synapse 구성 설명서에서 별칭 정책 옵션을 확인할 수 있습니다.
먼저 로컬에서 별칭이 제대로 확인되는지 확인하십시오. 로컬 조회는 성공했지만 외부 검색이 실패하는 경우, HTTPS 인증서, 관련 위임 및 노출된 페더레이션 리스너를 포함하여 별칭 도메인/.well-known/matrix/server 에 대한 페더레이션을 검사하십시오 . 클라이언트 트래픽에 사용되는 호스트 이름은 다른 Matrix 서버 이름에 대한 페더레이션을 자동으로 설정하지 않습니다. Matrix 서버 간 API에서 서버 검색 및 위임에 대한 설명을 참조하십시오. 또한 원격 사용자의 참여가 허용되는지 확인하십시오. 초대 전용 회의실이라도 참여가 거부되더라도 성공적으로 확인될 수 있습니다.
#support:example.com 아래에 표시 되고 요소에서 의도된 기본 주소 로 표시되는지 확인하십시오 .room_id에 표시된 ID와 비교하십시오.https://matrix.to/#/%23support%3Aexample.com. 링크가 예상대로 채팅방으로 연결될 것입니다. 해당 계정으로 채팅방에 참여할 수 있는지 여부는 채팅방의 접속 규칙에 따라 달라집니다.Matrix의 룸 별칭과 matrix.to 형식 참조는 인코딩된 공유 링크 형식을 정의합니다. 세 가지 검사를 모두 통과하면 새 주소를 공유할 준비가 되며 원래 룸 ID는 변경되지 않습니다.
Element 또는 Matrix API를 사용하여 권한, Synapse 명명 및 연동을 확인하고 Matrix 회의실에 도메인에서 쉽게 공유할 수 있는 주소를 부여하세요.
coturn과 Synapse를 일치하는 TURN 자격 증명으로 구성하고, 필요한 릴레이 포트를 열고, Matrix 클라이언트가 릴레이 후보를 가져올 수 있는지 확인합니다.
Docker Compose, PostgreSQL, 비공개 설정 파일, 그리고 HTTPS를 통해 노출하기 전에 필요한 검사 기능을 사용하여 Synapse 홈 서버를 영구적으로 설정합니다.
Element 웹 배포에 브랜드 이름, 사용자 지정 색상 및 로그인 자산을 설정하는 동시에 Element 브랜드로 유지되는 부분을 파악하세요.
Synapse가 프로세스별 파일 열기 제한에 도달했는지 진단하고, 해당 서비스 또는 워커에 대한 systemd 드롭인을 설정하고, 실제 제한을 확인합니다.
오류가 특정 브라우저 또는 특정 이벤트에만 국한되는지 확인한 다음, Element의 복구 키 또는 신뢰할 수 있는 장치를 사용하여 암호화된 나머지 기록을 손상시키지 않고 복구할 수 있습니다.
Synapse의 기록 및 미디어 삭제 API 또는 보존 설정을 사용하여 오래된 데이터를 안전하게 제거한 다음 완료 여부와 디스크 공간 복구를 확인하십시오.
최신 라이브러리를 설치하고, 전용 Matrix 계정을 연결한 다음, 더욱 안전한 자격 증명 처리와 명확한 테스트를 포함하는 간단한 !echo 봇을 실행하세요.
등록, 로그인 및 테스트가 각각 다른 세 개의 Mautrix 브리지를 설정하여 Docker 네트워킹, 계정 정책 및 동기화 관련 예상치 못한 문제를 방지하세요.
Synapse 저장소를 채우는 항목을 찾고, 안전한 미디어 보존 설정을 지정하고, 디스크에서 파일을 직접 삭제하지 않고 원격 캐시를 정리하세요.