도메인에서 사용자 지정 매트릭스 룸 별칭을 구성하는 방법

Matrix 룸 별칭은 룸에 `.`과 같은 사람이 읽기 쉬운 주소를 부여합니다 #support:example.org. 콜론 뒤의 부분은 홈서버의 서버 이름 , 즉 별칭 네임스페이스를 소유하는 도메인입니다. 이는 DNS 레코드를 추가하여 변경할 수 있는 임의의 도메인 레이블이 아닙니다. 자체 도메인을 사용하려면 홈서버를 해당 도메인으로 서버 이름을 구성해야 하며, 그 후에 페더레이션을 별도의 호스트에 위임할 수 있습니다.

이 가이드에서는 example.org도메인, matrix.example.orgSynapse 호스트, #support:example.org대상 별칭으로 각각 , , 를 사용합니다. 이러한 자리 표시자는 실제 값으로 바꿔야 합니다. 이 가이드는 자체 호스팅 Synapse를 기준으로 작성되었습니다. 호스팅 Matrix 제공업체를 사용하는 경우, 사용자 지정 서버 이름을 사용할 수 있는지 확인하십시오. 많은 호스팅 계정은 제공업체의 도메인으로만 별칭을 생성할 수 있습니다.

매트릭스 룸 가명이 하는 일

홈 서버 는 사용자의 방 데이터를 저장하고 다른 서버에 연결하는 Matrix 서버입니다. 방 ID (예: )는 !opaqueid:example.org방을 기술적으로 식별하는 데 사용됩니다. 방 별칭( 예: #support:example.org)은 방 ID와 사용자가 방에 참여하는 데 도움이 되는 서버 목록으로 연결되는 읽기 가능한 디렉터리 항목입니다.

별칭은 방 이름을 바꾸거나, 개인 정보 보호 설정을 변경하거나, 공개 방 목록에 표시되도록 보장하지 않습니다. 이러한 설정은 별도의 방 설정입니다. 방은 여러 개의 별칭을 가질 수 있습니다. 정식 별칭은 클라이언트가 표시하거나 공유하는 기본 주소이며, 방 상태로 게시됩니다. 홈서버는 별칭과 방 사이의 매핑을 유지 관리합니다. Matrix 사양에서는 별칭 매핑이 변경될 수 있으므로 주소를 사용하기 전에 반드시 확인해야 한다고 경고합니다.

시작하기 전에

원하는 도메인을 직접 제어할 수 있으며, example.org해당 도메인에서 HTTPS 콘텐츠를 제공할 수 있는 기능도 포함됩니다.
Synapse와 같은 홈서버를 실행할 때 Matrix 값을 로 server_name설정하십시오 example.org. 이 값은 서버 설정 시 선택되며 나중에 임의로 변경해서는 안 됩니다. 사용자 ID와 별칭은 이 값을 네임스페이스로 사용합니다.
유효한 TLS 인증서와 페더레이션 경로가 있어야 합니다. 위임된 Matrix 호스트(예: matrix.example.org)는 유효한 인증서를 제시해야 합니다.
해당 방에 참여하고 방 주소를 변경하는 데 필요한 권한이 있어야 합니다. Synapse에는 별칭 생성을 허용하거나 거부할 수 있는 서버 측 규칙도 있습니다.

예를 들어 서버가 이미 다른 서버 이름으로 실행 중인 경우, 새 도메인 provider.net을 생성하는 #support:example.org것은 도메인 매핑의 지름길이 아닙니다. 공급업체에 사용자 지정 도메인 지원에 대해 문의하거나 별도의 홈서버 배포 및 마이그레이션을 계획하십시오. Matrix는 한 홈서버가 다른 서버의 네임스페이스에 별칭을 생성하는 프로세스를 정의하지 않습니다.

1단계: 서버 이름과 페더레이션 경로를 선택합니다.

홈서버를 설정하기 전에 콜론 뒤에 표시될 이름을 결정하세요. 이 예에서 Synapse는 example.org서버 이름으로 를 사용하고, 클라이언트 및 페더레이션 서비스는 에서 실행됩니다 matrix.example.org. DNS 레코드는 에 대한 트래픽을 matrix.example.org호스트 또는 리버스 프록시로 보냅니다. DNS 레코드 자체만으로는 별칭 네임스페이스를 설정하지 않으며, Synapse의 서버 이름이 이를 수행합니다.

홈서버에 기본 페더레이션 포트 8448로 직접 연결할 수 없는 경우 example.org, Matrix는 페더레이션 엔드포인트를 찾을 방법이 필요합니다. 일반적인 방법 중 하나는 .well-known 위임 입니다 . 서버 이름 도메인으로 전송되는 작은 HTTPS JSON 응답이 페더레이션 트래픽을 실제 Matrix 호스트로 안내합니다. 이 응답을 다음 주소에서 제공하세요 https://example.org/.well-known/matrix/server.

{
  "m.server": "matrix.example.org:443"
}

응답이 유효한 JSON 형식이고 HTTPS를 통해 제공되는지, 그리고 대상 호스트에 유효한 인증서가 있고 페더레이션 요청을 Synapse로 라우팅하는지 확인하십시오. 페더레이션 엔드포인트에서 8448 포트를 사용하는 경우 포트를 생략할 수 있습니다. 이 예에서는 443 포트가 명시적으로 사용되었습니다. Synapse가 이미 서버 이름 도메인의 8448 포트에서 페더레이션을 제공하는 경우 위임이 필요하지 않을 수 있습니다. 클라이언트 측 /.well-known/matrix/client파일은 별도의 검색 메커니즘이며 서버 위임을 대체하는 것이 아닙니다.

Synapse의 최신 구성 문서에는 serve_server_wellknown서버 이름 도메인의 443번 포트로 들어오는 요청을 Synapse로 라우팅하는 옵션이 포함되어 있습니다. 이 옵션은 프록시 및 도메인 라우팅이 문서에 명시된 요구 사항을 충족하는 경우에만 사용하십시오. 그렇지 않은 경우 웹 서버 또는 프록시에서 JSON 응답을 구성하십시오.

2단계: Synapse의 별칭 정책을 확인합니다.

Synapse는 별칭 생성 권한과 허용되는 회의실 주소를 제한할 수 있습니다. 별칭 생성 요청이 거부되는지 여부를 확인하려면 해당 homeserver.yaml설정을 살펴보세요 alias_creation_rules. Synapse는 구성된 규칙을 순서대로 평가하며, 일치하는 첫 번째 규칙이 요청을 처리하고, 일치하는 규칙이 없으면 요청을 거부합니다. 목록이 비어 있으면 모든 별칭 생성 요청이 거부됩니다. 목록이 null이거나 생략된 경우, 다른 검사를 거쳐 기본적으로 별칭 생성이 허용됩니다.

또한 require_membership_for_aliases사용자가 회의실에 있어야 한다는 기본 설정도 확인하십시오. Synapse 구성을 변경하는 경우 배포의 일반적인 유효성 검사 및 재시작 프로세스를 따르고 필요 이상으로 정책을 완화하지 마십시오. 회의실의 전력 수준과 클라이언트에서 사용 가능한 제어 기능 또한 일반 구성원이 선호하는 별칭을 설정할 수 있는지 여부에 영향을 미칠 수 있습니다.

3단계: 방에 대한 별칭을 만드세요

Matrix 클라이언트를 사용하여 원하는 방에 접속하고 방 설정을 엽니다. 주소 또는 별칭 섹션을 찾습니다. 클라이언트 버전에 따라 문구와 레이아웃이 다를 수 있습니다. #홈서버 도메인을 포함한 전체 주소를 입력합니다(예: ) #support:example.org. 해당 주소를 방 주소로 추가하고, 클라이언트에서 해당 옵션을 제공하는 경우 표준 또는 기본 별칭으로 설정합니다. 변경 사항을 저장합니다.

클라이언트가 별칭 제어 기능을 제공하지 않는 경우, 클라이언트-서버 API 요청을 통해 매핑을 생성할 수 있습니다. 인증된 PUT /_matrix/client/v3/directory/room/{roomAlias}엔드포인트는 요청 본문에 방 ID를 포함해야 합니다. 예를 들어, 권한이 부여된 방 구성원 또는 서버 계정은 해당 방을 소유한 홈서버에 다음과 같은 요청을 보낼 수 있습니다 example.org.

curl -X PUT \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org" \
  -H "Authorization: Bearer $MATRIX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"room_id":"!yourRoomId:example.org"}'

샘플 룸 ID를 실제 룸 ID로 바꾸고, 필요한 권한이 있는 유효한 액세스 토큰을 사용하십시오. 토큰은 암호처럼 취급해야 합니다. 토큰을 게시하거나, 지원 게시물에 붙여넣거나, 소스 코드 관리 시스템에 저장하지 마십시오. URL 인코딩 #및 :HTTP 경로의 퍼센트(%)는 이스케이프 처리됩니다. 성공 응답은 매핑이 생성되었음을 나타냅니다. "이미 존재합니다"라는 응답은 해당 이름이 이미 사용 중임을 의미합니다. 변경 또는 삭제하기 전에 소유자를 확인하십시오.

4단계: 주소를 확인하고 공유하세요

공개 클라이언트-서버 API를 사용하여 별칭을 확인합니다. 이 조회에는 인증이 필요하지 않습니다.

curl -i \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org"

성공적인 응답에는 예상 결과 room_id와 servers목록이 포함되어야 합니다. 반환된 회의실 ID를 의도한 회의실 ID와 비교하십시오. 404 오류는 해당 네임스페이스를 처리하는 서버에 해당 별칭에 대한 매핑이 없음을 의미합니다. 400 오류는 주소 형식이 잘못되었음을 나타냅니다. 그런 다음 두 번째 Matrix 계정 또는 클라이언트에서 전체 별칭을 테스트하여 회의실이 제대로 확인되고 참가 규칙에 따라 참가할 수 있는지 확인하십시오.

정식 별칭을 설정한 경우, 방 정보를 다시 확인하고 기본 주소가 게시하려는 주소와 일치하는지 확인하세요. 별칭이나 Matrix 영구 링크를 공유하기 전에 해당 주소가 올바른 방으로 연결되는지 확인해야 합니다. 공개 별칭을 설정한다고 해서 비공개 방이 공개되는 것은 아니며, 사용자는 여전히 방에 참여할 권한이 필요하다는 점을 기억하세요.

흔히 발생하는 문제점을 피하는 것이 중요합니다

홈서버가 소유하지 않은 도메인을 사용하는 경우: 별칭의 서버 이름은 해당 별칭을 생성한 홈서버 네임스페이스와 일치해야 합니다. DNS CNAME만으로는 다른 서버의 도메인을 인증할 수 없습니다.
도메인과 호스트를 혼동하지 마세요. example.org 는 별칭 네임스페이스이고 는 matrix.example.org서비스 호스트일 수 있습니다. Synapse 서버 이름과 위임 설정을 신중하게 지정하세요.
클라이언트 검색 파일을 잘못된 위치에 두었습니다. 페더레이션 위임은 .을 사용합니다 /.well-known/matrix/server. 클라이언트 검색 파일은 경로와 용도가 다릅니다.
별칭이 방을 공개적으로 게시한다고 가정할 때: 별칭 확인 및 공개 방 디렉토리 게시 작업은 별도의 정책에 따라 관리되는 별개의 작업입니다.
기존 배포 환경에서 서버 이름을 변경하는 경우: 기존 Matrix ID는 해당 네임스페이스에 종속됩니다. 도메인 변경은 간단한 별칭 설정이 아닌 아키텍처 마이그레이션으로 간주해야 합니다.
매핑 확인 없이 공유하기: 게시하기 전에 별칭을 확인하고 반환된 방 ID를 비교하세요. 읽기 쉬운 주소도 편리하지만, 서버의 매핑이 해당 주소가 연결되는 위치를 결정합니다.

프로토콜 세부 정보는 Matrix 식별자 및 별칭 형식 과 Matrix 룸 별칭 API를 참조하십시오 . Synapse 설정에 대해서는 Element의 페더레이션 위임 가이드 및 구성 설명서를 참조하십시오 . Synapse 옵션 및 클라이언트 화면은 릴리스 간에 변경될 수 있으므로 사용 중인 버전의 설명서를 확인하십시오.