Startseite
» Gewusst wie
»
Stellen Sie sicher, dass Ihr Matrix Synapse-Server für die Föderation erreichbar ist.
Stellen Sie sicher, dass Ihr Matrix Synapse-Server für die Föderation erreichbar ist.
Um einen Matrix Synapse Homeserver in einen Verbund einzubinden, muss sein Servername über HTTPS aus dem öffentlichen Internet auffindbar und erreichbar sein. Anschließend werden Matrix-Server-zu-Server-Anfragen an Synapse weitergeleitet. In einer gängigen Konfiguration übernimmt ein Reverse-Proxy die TLS-Verschlüsselung auf Port 443, und eine /.well-known/matrix/serverKonfigurationsdatei verweist Ihre Matrix-Domain auf diesen Proxy. Falls Synapse bereits auf Port 8448 unter Ihrem Servernamen antwortet, ist eine Delegierung möglicherweise nicht erforderlich.
Diese Anleitung verwendet example.comals permanenten Matrix-Servernamen und matrix.example.comals Maschinen- oder Proxy-Endpunkt. Ersetzen Sie beides durch Ihre eigenen Namen. Ein Homeserver speichert Matrix-Konten und -Räume; die Föderation ermöglicht die Kommunikation zwischen Homeservern. DNS, Firewall-Regeln, Proxy-Syntax, Container-Netzwerk und Zertifikate hängen von Ihrem Host ab.
Bevor Sie die Konfiguration ändern
Entscheiden Sie, ob die Matrix-IDs der Benutzer wie folgt aussehen sollen @name:example.com: oder @name:matrix.example.com. Der Wert von server_namewird homeserver.yamlBestandteil der Matrix-IDs und Raumadressen. Laut Synapse-Installationsdokumentation sollte dies vor der Installation festgelegt werden, da eine spätere Änderung ohne Folgen nicht möglich ist. Wenn Synapse bereits verwendet wird, ändern Sie die IDs nicht einfach, um sie an eine Webadresse anzupassen; verwenden Sie stattdessen die Delegierung, um die bestehenden IDs beizubehalten.
Der Servername ist Teil der Matrix-IDs, daher bestätigen Sie ihn bitte, bevor Sie fortfahren.
Stellen Sie vor der Bearbeitung sicher, dass Sie auf Synapse, den Proxy und den öffentlichen DNS-Server zugreifen können und über ein gültiges TLS-Zertifikat für den Verbundendpunkt verfügen. Sichern Sie homeserver.yamlden Signaturschlüssel, der die Identität des Homeservers festlegt. Bewahren Sie diesen Schlüssel sicher auf; für die routinemäßige Einrichtung des Verbunds ist keine Neuerstellung erforderlich.
Richten Sie die öffentliche Route ein
1. Überprüfen Sie den HTTP-Listener von Synapse.
Synapse lauscht üblicherweise auf Port 10 8008hinter einem Reverse-Proxy auf HTTP-Anfragen. Im Listener, der Proxy-Traffic akzeptiert, muss x_forwarded: truedie Client-Adresse und das Schema des Proxys so konfiguriert werden, dass Synapse diese verwenden kann. Der Proxy muss die entsprechenden Header setzen X-Forwarded-Forund X-Forwarded-Protodarf keine beliebigen Werte von externen Clients weiterleiten.
Der Listener akzeptiert HTTP-Anfragen von einem lokalen Proxy und aktiviert die Weiterleitungsheader-Verarbeitung von Synapse.
Die Bindung an einen 127.0.0.1Server ist sinnvoll, wenn der Proxy auf demselben Host ausgeführt wird. Sie ist nicht geeignet, wenn sich der Proxy in einem anderen Container oder auf einem anderen Rechner befindet, es sei denn, diese Adresse ist vom Proxy aus erreichbar. Verwenden Sie in einer Containerumgebung die Netzwerkadresse oder den Dienstnamen, den der Proxy erreichen kann, und beschränken Sie den Zugriff über das Containernetzwerk oder die Firewall. Behalten Sie die bestehende Listener-Struktur bei und bearbeiten Sie die relevanten Werte; fügen Sie nicht einfach einen Teil Ihrer Konfiguration ein.
2. Routenmatrixpfade durch den Proxy
Konfigurieren Sie den HTTPS-Virtual-Host des Proxys so, dass er sowohl den ersten /_matrixals auch /_synapse/clientden zweiten Pfad an den HTTP-Listener von Synapse weiterleitet. Der erste Pfad überträgt Matrix-APIs, einschließlich Federation; der zweite wird für Synapse-Client-Endpunkte verwendet. Orientieren Sie sich an der offiziellen Vorlage Ihrer Proxy-Software, behalten Sie den Anfragepfad bei und senden Sie die von Synapse erwarteten weitergeleiteten Header. Normalisieren, dekodieren oder überschreiben Sie URI-Pfade nicht: Matrix-Anfragesignaturen können fehlschlagen, wenn ein Proxy den kodierten Pfad ändert.
Der Proxy muss beide Matrix-API-Pfade an Synapse weiterleiten, ohne die URI umzuschreiben.
Die genaue Konfiguration variiert je nach Anbieter (Nginx, Caddy, Apache, Load Balancer und Managed Hosting). Verwenden Sie die aktuelle Syntax des jeweiligen Anbieters und die Synapse-Dokumentation zum Reverse-Proxy als Referenz. Eine Proxy-Regel, die den Webclient bedient, aber den Pfad zur Federation-API auslässt, ist nicht ausreichend.
3. Stellen Sie sicher, dass DNS, HTTPS und der gewählte Port übereinstimmen.
Im Beispiel matrix.example.commuss die Adresse auf den Proxy oder Load Balancer aufgelöst werden, und der Port 443muss von extern erreichbar sein. Der Proxy benötigt ein gültiges Zertifikat für die angegebene Adresse matrix.example.com. Wenn Sie die Föderation stattdessen direkt unter der angegebenen Adresse bereitstellen example.com:8448, veröffentlichen Sie diese Route und das zugehörige Zertifikat und öffnen Sie Port 84488448. Verwenden Sie entweder den direkten Port 8448 (den üblichen Standard) oder delegieren Sie die Adresse an einen anderen Host und Port, z. B. 443.
Prüfen Sie DNS-, Firewall- oder Cloud-Sicherheitsgruppenregeln sowie das Zertifikat von außerhalb Ihres privaten Netzwerks. Falls ein CDN oder Tunnel vorgeschaltet ist, hängt die Unterstützung des erforderlichen Matrix-Datenverkehrs von der aktuellen Konfiguration des jeweiligen Dienstes ab. Prüfen Sie die Dokumentation und testen Sie die tatsächliche Route, anstatt Kompatibilität anzunehmen.
Veröffentlichen Sie die Föderationserkennung bei Bedarf
4. Serverdelegierung für einen separaten Endpunkt hinzufügen
Wenn die Matrix-ID-Domäne lautet, example.comSynapse aber unter erreichbar ist matrix.example.com:443, stellen Sie dieses JSON über HTTPS unter bereit https://example.com/.well-known/matrix/server:
{
"m.server": "matrix.example.com:443"
}
Dieser Verbundermittlungsdatensatz delegiert example.com an den HTTPS-Endpunkt unter matrix.example.com auf Port 443.
Port 443 ist in diesem Beispiel explizit angegeben; wird kein Port angegeben, verwendet Matrix standardmäßig Port 8448. Verwechseln Sie diese Datei nicht mit der Datei `server.com` /.well-known/matrix/client, die Clients hilft, die Client-Server-API zu finden und unabhängig von der Server-zu-Server-Federation ist. Synapse kann eine Server-Welcome-Datei selbst bereitstellen, wenn die Servernamensdomäne direkt an Synapse weitergeleitet wird. Bei einem separaten Endpunkt veröffentlichen Sie die Datei normalerweise auf dem Webserver der Servernamensdomäne.
Die Ermittlung von Föderationsverbindungen ist in Matrix spezifiziert und in Synapse dokumentiert. Die Matrix-Spezifikation ermöglicht die Ermittlung über [Methode/Verfahren einfügen /.well-known/matrix/server]. Beachten Sie die Synapse-Delegierungsanweisungen, bevor Sie eine andere Methode wie beispielsweise einen SRV-Eintrag wählen, da dies auch Auswirkungen auf die TLS-Erwartungen hat.
Test von außerhalb des Servers
5. Überprüfen Sie den Datensatz und führen Sie anschließend eine Verbundprüfung durch.
Fordern Sie die Discovery-URL von einem Rechner außerhalb des privaten Netzwerks des Servers an. Sie sollte das oben genannte JSON-Objekt über HTTPS ohne Anmeldeseite, HTML-Weiterleitung, Zertifikatswarnung oder eine fremde Website zurückgeben. Überprüfen Sie anschließend, ob der delegierte Hostname aufgelöst werden kann, das zugehörige Zertifikat gültig ist und der angegebene Port Synapse erreicht. Verwenden Sie vor dem Testen die Konfigurationsprüfung und die Neuladeprozedur Ihres Proxys.
Geben Sie abschließend Ihren Servernamen (z. B. „example.com“ example.com, nicht den delegierten Hostnamen, es sei denn, dieser ist Ihr Servername server_name) im offiziellen Matrix Federation Tester ein . Die Synapse-Federationsanleitung empfiehlt außerdem, die Tests in einem öffentlichen Raum wie z. B. „example.com“ durchzuführen #synapse:matrix.org. Ein erfolgreicher Test bestätigt, dass die gängigen Erkennungs- und Erreichbarkeitsprüfungen bestanden wurden; er garantiert jedoch nicht, dass jeder Remote-Server oder jede Raumoperation funktioniert, da die Richtlinien der Remote-Server und die Netzwerkbedingungen variieren.
Meldet der Tester, dass Ihr Server nicht erreichbar ist, überprüfen Sie die verwendete Domain und den Port, DNS-Einstellungen, Firewall-Regeln, Zertifikatsnamen, Proxy-Pfade, weitergeleitete Header und ob eine Weiterleitung die Anfrage verändert hat. Die aktuelle Dokumentation zur Synapse-Federation weist ausdrücklich darauf hin, dass Synapse-Federationsserver HTTP-308-Weiterleitungen in manchen Fällen nicht folgen. Vermeiden Sie es, sich für den Federation-Endpunkt auf eine 308-Weiterleitung zu verlassen, und testen Sie erneut, nachdem Sie das Problem behoben haben. Informationen zum versionsspezifischen Verhalten finden Sie in der Dokumentation zu Ihrer installierten Synapse-Version.
Für die Föderation müssen entfernte Homeserver Ihre Föderations-API finden und erreichen können. Ob dies für jeden entfernten Server funktioniert, lässt sich nicht allein anhand der Konfiguration feststellen. Bestätigen Sie die Route mit dem Tester und einem realen Raumbeitritt und untersuchen Sie anschließend den spezifischen Endpunkt oder Fehler, der nicht funktioniert.
Diese Benutzeroberflächen sind schematische Beispiele für Konfigurations- und Erkennungsdaten und keine Screenshots von einem Live-Server. Die Dokumentationsangaben wurden am 10. Oktober 2026 geprüft.