Jak skonfigurować niestandardowe aliasy pomieszczeń macierzy w swojej domenie

Alias ​​pokoju w Matrix nadaje pokojowi adres czytelny dla człowieka, taki jak #support:example.org. Część po dwukropku to nazwa serwera domowego , czyli domena będąca właścicielem przestrzeni nazw aliasu. Nie jest to dowolna etykieta domeny, którą można zmienić, dodając rekord DNS. Aby korzystać z własnej domeny, serwer domowy musi być skonfigurowany z tą domeną jako nazwą serwera; federację można następnie delegować do osobnego hosta.

W tym przewodniku użyto example.orgdomeny, matrix.example.orghosta Synapse i #support:example.orgaliasu docelowego. Zastąp te symbole zastępcze własnymi wartościami. Przewodnik koncentruje się na Synapse hostowanym samodzielnie. Jeśli korzystasz z hostowanego dostawcy Matrix, sprawdź, czy pozwala on na użycie niestandardowej nazwy serwera; wiele kont hostowanych może tworzyć aliasy tylko w domenie dostawcy.

Co oznacza alias pokoju Matrix

Serwer domowy to serwer Matrix, który przechowuje dane o pokojach użytkowników i łączy się z innymi serwerami. Identyfikator pokoju , taki jak !opaqueid:example.org, technicznie identyfikuje pokój. Alias ​​pokoju , taki jak #support:example.org, to czytelny wpis w katalogu, który odpowiada identyfikatorowi pokoju i liście serwerów, które mogą pomóc użytkownikowi dołączyć.

Alias ​​nie zmienia nazwy pokoju, jego prywatności ani nie gwarantuje, że pojawi się on w publicznym katalogu pokoi. Są to osobne ustawienia pokoju. Pokój może mieć wiele aliasów. Alias ​​kanoniczny to preferowany adres wyświetlany lub współdzielony przez klientów; jest on publikowany jako stan pokoju, podczas gdy serwer domowy utrzymuje mapowanie aliasów na pokoje. Specyfikacja Matrix ostrzega, że ​​mapowania aliasów mogą się zmieniać, dlatego przed użyciem należy ustalić adres.

Zanim zaczniesz

• Kontroluj domenę, której chcesz używać, na przykład example.org, w tym możliwość obsługi treści HTTPS w tej domenie.
• Uruchom serwer domowy, taki jak Synapse, z parametrem Matrix server_nameustawionym na example.org. Ta wartość jest wybierana podczas konfiguracji serwera i nie powinna być później przypadkowo zmieniana: identyfikatory użytkowników i aliasy używają jej jako przestrzeni nazw.
• Posiadaj działający certyfikat TLS i trasę federacyjną. Delegowany host Matrix, taki jak matrix.example.org, musi przedstawić ważny certyfikat.
• Dołącz do pokoju i uzyskaj uprawnienia wymagane do zmiany jego adresów. Synapse ma również reguły po stronie serwera, które mogą zezwalać lub blokować tworzenie aliasów.

Jeśli serwer działa już pod inną nazwą, na przykład provider.net, utworzenie #support:example.orgnie jest skrótem do mapowania domeny. Zapytaj dostawcę o obsługę niestandardowych domen lub zaplanuj osobne wdrożenie i migrację serwera domowego. Matrix nie definiuje procesu, w którym jeden serwer domowy tworzy aliasy w przestrzeni nazw innego serwera.

Krok 1: Wybierz nazwę serwera i trasę federacyjną

Zdecyduj, która nazwa pojawi się po dwukropku przed skonfigurowaniem serwera domowego. W tym przykładzie Synapse używa example.orgnazwy serwera, podczas gdy usługi klienta i federacji działają pod adresem matrix.example.org. Rekord DNS wysyła ruch do matrix.example.orghosta lub odwrotnego serwera proxy. Sam rekord DNS nie ustanawia przestrzeni nazw aliasów; robi to nazwa serwera Synapse.

Gdy serwer domowy nie jest bezpośrednio dostępny na example.orgdomyślnym porcie federacyjnym 8448, Matrix potrzebuje sposobu na odnalezienie swojego punktu końcowego federacyjnego. Jedną z powszechnych metod jest delegowanie .well-known : krótka odpowiedź JSON HTTPS w domenie nazwy serwera kieruje ruch federacyjny do rzeczywistego hosta Matrix. Obsługiwać to należy pod adresem https://example.org/.well-known/matrix/server:

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

Upewnij się, że odpowiedź jest poprawnym plikiem JSON, obsługiwanym przez HTTPS, a host docelowy posiada ważny certyfikat i kieruje żądania federacji do Synapse. Port można pominąć, jeśli punkt końcowy federacji używa portu 8448; w tym przykładzie port 443 jest jawny. Jeśli Synapse obsługuje już federację w domenie nazwy serwera na porcie 8448, delegowanie może nie być potrzebne. /.well-known/matrix/clientPlik skierowany do klienta to inny mechanizm wykrywania i nie zastępuje delegowania serwera.

Aktualna dokumentacja konfiguracji Synapse zawiera serve_server_wellknownopcję dla przypadków, w których żądania do domeny o nazwie serwera na porcie 443 są kierowane do Synapse. Użyj tej opcji tylko wtedy, gdy Twój serwer proxy i routing domeny spełniają udokumentowane wymagania. W przeciwnym razie skonfiguruj odpowiedź JSON na swoim serwerze WWW lub serwerze proxy.

Krok 2: Sprawdź zasady dotyczące aliasów w Synapse

Synapse może ograniczyć, kto może tworzyć aliasy i które adresy pokoi są dozwolone. W programie homeserver.yamlsprawdź, alias_creation_rulesczy żądanie utworzenia aliasu jest odrzucane. Synapse ocenia skonfigurowane reguły w kolejności; pierwsza pasująca reguła decyduje o żądaniu, a jeśli żadna reguła nie pasuje, żądanie jest odrzucane. Pusta lista odrzuca wszystkie żądania utworzenia aliasu. Lista null lub pominięta domyślnie zezwala na tworzenie aliasów, z zastrzeżeniem innych kontroli.

Zaznacz również opcję require_membership_for_aliases, która domyślnie wymaga obecności użytkownika w pokoju. Jeśli zmieniasz konfigurację Synapse, postępuj zgodnie ze standardową procedurą walidacji i ponownego uruchamiania wdrożenia oraz unikaj luzowania zasad w szerszym zakresie niż to konieczne. Poziomy mocy pokoju i dostępne opcje sterowania klienta również mogą wpływać na to, czy zwykły członek może ustawić preferowany alias.

Krok 3: Utwórz alias dla pokoju

Dołącz do wybranego pokoju w kliencie Matrix i otwórz jego ustawienia. Poszukaj sekcji adresu lub aliasu; sformułowania i układ klienta mogą się różnić w zależności od wersji. Wprowadź pełny adres, łącznie z domeną główną #i domeną serwera domowego, na przykład #support:example.org. Dodaj go jako adres pokoju i, jeśli klient oferuje taką opcję, ustaw go jako alias kanoniczny lub preferowany. Zapisz zmianę.

Jeśli Twój klient nie udostępnia kontrolki aliasu, mapowanie może zostać utworzone za pomocą żądania API klient-serwer. Uwierzytelniony PUT /_matrix/client/v3/directory/room/{roomAlias}punkt końcowy wymaga identyfikatora pokoju w treści żądania. Na przykład, autoryzowany użytkownik pokoju lub konto serwera może wysłać żądanie do serwera domowego, który jest właścicielem 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"}'

Zastąp przykładowy identyfikator pokoju dokładnym identyfikatorem pokoju i użyj ważnego tokena dostępu z wymaganymi uprawnieniami. Traktuj token jak hasło: nie publikuj go, nie wklejaj do posta pomocy technicznej ani nie zatwierdzaj w systemie kontroli wersji. Znaki procentowe w kodzie URL #i :ścieżce HTTP. Pomyślna odpowiedź oznacza, że ​​mapowanie zostało utworzone. Odpowiedź „już istnieje” oznacza, że ​​nazwa jest zajęta; przed zmianą lub usunięciem czegokolwiek upewnij się, kto jest jej właścicielem.

Krok 4: Zweryfikuj adres i udostępnij go

Rozwiąż alias za pomocą publicznego interfejsu API klient-serwer. To wyszukiwanie nie wymaga uwierzytelnienia:

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

Prawidłowa odpowiedź powinna zawierać oczekiwany adres room_idoraz serverslistę. Porównaj zwrócony identyfikator pokoju z zamierzonym pokojem. Błąd 404 oznacza, że ​​alias nie ma mapowania na serwerze obsługującym tę przestrzeń nazw. Błąd 400 wskazuje na nieprawidłowo sformatowany adres. Następnie przetestuj pełny alias na drugim koncie Matrix lub kliencie, aby upewnić się, że pokój został rozwiązany i można go dołączyć zgodnie z jego zasadami dołączania.

Jeśli ustawisz alias kanoniczny, sprawdź ponownie szczegóły pokoju i upewnij się, że preferowany adres to ten, który chcesz opublikować. Udostępnij alias lub stały link Matrix dopiero po potwierdzeniu, że prowadzi on do właściwego pokoju. Pamiętaj, że publiczny alias nie sprawia, że ​​pokój prywatny staje się publiczny; użytkownik nadal potrzebuje pozwolenia, aby do niego dołączyć.

Typowe problemy, których należy unikać

• Korzystanie z domeny, której serwer domowy nie jest właścicielem: Nazwa serwera w aliasie musi być zgodna z przestrzenią nazw serwera domowego, która go tworzy. Sama nazwa CNAME DNS nie może autoryzować domeny innego serwera.
• Pomieszanie domeny i hosta: example.org może to być alias przestrzeni nazw, a matrix.example.orghost usługi. Ustaw nazwę serwera Synapse i delegację celowo.
• Umieszczenie pliku wykrywania klienta w niewłaściwym miejscu: Delegacja federacyjna używa /.well-known/matrix/server. Plik wykrywania klienta ma inną ścieżkę i przeznaczenie.
• Zakładając, że alias publikuje pokój publicznie: Rozwiązywanie aliasów i publikacja publicznego katalogu pokoi to oddzielne operacje regulowane przez oddzielne zasady.
• Zmiana nazwy serwera w istniejącym wdrożeniu: istniejące identyfikatory Matrix zależą od tej przestrzeni nazw. Traktuj zmianę domeny jako migrację architektoniczną, a nie szybkie ustawienie aliasu.
• Udostępnianie bez sprawdzania mapowania: Rozwiąż alias i porównaj zwrócony identyfikator pokoju przed jego opublikowaniem. Czytelny adres jest wygodny, ale to mapowanie serwera decyduje, dokąd prowadzi.

Szczegóły protokołu można znaleźć w dokumencie Matrix identifier and alias format oraz w interfejsie API aliasów pomieszczeń Matrix . Informacje na temat konfiguracji Synapse można znaleźć w podręczniku Element dotyczącym delegowania federacji oraz instrukcji konfiguracji . Opcje Synapse i ekrany klienta mogą się zmieniać między wersjami; zapoznaj się z dokumentacją używanej wersji.