So konfigurieren Sie benutzerdefinierte Matrix-Raumaliase in Ihrer Domäne

Ein Matrix-Raumalias weist einem Raum eine lesbare Adresse zu, z. #support:example.orgB. ` <Raumname> . ...

Diese Anleitung verwendet example.orgals Domain, matrix.example.orgals Synapse-Host und #support:example.orgals Zielalias. Ersetzen Sie diese Platzhalter durch Ihre eigenen Werte. Sie konzentriert sich auf selbstgehostetes Synapse. Wenn Sie einen gehosteten Matrix-Anbieter verwenden, prüfen Sie, ob dieser die Verwendung eines benutzerdefinierten Servernamens zulässt; viele gehostete Konten erlauben die Erstellung von Aliasen nur unter der Domain des Anbieters.

Was ein Matrix-Raumalias bewirkt

Ein Homeserver ist der Matrix-Server, der die Raumdaten der Benutzer speichert und Verbindungen zu anderen Servern herstellt. Eine Raum-ID , z. B. „Raum-ID“, !opaqueid:example.orgidentifiziert einen Raum technisch. Ein Raum-Alias , z. B. „ Raum-Alias #support:example.org“, ist ein lesbarer Verzeichniseintrag, der eine Raum-ID und eine Liste von Servern enthält, die einem Benutzer beim Beitritt helfen können.

Ein Alias ​​ändert weder den Namen des Raums noch dessen Privatsphäre oder garantiert, dass er in einem öffentlichen Raumverzeichnis erscheint. Dies sind separate Raumeinstellungen. Ein Raum kann mehrere Aliase haben. Ein kanonischer Alias ​​ist die bevorzugte Adresse, die Clients angezeigt oder weitergegeben wird; er wird als Raumstatus veröffentlicht, während der Homeserver die Zuordnung von Alias ​​zu Raum verwaltet. Die Matrix-Spezifikation weist darauf hin, dass sich Alias-Zuordnungen ändern können. Daher sollte eine Adresse vor der Verwendung überprüft werden.

Bevor Sie beginnen

• Sie haben die Kontrolle über die Domain, die Sie verwenden möchten, z. B. example.org, einschließlich der Möglichkeit, HTTPS-Inhalte unter dieser Domain bereitzustellen.
• Betreiben Sie einen Homeserver wie Synapse mit der Matrix- server_nameEinstellung „“ example.org. Dieser Wert wird bei der Servereinrichtung festgelegt und sollte später nicht ohne Weiteres geändert werden: Benutzer-IDs und Aliase verwenden ihn als Namensraum.
• Sie benötigen ein funktionierendes TLS-Zertifikat und eine funktionierende Verbundroute. Der delegierte Matrix-Host, z. B. matrix.example.org, muss ein gültiges Zertifikat vorweisen.
• Sie müssen dem Raum beitreten und über die erforderlichen Berechtigungen verfügen, um dessen Adressen zu ändern. Synapse bietet außerdem serverseitige Regeln, die die Erstellung von Aliasen zulassen oder unterbinden können.

Wenn der Server bereits unter einem anderen Servernamen läuft, ist provider.netdas Erstellen #support:example.orgeines solchen Namens keine einfache Lösung für die Domänenzuordnung. Fragen Sie Ihren Anbieter nach Unterstützung für benutzerdefinierte Domänen oder planen Sie eine separate Bereitstellung und Migration Ihrer Homeserver. Matrix definiert kein Verfahren, mit dem ein Homeserver Aliase im Namespace eines anderen Servers erstellen kann.

Schritt 1: Servernamen und Verbundroute auswählen

Entscheiden Sie vor der Einrichtung des Homeservers, welcher Name nach dem Doppelpunkt erscheinen soll. In diesem Beispiel verwendet Synapse example.orgals Servernamen, während Client- und Verbunddienste unter laufen matrix.example.org. Ein DNS-Eintrag leitet den Datenverkehr für matrix.example.organ den Host oder Reverse-Proxy weiter. Der DNS-Eintrag allein legt den Alias-Namensraum nicht fest; dies geschieht durch den Servernamen von Synapse.

Wenn der Homeserver nicht direkt über example.orgden Standard-Federationsport 8448 erreichbar ist, benötigt Matrix eine Möglichkeit, seinen Federation-Endpunkt zu ermitteln. Eine gängige Methode ist die .well-known-Delegierung : Eine kleine HTTPS-JSON-Antwort unter der Servernamensdomäne leitet den Federation-Traffic an den eigentlichen Matrix-Host weiter. Stellen Sie diese unter folgender Adresse bereit https://example.org/.well-known/matrix/server:

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

Stellen Sie sicher, dass die Antwort gültiges JSON ist, über HTTPS bereitgestellt wird und der Zielhost über ein gültiges Zertifikat verfügt und Verbundanfragen an Synapse weiterleitet. Der Port kann weggelassen werden, wenn der Verbundendpunkt Port 8448 verwendet; in diesem Beispiel ist Port 443 explizit angegeben. Wenn Synapse den Verbund bereits über die Servernamensdomäne auf Port 8448 bereitstellt, ist eine Delegierung möglicherweise nicht erforderlich. Die clientseitige /.well-known/matrix/clientDatei ist ein anderer Erkennungsmechanismus und ersetzt nicht die Serverdelegierung.

Die aktuelle Konfigurationsdokumentation von Synapse enthält eine serve_server_wellknownOption für Fälle, in denen Anfragen an die Servernamensdomäne auf Port 443 an Synapse weitergeleitet werden. Verwenden Sie diese Option nur, wenn Ihr Proxy und das Domain-Routing den dokumentierten Anforderungen entsprechen. Andernfalls konfigurieren Sie die JSON-Antwort auf Ihrem Webserver oder Proxy.

Schritt 2: Überprüfen Sie die Alias-Richtlinien von Synapse.

Synapse kann einschränken, wer Aliase erstellen darf und welche Raumadressen zulässig sind. homeserver.yamlPrüfen Sie in der alias_creation_rulesKonfiguration, ob eine Anfrage zur Aliaserstellung abgelehnt wurde. Synapse wertet die konfigurierten Regeln der Reihe nach aus; die erste zutreffende Regel entscheidet über die Anfrage, und wenn keine Regel zutrifft, wird die Anfrage abgelehnt. Eine leere Liste lehnt alle Anfragen zur Aliaserstellung ab. Eine leere oder nicht vorhandene Liste erlaubt die Aliaserstellung standardmäßig, vorbehaltlich weiterer Prüfungen.

Prüfen Sie auch die Einstellung require_membership_for_aliases, die standardmäßig voraussetzt, dass sich der Benutzer im Raum befindet. Wenn Sie die Synapse-Konfiguration ändern, befolgen Sie den normalen Validierungs- und Neustartprozess Ihrer Bereitstellung und vermeiden Sie unnötige Lockerungen der Richtlinien. Die Sendeleistung eines Raums und die verfügbaren Steuerungsmöglichkeiten des Clients können ebenfalls Einfluss darauf haben, ob ein reguläres Mitglied den bevorzugten Alias ​​festlegen kann.

Schritt 3: Erstellen Sie einen Alias ​​für den Raum

Treten Sie dem gewünschten Raum in einem Matrix-Client bei und öffnen Sie dessen Einstellungen. Suchen Sie nach einem Abschnitt für Adressen oder Aliase; die Bezeichnungen und das Layout können je nach Clientversion variieren. Geben Sie die vollständige Adresse inklusive der führenden #Domain und der Homeserver-Domäne ein, z. B. #support:example.org. Fügen Sie sie als Raumadresse hinzu und legen Sie sie, falls der Client diese Option anbietet, als kanonischen oder bevorzugten Alias ​​fest. Speichern Sie die Änderung.

Falls Ihr Client keine Aliassteuerung bereitstellt, kann die Zuordnung über eine Client-Server-API-Anfrage erstellt werden. Der authentifizierte PUT /_matrix/client/v3/directory/room/{roomAlias}Endpunkt benötigt eine Raum-ID im Anfragetext. Beispielsweise kann ein autorisiertes Raummitglied oder Serverkonto eine Anfrage an den Homeserver senden, dem die Raum-ID gehört 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"}'

Ersetzen Sie die Beispiel-Raum-ID durch die exakte ID des Raums und verwenden Sie ein gültiges Zugriffstoken mit der erforderlichen Autorisierung. Behandeln Sie das Token wie ein Passwort: Veröffentlichen Sie es nicht, fügen Sie es nicht in einen Support-Beitrag ein und speichern Sie es nicht in der Versionsverwaltung. Die Prozentzeichen werden in der URL-Codierung #und :im HTTP-Pfad maskiert. Eine erfolgreiche Antwort zeigt an, dass die Zuordnung erstellt wurde. Die Antwort „Bereits vorhanden“ bedeutet, dass der Name bereits vergeben ist; prüfen Sie den Inhaber, bevor Sie Änderungen oder Löschungen vornehmen.

Schritt 4: Adresse überprüfen und teilen

Der Alias ​​wird mithilfe der öffentlichen Client-Server-API aufgelöst. Für diese Suche ist keine Authentifizierung erforderlich:

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

Eine erfolgreiche Antwort sollte die erwarteten Informationen room_idund eine serversListe enthalten. Vergleichen Sie die zurückgegebene Raum-ID mit der gewünschten Raum-ID. Ein 404-Fehler bedeutet, dass der Alias ​​auf dem Server, der diesen Namensraum verwaltet, nicht zugeordnet ist. Ein 400-Fehler weist auf eine ungültig formatierte Adresse hin. Testen Sie anschließend den vollständigen Alias ​​in einem zweiten Matrix-Konto oder -Client, um zu bestätigen, dass der Raum aufgelöst werden kann und der Beitritt gemäß seinen Beitrittsregeln möglich ist.

Wenn Sie einen kanonischen Alias ​​festlegen, überprüfen Sie die Raumdetails erneut und vergewissern Sie sich, dass die bevorzugte Adresse diejenige ist, die Sie veröffentlichen möchten. Teilen Sie den Alias ​​oder einen Matrix-Permalink erst, nachdem Sie sichergestellt haben, dass er zum richtigen Raum führt. Beachten Sie, dass ein öffentlicher Alias ​​einen privaten Raum nicht öffentlich macht; Benutzer benötigen weiterhin eine Berechtigung zum Beitritt.

Häufige Probleme, die es zu vermeiden gilt

• Verwendung einer Domain, die nicht dem Homeserver gehört: Der Servername in einem Alias ​​muss mit dem Namespace des Homeservers übereinstimmen, der ihn erstellt hat. Ein DNS-CNAME-Eintrag allein reicht nicht aus, um die Domain eines anderen Servers zu autorisieren.
• Verwechslung von Domäne und Host: example.org kann der Alias-Namespace sein, während matrix.example.orgder Diensthost ist. Legen Sie den Synapse-Servernamen und die Delegierung bewusst fest.
• Die Client-Erkennungsdatei befindet sich am falschen Ort: Die Föderationsdelegierung verwendet /.well-known/matrix/server. Die Client-Erkennungsdatei hat einen anderen Pfad und Zweck.
• Angenommen, ein Alias ​​veröffentlicht einen Raum öffentlich: Die Auflösung des Alias ​​und die Veröffentlichung im öffentlichen Raumverzeichnis sind separate Vorgänge, die jeweils eigenen Richtlinien unterliegen.
• Änderung des Servernamens in einer bestehenden Bereitstellung: Vorhandene Matrix-IDs hängen von diesem Namensraum ab. Behandeln Sie eine Domänenänderung als Architekturmigration und nicht als schnelle Alias-Einstellung.
• Teilen ohne Überprüfung der Zuordnung: Lösen Sie den Alias ​​auf und vergleichen Sie die zurückgegebene Raum-ID, bevor Sie die Information veröffentlichen. Eine lesbare Adresse ist zwar praktisch, aber die Zuordnung des Servers bestimmt, wohin sie führt.

Die Protokolldetails finden Sie in der Dokumentation zum Matrix-Identifikator- und Aliasformat sowie in der Matrix-Raumalias-API . Informationen zur Synapse-Einrichtung finden Sie im Leitfaden zur Föderationsdelegierung und im Konfigurationshandbuch von Element . Synapse-Optionen und Client-Oberflächen können sich zwischen verschiedenen Versionen ändern; prüfen Sie daher die Dokumentation Ihrer Version.