Um einem Matrix-Raum eine Adresse wie z. B. „/matrix“ zuzuweisen #support:example.com, erstellen Sie einen lokalen Raumalias auf dem Homeserver mit dem konfigurierten Servernamen „/matrix“ example.comund wählen Sie diesen Alias anschließend in Element als Hauptadresse des Raums aus. Sie benötigen keinen separaten DNS-Eintrag für jeden Raumalias, können aber die Aliasdomäne eines bestehenden Homeservers nicht einfach durch eine DNS-Eingabe ändern.
Verstehen, was die benutzerdefinierte Domäne steuert
Ein Raumalias ist eine lesbare Adresse, die zur permanenten Raum-ID eines Matrix-Raums aufgelöst wird . Diese ID beginnt üblicherweise mit einem Doppelpunkt !. Ein Raum kann mehrere Aliase haben, beispielsweise `<Raum1>` #support:example.comund #help:example.com`<Raum2>`, die beide auf denselben Raum verweisen. Der Text nach dem Doppelpunkt identifiziert den Homeserver, der für die Auflösung dieses Alias zuständig ist, nicht unbedingt den Server, auf dem alle Teilnehmer gehostet werden.
Matrix definiert Aliase im Format ` <matrix-name> #localpart:server-name. server_name...matrix.example.com#support:example.comexample.com
Überprüfen Sie die Voraussetzungen
- Ein funktionierender Matrix-Homeserver: Dieses Beispiel setzt voraus, dass Synapse bereits Client-API-Anfragen unter der angegebenen Adresse bearbeitet,
https://matrix.example.comwährend die Konfiguration server_namewie folgt lautet: example.com. Die Client-URL und der Servername können abweichen.
- Ein bestehender Raum: Erstellen Sie den Raum gegebenenfalls zuerst. Wählen Sie einen kurzen, einprägsamen Aliasnamen, z. B. „<Raumname>“
support. Ein Alias muss auf dem Server, der ihn erstellt, eindeutig sein.
- Berechtigung zur Adressverwaltung: Melden Sie sich mit einem Konto an, das berechtigt ist, den lokalen Alias zu erstellen und die Hauptadresse des Raums zu ändern. Die Alias-Erstellungsrichtlinie des Servers und die Leistungsstufen des Raums können diese Aktionen einschränken.
- Eine Möglichkeit zum Testen: Halten Sie ein zweites Matrix-Konto bereit, idealerweise auf einem anderen Homeserver, damit Sie die Erkennung unabhängig von Ihrer Administratorsitzung überprüfen können.
Erstellen Sie den Alias in Element Web
Der folgende Pfad entspricht der Terminologie für Raumeinstellungen in der Element-Raumeinstellungen-Dokumentation (Stand: Oktober 2026). Die Menüpositionen können je nach Element-Version und anderen Matrix-Clients variieren.
1. Öffnen Sie die Raumeinstellungen.
Öffnen Sie in Element Web oder Element Desktop den gewünschten Raum. Wählen Sie im Rauminfofeld „Raumeinstellungen“ oder verwenden Sie das Dreipunktmenü des Raums und wählen Sie „Einstellungen“ . Falls Sie die interne Raum-ID später zur Fehlerbehebung benötigen, finden Sie diese im Abschnitt „Erweitert“ . Kopieren Sie sie unverändert.
2. Lokale Adresse hinzufügen
Suchen Sie auf der Seite „Allgemeine Einstellungen“ nach „Raumadressen“ und anschließend nach „Lokale Adressen“ . Geben Sie den Alias-Lokalteil, z. B. „<alias>“ support, in das Feld „Raumadresse“ ein und wählen Sie „Hinzufügen “ oder die entsprechende Speicherfunktion. Überprüfen Sie, ob die vollständige Adresse „<alias>“ lautet #support:example.com. Endet sie stattdessen mit „ :matrix.example.com<alias>“, brechen Sie den Vorgang ab: Dies ist ein Problem mit dem Namen des Homeservers und kein Tippfehler, der in den Raumeinstellungen korrigiert werden kann.
3. Wählen Sie die Hauptadresse
Unter „Raumadressen“ finden Sie „Veröffentlichte Adressen“ . Legen Sie dort die Hauptadresse#support:example.com fest . Laut Element-Dokumentation wird die erste erstellte lokale Adresse normalerweise automatisch als Hauptadresse ausgewählt. Die explizite Auswahl ist hilfreich, wenn der Raum bereits mehrere Aliase besitzt.
Die Hauptadresse ist der kanonische Alias des Raums : die bevorzugte Adresse, die im Raumstatus angegeben wird. Das Erstellen eines Alias und das Auswählen des kanonischen Alias sind zwar verwandte, aber unterschiedliche Aktionen. Matrix unterstützt auch alternative angegebene Aliase. Ein kanonischer Alias sollte bereits vor seiner Angabe auf den betreffenden Raum verweisen.
4. Entscheiden Sie, ob der Raum in ein Verzeichnis aufgenommen werden soll.
Aktivieren Sie die Option „Diesen Raum im öffentlichen Raumverzeichnis veröffentlichen“ nur dann, wenn Sie die Verzeichnisauffindbarkeit tatsächlich wünschen. Das Festlegen einer Adresse macht einen Raum nicht automatisch öffentlich, und die Veröffentlichung eines Raums ist unabhängig von seinen Beitrittsregeln. Ein privater oder nur auf Einladung zugänglicher Raum kann einen einprägsamen Alias haben, ohne dass jeder die Berechtigung zum Beitritt erhält. Überprüfen Sie bei öffentlichen Community-Räumen sowohl die Verzeichniseinstellung als auch die Beitrittsregeln des Raums, bevor Sie die Adresse weitergeben.
Verwenden Sie die Matrix-API, wenn der Client die Adresse nicht hinzufügen kann.
Administratoren und Automatisierungstools können die standardmäßige Matrix Client-Server-API verwenden . Das folgende Beispiel erstellt denselben Alias; führen Sie es nicht#support:example.com aus, wenn das Element bereits erstellt wurde . Ersetzen Sie die Platzhalter durch die tatsächliche Raum-ID und ein gültiges Zugriffstoken für einen Benutzer, der gemäß der Alias-Richtlinie des Homeservers berechtigt ist. Behandeln Sie das Token wie ein Passwort.
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'
Eine erfolgreiche Anfrage liefert 200ein leeres JSON-Objekt als HTTP-Antwort. Die Teile ` %23<a>` und `<s> ` sind URL-kodiert für `<a> ` und `<s>` . Die PUT-Anfrage erstellt eine Alias-zu-Raum-Zuordnung; sie ändert nicht unbedingt den kanonischen Raumalias. Nach einer reinen API-Erstellung kehren Sie zur Hauptadressensteuerung von Element zurück, wenn dieser Alias als primäre Adresse verwendet werden soll. Fügen Sie niemals ein echtes Bearer-Token in einen gemeinsamen Shell-Befehl, einen Screenshot oder ein Support-Ticket ein.%3A#:
Überprüfen Sie, ob die Zuordnung aufgelöst wird.
Für die Verzeichnissuche ist keine Anmeldung erforderlich. Ersetzen Sie die URL-Hostadresse durch Ihren eigenen, zugänglichen Client-API-Endpunkt:
curl --fail-with-body --silent --show-error \
'https://matrix.example.com/_matrix/client/v3/directory/room/%23support%3Aexample.com'
Die Antwort sollte room_idden Zielraum und ein serversArray enthalten. Dies testet die Aliasauflösung, nicht die Kompatibilität aller Remote-Server mit Ihrem Server.
Beheben Sie die häufigsten Fehler
Der Alias hat die falsche Domain.
Überprüfen Sie die Konfiguration von Synapse server_name. Ändern Sie diesen Wert nicht auf einem bestehenden Server, um dessen Aliase umzubenennen: Seine Identität und bestehende Matrix-Kennungen hängen davon ab. Planen Sie bei einer Neuinstallation den gewünschten Servernamen, bevor Sie Benutzer und Räume erstellen. Wenn Sie bereits unter einem anderen Namen arbeiten, ist die Verwendung der tatsächlichen Alias-Domäne möglicherweise die sicherere Wahl, es sei denn, Sie können einen entsprechend benannten Homeserver einrichten, der die neuen Aliase verwaltet.
Erstellung schlägt mit Fehlercode 403 oder 409 fehl.
HTTP 403deutet in der Regel auf verweigerte Berechtigungen oder eine anwendbare Serverrichtlinie hin. Überprüfen Sie die Raumberechtigungen des Benutzers und die Synapse- alias_creation_rulesRegeln; diese werden der Reihe nach ausgewertet, und eine explizit leere Liste verhindert die Erstellung aller Aliase. HTTP 409bedeutet, dass der Alias bereits existiert. Wählen Sie einen anderen Localpart oder untersuchen Sie die bestehende Zuordnung, anstatt sie blind zu überschreiben. Die Optionen der Aliasrichtlinie sind im Synapse-Konfigurationshandbuch dokumentiert.
Spieler auf anderen Servern können den Raum nicht finden.
Prüfen Sie zunächst, ob der Alias lokal aufgelöst werden kann. Wenn die lokale Suche erfolgreich ist, die externe Suche jedoch fehlschlägt, überprüfen Sie die Föderation für die Aliasdomäne , einschließlich HTTPS-Zertifikate, die entsprechende /.well-known/matrix/serverDelegierung und den freigegebenen Föderationslistener. Ein für den Client-Datenverkehr verwendeter Hostname stellt nicht automatisch eine Föderation für einen anderen Matrix-Servernamen her. Die Matrix Server-Server-API beschreibt die Servererkennung und -delegierung. Stellen Sie außerdem sicher, dass Remote-Benutzer beitreten dürfen; ein Raum, der nur auf Einladung zugänglich ist, kann zwar erfolgreich aufgelöst werden, aber den Beitritt verweigern.
Benutzerdefinierte Zimmeradresse überprüfen
- Prüfen Sie, ob diese Adresse
#support:example.comunter „Lokale Adressen“ und als die gewünschte Hauptadresse im Element angezeigt wird.
- Führen Sie die oben genannte GET-Anfrage für das nicht authentifizierte Verzeichnis aus und vergleichen Sie das Ergebnis
room_idmit der ID, die in den erweiterten Raumeinstellungen von Element angezeigt wird.
- Versuchen Sie, die URL von einem anderen Konto aus zu öffnen
https://matrix.to/#/%23support%3Aexample.com. Der Link sollte zum erwarteten Raum führen; ob das Konto beitreten kann, hängt jedoch von den Zugriffsregeln des Raums ab.
Die Referenz auf den Raumalias und das Matrix.to-Format in Matrix definiert das kodierte Freigabelink-Format. Wenn alle drei Prüfungen erfolgreich sind, kann die neue Adresse freigegeben werden, während die ursprüngliche Raum-ID unverändert bleibt.