Accueil
» Comment faire
»
Rendez votre serveur Matrix Synapse accessible pour la fédération
Rendez votre serveur Matrix Synapse accessible pour la fédération
Pour fédérer un serveur Matrix Synapse, assurez-vous que son nom de serveur soit accessible depuis Internet via HTTPS, puis redirigez les requêtes entre serveurs Matrix vers Synapse. Dans une configuration courante, un proxy inverse gère le protocole TLS sur le port 443 et un /.well-known/matrix/serverfichier de configuration configure votre domaine Matrix pour pointer vers ce proxy. Si Synapse répond déjà sur le port 8448 de votre domaine, la délégation n'est peut-être pas nécessaire.
Ce guide utilise example.comcomme nom de serveur Matrix permanent et matrix.example.comcomme machine ou point de terminaison proxy. Remplacez ces deux noms par les vôtres. Un serveur d'accueil stocke les comptes et les salles Matrix ; la fédération permet aux serveurs d'accueil de communiquer entre eux. La configuration DNS, les règles de pare-feu, la syntaxe du proxy, le réseau des conteneurs et les certificats dépendent de votre hôte.
Avant de modifier la configuration
Choisissez le format des identifiants Matrix des utilisateurs : `<nom_utilisateur>` @name:example.comou ` <nom_utilisateur> @name:matrix.example.com`. La valeur de ` server_name<nom_utilisateur>` homeserver.yamlsera intégrée aux identifiants Matrix et aux adresses des salles. La documentation d'installation de Synapse recommande de faire ce choix avant l'installation, car toute modification ultérieure aura des conséquences. Si Synapse est déjà utilisé, ne modifiez pas `<nom_utilisateur>` simplement pour qu'il corresponde à une adresse web ; utilisez la délégation pour conserver les identifiants existants.
Le nom du serveur fait partie des identifiants Matrix, veuillez donc le confirmer avant de continuer.
Avant toute modification, assurez-vous de pouvoir accéder à Synapse, au proxy et au DNS public, et de disposer d'un certificat TLS valide pour le point de terminaison de fédération. Sauvegardez homeserver.yamlla clé de signature, qui établit l'identité du serveur principal. Conservez cette clé en lieu sûr ; la configuration standard de la fédération ne nécessite pas sa régénération.
Mettre en place la voie publique
1. Confirmer l'écouteur HTTP de Synapse
Synapse écoute généralement le trafic HTTP sur un port 8008situé derrière un proxy inverse. Dans le composant qui accepte le trafic du proxy, configurez Synapse pour qu'il puisse utiliser l'adresse et le schéma du client transféré par le proxy. Le proxy doit définir les en - têtes x_forwarded: trueappropriés , plutôt que de transmettre des valeurs arbitraires fournies par des clients externes.X-Forwarded-ForX-Forwarded-Proto
Le module d'écoute accepte les requêtes HTTP provenant d'un proxy local et active la gestion des en-têtes transférés par Synapse.
L'utilisation de cette méthode 127.0.0.1est appropriée lorsque le proxy s'exécute sur le même hôte. Elle n'est pas adaptée si le proxy se trouve dans un autre conteneur ou sur une autre machine, sauf si cette adresse est accessible depuis le proxy. Dans un déploiement conteneurisé, utilisez l'adresse réseau ou le nom de service accessible par le proxy et limitez l'accès via le réseau du conteneur ou le pare-feu. Conservez la structure d'écoute existante et modifiez les valeurs pertinentes ; ne copiez pas un fragment de configuration sans l'adapter au reste de votre configuration.
2. Chemins de la matrice de routage via le proxy
Configurez l'hôte virtuel HTTPS du proxy pour rediriger les deux chemins /_matrixvers /_synapse/clientl'écouteur HTTP de Synapse. Le premier chemin transporte les API Matrix, notamment la fédération ; le second est utilisé pour les points de terminaison clients de Synapse. Suivez l'exemple officiel de votre logiciel proxy, conservez le chemin de la requête et envoyez les en-têtes attendus par Synapse. Ne normalisez, ne décodez ni ne réécrivez les chemins d'URI : les signatures des requêtes Matrix peuvent échouer si un proxy modifie le chemin encodé.
Le proxy doit transmettre les deux chemins d'accès à l'API Matrix à Synapse sans réécrire l'URI.
La configuration exacte diffère selon le fournisseur (Nginx, Caddy, Apache, équilibreur de charge, hébergement géré). Utilisez la syntaxe actuelle du fournisseur et la documentation du proxy inverse Synapse comme référence. Une règle de proxy qui dessert le client web mais omet le chemin d'accès à l'API de fédération est insuffisante.
3. Assurez-vous que le DNS, le protocole HTTPS et le port choisi correspondent.
Dans cet exemple, l' matrix.example.comadresse IP doit pointer vers le proxy ou l'équilibreur de charge, et le port 443doit être accessible depuis l'extérieur. Le proxy nécessite un certificat valide pour l' adresse IP matrix.example.com. Si vous gérez la fédération directement à l'adresse IP example.com:8448, publiez cette route et ce certificat, puis ouvrez le port 8448. Utilisez soit le port 8448 (port par défaut classique), soit la délégation vers un autre hôte et un autre port, par exemple le port 443.
Vérifiez les règles DNS, de pare-feu ou de groupe de sécurité cloud, ainsi que le certificat externe à votre réseau privé. Si un CDN ou un tunnel est utilisé, sa compatibilité avec le trafic Matrix requis dépend de sa configuration actuelle ; consultez sa documentation et testez le routage réel plutôt que de présumer de sa compatibilité.
Publier la découverte de fédération en cas de besoin
4. Ajouter une délégation de serveur pour un point de terminaison distinct
Si le domaine de l'identifiant Matrix est example.comdifférent de celui de Synapse matrix.example.com:443, ce JSON sera servi via HTTPS à l'adressehttps://example.com/.well-known/matrix/server :
{
"m.server": "matrix.example.com:443"
}
Cet enregistrement de découverte de fédération délègue example.com au point de terminaison HTTPS à matrix.example.com sur le port 443.
Le port 443 est explicitement indiqué dans cet exemple ; si vous omettez un port, la découverte Matrix utilisera par défaut le port 8448. Ne confondez pas ce fichier avec le fichier ` /.well-known/matrix/clientserverwell-known.conf`, qui permet aux clients de trouver l'API client-serveur et est indépendant de la fédération serveur à serveur. Synapse peut diffuser lui-même un fichier `serverwell-known.conf` lorsque le domaine du nom de serveur est routé directement vers Synapse, mais avec un point de terminaison distinct, vous publiez généralement le fichier sur le serveur web du domaine du nom de serveur.
La découverte de fédération est définie par Matrix et documentée par Synapse. La spécification Matrix autorise la découverte via/.well-known/matrix/server ; consultez les instructions de délégation de Synapse avant de choisir une autre méthode, comme un enregistrement SRV, qui influe également sur les attentes TLS.
Test effectué depuis l'extérieur du serveur
5. Vérifiez l'enregistrement, puis effectuez une vérification de fédération.
Demandez l'URL de découverte depuis une machine située hors du réseau privé du serveur. Elle devrait renvoyer l'objet JSON ci-dessus via HTTPS, sans page de connexion, redirection HTML, avertissement de certificat ni site web non pertinent. Vérifiez ensuite que le nom d'hôte délégué est résolu, que son certificat est valide et que son port annoncé est accessible par Synapse. Avant de tester, utilisez l'outil de vérification de configuration de votre proxy et effectuez un rechargement.
Enfin, saisissez le nom de votre serveur (par exemple, ` example.commatrix_host`, et non le nom d'hôte délégué, sauf s'il s'agit de votre serveur server_name) dans l' outil de test de fédération Matrix officiel . Le guide de fédération Synapse suggère également de tester en rejoignant une salle publique telle que ` #synapse:matrix.orgmatrix_host`. Un test réussi confirme que les vérifications de découverte et d'accessibilité courantes ont été effectuées ; il ne garantit cependant pas le bon fonctionnement de tous les serveurs distants ni de toutes les opérations de salle, car les politiques distantes et les conditions réseau varient.
Si le testeur signale que votre serveur est inaccessible, vérifiez le domaine et le port utilisés, la configuration DNS, les règles de pare-feu, le nom du certificat, les chemins de proxy, les en-têtes transférés et si une redirection a modifié la requête. La documentation actuelle de la fédération Synapse indique clairement que les serveurs fédérateurs de Synapse peuvent ne pas suivre les redirections HTTP 308 dans certains cas. Évitez de vous fier à une redirection 308 pour le point de terminaison de la fédération et effectuez un nouveau test après avoir corrigé le problème. Consultez la documentation correspondant à votre version de Synapse pour connaître le comportement spécifique à cette version.
La fédération nécessite que les serveurs distants découvrent et accèdent à votre API de fédération. La configuration seule ne permet pas de vérifier si cela fonctionne pour chaque serveur distant. Confirmez le chemin d'accès avec un testeur et une connexion à une salle réelle, puis examinez le point de terminaison défaillant ou l'erreur spécifique.
Ces panneaux d'interface sont des exemples schématiques de données de configuration et de découverte, et non des captures d'écran d'un serveur en production. Références documentaires vérifiées le 10 octobre 2026.