Zorg dat uw Matrix Synapse-server bereikbaar is voor federatie.

Om een ​​Matrix Synapse-homeserver te federeren, moet de servernaam vindbaar en bereikbaar zijn vanaf het openbare internet via HTTPS. Vervolgens moeten Matrix-server-naar-server-verzoeken naar Synapse worden doorgestuurd. In een veelvoorkomende configuratie handelt een reverse proxy TLS af op poort 443 en /.well-known/matrix/serververwijst een configuratiebestand uw Matrix-domein naar die proxy. Als Synapse al antwoordt op uw serverdomein op poort 8448, is delegatie mogelijk niet nodig.

Deze handleiding gebruikt example.comals de permanente Matrix-servernaam en matrix.example.comals het machine- of proxy-eindpunt. Vervang beide door uw eigen namen. Een homeserver slaat Matrix-accounts en -ruimtes op; federatie maakt communicatie tussen homeservers mogelijk. DNS, firewallregels, proxysyntaxis, containernetwerken en certificaten zijn afhankelijk van uw host.

Voordat u de configuratie wijzigt

Bepaal of de Matrix-ID's van gebruikers eruit moeten zien als @name:example.comof @name:matrix.example.com. De waarde van server_namein homeserver.yamlwordt onderdeel van de Matrix-ID's en kameradressen. De installatiedocumentatie van Synapse geeft aan dat u dit vóór de installatie moet kiezen, omdat het later niet zonder gevolgen kan worden gewijzigd. Als Synapse al in gebruik is, wijzig het dan niet alleen om het aan een webadres aan te passen; gebruik delegatie om de bestaande ID's te behouden.

Een YAML-editor toont server_name: example.com en een herinnering om de waarde te kiezen vóór de installatie.
De servernaam maakt deel uit van de Matrix-ID's, dus controleer deze voordat u verdergaat.

Voordat u begint met bewerken, moet u ervoor zorgen dat u toegang hebt tot Synapse, de proxy en de openbare DNS, en dat u een geldig TLS-certificaat hebt voor het federatie-eindpunt. Maak een back-up homeserver.yamlvan de ondertekeningssleutel, die de identiteit van de thuisserver vaststelt. Bewaar deze sleutel veilig; het is niet nodig om deze opnieuw te genereren tijdens de standaard federatie-instellingen.

Stel de openbare route in.

1. Controleer of de HTTP-listener van Synapse werkt.

Synapse luistert doorgaans naar HTTP-verkeer op een poort 8008achter een reverse proxy. In de listener die proxyverkeer accepteert, x_forwarded: truemoet Synapse het doorgestuurde clientadres en -schema van de proxy gebruiken. De proxy moet de juiste headers instellen X-Forwarded-For, X-Forwarded-Protoin plaats van willekeurige waarden door te geven die door externe clients worden aangeleverd.

Een fragment uit een YAML-listener laat zien dat Synapse actief is op HTTP-poort 8008 met x_forwarded ingeschakeld en een loopback-bindadres.
De listener accepteert HTTP van een lokale proxy en schakelt de doorgestuurde headerverwerking van Synapse in.

Binding 127.0.0.1is geschikt wanneer de proxy op dezelfde host draait. Het is niet geschikt wanneer de proxy zich in een andere container of machine bevindt, tenzij dat adres bereikbaar is vanaf de proxy. Gebruik in een containeromgeving het netwerkadres of de servicenaam die de proxy kan bereiken en beperk de toegang via het containernetwerk of de firewall. Behoud de bestaande listenerstructuur en bewerk de relevante waarden; plak geen fragment blindelings over de rest van uw configuratie.

2. Route Matrix-paden via de proxy

Configureer de virtuele HTTPS-host van de proxy om zowel /_matrixals door te sturen /_synapse/clientnaar de HTTP-listener van Synapse. Het eerste pad transporteert Matrix API's, inclusief federatie; het tweede wordt gebruikt voor Synapse-client-eindpunten. Volg het officiële voorbeeld voor uw proxysoftware, behoud het aanvraagpad en verstuur de doorgestuurde headers die Synapse verwacht. Normaliseer, decodeer of herschrijf geen URI-paden: Matrix-aanvraagsignaturen kunnen mislukken als een proxy het gecodeerde pad wijzigt.

Een configuratie-editor voor een reverse proxy laat zien dat de Matrix API- en Synapse-clientpaden worden doorgestuurd naar localhost poort 8008 met doorgestuurde headers.
De proxy moet beide Matrix API-paden aan Synapse doorgeven zonder de URI te herschrijven.

De exacte configuratie verschilt per Nginx-, Caddy-, Apache-, load balancer- en managed hostingprovider. Gebruik de huidige syntax van de leverancier en de Synapse reverse-proxy-documentatie als referentie. Een proxyregel die de webclient bedient maar het pad naar de federatie-API weglaat, is niet voldoende.

3. Zorg ervoor dat DNS, HTTPS en de gekozen poort met elkaar overeenkomen.

In dit voorbeeld matrix.example.commoet de verbinding naar de proxy of load balancer verwijzen en 443moet de poort van buitenaf bereikbaar zijn. De proxy heeft een geldig certificaat nodig voor matrix.example.com. Als u de federatie in plaats daarvan rechtstreeks op aanbiedt example.com:8448, publiceer dan die route en dat certificaat en open poort 8448. Gebruik ofwel rechtstreeks poort 8448, de gebruikelijke standaard, of delegatie naar een andere host en poort, zoals 443.

Controleer de DNS-, firewall- of cloudbeveiligingsgroepregels en het certificaat van buiten uw privénetwerk. Als er een CDN of tunnel voor staat, hangt het ervan af of deze het vereiste Matrix-verkeer ondersteunt, afhankelijk van de huidige configuratie van die service; raadpleeg de documentatie en test de daadwerkelijke route in plaats van compatibiliteit te veronderstellen.

Publiceer de federatie-ontdekking wanneer nodig.

4. Voeg serverdelegatie toe voor een apart eindpunt.

Als het Matrix ID-domein is, example.commaar Synapse bereikbaar is op matrix.example.com:443, serveer deze JSON dan via HTTPS op https://example.com/.well-known/matrix/server:

{
  "m.server": "matrix.example.com:443"
}
Een JSON-weergave in browserstijl op example.com/.well-known/matrix/server bevat de waarde m.server matrix.example.com:443.
Dit federatie-ontdekkingsrecord delegeert example.com naar het HTTPS-eindpunt matrix.example.com op poort 443.

Poort 443 is in dit voorbeeld expliciet; als u een poort weglaat, gebruikt Matrix Discovery standaard poort 8448. Verwar dit bestand niet met /.well-known/matrix/client, dat clients helpt de client-server-API te vinden en losstaat van server-naar-server-federatie. Synapse kan zelf een server-wellknown-bestand aanbieden wanneer het server-name-domein rechtstreeks naar Synapse wordt gerouteerd, maar met een apart eindpunt publiceert u het bestand normaal gesproken op de webserver van het server-name-domein.

Federatie-ontdekking wordt gespecificeerd door Matrix en gedocumenteerd door Synapse. De Matrix-specificatie maakt ontdekking mogelijk via /.well-known/matrix/server; controleer de delegatie-instructies van Synapse voordat u een andere methode kiest, zoals een SRV-record, aangezien dit ook van invloed is op de TLS-verwachtingen.

Test vanaf buiten de server

5. Controleer de gegevens en voer vervolgens een federatiecontrole uit.

Vraag de discovery-URL op vanaf een machine buiten het privénetwerk van de server. Deze zou het bovenstaande JSON-object via HTTPS moeten retourneren, zonder inlogpagina, HTML-redirect, certificaatwaarschuwing of ongerelateerde website. Controleer vervolgens of de gedelegeerde hostnaam correct wordt opgelost, of het certificaat geldig is en of de geadverteerde poort Synapse bereikt. Gebruik de configuratiechecker en herlaadprocedure van uw proxy voordat u de tests uitvoert.

Voer tot slot uw servernaam (bijvoorbeeld , example.comniet de gedelegeerde hostnaam, tenzij dat uw is server_name) in de officiële Matrix Federation Tester in . De Synapse-federatiehandleiding raadt ook aan om te testen door deel te nemen aan een openbare ruimte zoals #synapse:matrix.org. Een succesvolle controle bevestigt dat de gebruikelijke detectie- en bereikbaarheidscontroles zijn geslaagd; het garandeert echter niet dat elke externe server of elke ruimtebewerking zal werken, omdat externe beleidsregels en netwerkcondities variëren.

Als de tester meldt dat uw server niet bereikbaar is, controleer dan het domein en de poort die geprobeerd zijn, DNS, firewallregels, certificaatnaam, proxypaden, doorgestuurde headers en of een redirect het verzoek heeft gewijzigd. De huidige Synapse-federatiedocumentatie waarschuwt specifiek dat de federatieve servers van Synapse in sommige gevallen HTTP 308-redirects mogelijk niet opvolgen. Vermijd het gebruik van een 308-redirect voor het federatie-eindpunt en test opnieuw nadat u dit hebt gecorrigeerd. Raadpleeg de documentatie die overeenkomt met uw geïnstalleerde Synapse-versie voor versiespecifiek gedrag.

Federatie vereist dat externe thuisservers uw federatie-API kunnen vinden en bereiken. Of dit voor elke externe server werkt, is niet alleen op basis van de configuratie te achterhalen. Bevestig de route met de tester en een daadwerkelijke deelname aan een chatroom, en onderzoek vervolgens het specifieke falende eindpunt of de fout.

Deze interfacepanelen zijn schematische voorbeelden van configuratie- en ontdekkingsgegevens, geen schermafbeeldingen van een live server. Documentatiereferenties gecontroleerd op 10 oktober 2026.

Laat een reactie achter

Matrix Room-beheerdersrechtenfouten oplossen via actie

Traceer M_FORBIDDEN naar het stroomniveau van de ruimte, het lidmaatschap of de Synapse-serverbeheerderstoegang en herstel vervolgens alleen de machtiging die de geblokkeerde actie nodig heeft.

Zorg dat uw Matrix Synapse-server bereikbaar is voor federatie.

Zorg dat uw Matrix Synapse-server bereikbaar is voor federatie.

Configureer Synapse discovery, HTTPS en proxy routing zodat andere Matrix homeservers uw server kunnen vinden en ermee in contact kunnen komen.

Verbind Element Web met Keycloak via Synapse OIDC.

Configureer een Keycloak OIDC-client en een Synapse-provider zodat Element Web-gebruikers zich kunnen aanmelden via uw identiteitsserver zonder clientgeheimen prijs te geven.

Stel Element Key-back-up en kruisondertekening veilig in.

Stel Element Key-back-up en kruisondertekening veilig in.

Sla een herstelsleutel op, verifieer uw Element-sessies en controleer of versleutelde berichtsleutels kunnen worden hersteld zonder de back-up te verwarren met uw accountwachtwoord.

Voorkom dat Matrix Synapse-geheugen vastloopt tijdens clientsynchronisatie.

Diagnoseer geheugenproblemen bij Synapse tijdens synchronisatie, pas de caching veilig aan, identificeer achterstanden in aanvragen en controleer of het geheugengebruik stabiel is.

Los TLS-certificaatfouten van Synapse Federation op.

Traceer Matrix-federatiecertificaatfouten naar de juiste server, herstel de TLS-keten of het CA-vertrouwen en verifieer de oplossing zonder de beveiligingscontroles uit te schakelen.

Plaats een Synapse Matrix-server veilig achter Cloudflare.

Plaats een Synapse Matrix-server veilig achter Cloudflare.

Routeer Matrix-clients en federatie via Cloudflare op HTTPS 443, behoud Synapse-ontdekking en voorkom cachen van API-verkeer of problemen met media-uploads.

Herstel Matrix Synapse veilig met een PostgreSQL-dump.

Maak een back-up van Synapse met pg_dump, bescherm de ondertekeningssleutel en de media, en herstel de back-up in een schone PostgreSQL-database zonder verouderde eenmalige sleutels opnieuw te gebruiken.

Mjölnir als Matrix Room Moderation Bot uitvoeren met Docker

Mjölnir als Matrix Room Moderation Bot uitvoeren met Docker

Configureer Mjölnir met een speciaal Matrix-account, een versleutelde beheerruimte, Docker Compose, een beleidslijst en toegangsrechtencontroles.

Schakel native Matrix Sliding Sync in voor sneller laden op mobiele apparaten.

Schakel native Matrix Sliding Sync in voor sneller laden op mobiele apparaten.

Sla de verouderde proxy over en configureer Synapse's ingebouwde Sliding Sync. Controleer de clientdetectie en meet vervolgens het laadgedrag van de kamerlijst en het herverbindingsgedrag op een compatibele telefoon.