Comment configurer un serveur Matrix derrière un proxy Cloudflare

Un serveur Matrix peut être hébergé derrière Cloudflare, mais la configuration dépend de la manière dont les clients et les autres serveurs d'hébergement le découvrent. Le proxy HTTP standard de Cloudflare prend en charge HTTPS sur le port 443 ; la fédération Synapse utilise généralement par défaut le port 8448, qui ne figure pas dans la liste des ports proxy standard de Cloudflare. Une solution fiable consiste à exposer Synapse via un proxy inverse sur le port 443 et à publier des enregistrements DNS connus (Well-Known Record) Matrix qui dirigent le trafic des clients et de la fédération vers ce nom d'hôte. Une autre solution consiste à conserver la fédération sur le port 8448 et à configurer cet enregistrement DNS en mode DNS uniquement.

Ce guide utilise Synapse, l'implémentation officielle du serveur d'hébergement Matrix, avec les identifiants Matrix @alice:example.comet le point de terminaison client fournis à titre d'exemple matrix.example.com. Remplacez ces noms et adresses par les vôtres. Les instructions supposent que Synapse et un proxy inverse HTTPS sont déjà installés. Elles peuvent varier selon l'implémentation du serveur d'hébergement. Vérifié le 6 octobre 2026 par rapport à la documentation Cloudflare et Element Synapse.

Choisissez la configuration réseau appropriée

Le proxy « nuage orange » de Cloudflare est un proxy inverse HTTP/HTTPS. Il se situe entre les clients et votre serveur d'origine pour les requêtes web transitant par proxy ; il ne prend pas en charge tous les ports TCP. Ses ports HTTPS standard incluent les ports 443 et 8443, mais pas le port de fédération 8448, couramment utilisé par Synapse. Consultez la liste des ports réseau pris en charge par Cloudflare et les limitations du proxy .

La première configuration est utilisée ci-dessous. Un enregistrement DNS proxy ne configure pas à lui seul la découverte Matrix, le proxy inverse, TLS ou la politique de pare-feu.

1. Choisissez le nom du serveur Matrix avant de configurer le DNS.

Le nom du serveur Matrix correspond à la partie située après les deux-points dans l'identifiant utilisateur. Dans cet exemple example.com, il s'agit de `<nom_serveur>`, les utilisateurs ont donc des identifiants tels que ` <nom_utilisateur> @alice:example.com`. Le nom d'hôte technique du client est `< matrix.example.comnom_hôte>`. Cette séparation permet de conserver la stabilité du domaine utilisé dans les identifiants utilisateur, même lorsque le trafic est délégué à un autre nom d'hôte. Si Synapse est déjà initialisé, ne modifiez pas server_namece nom d'hôte sans précaution : il fait partie de l'identité de l'utilisateur et de la salle, et sa modification constitue une migration, et non un simple ajustement du proxy.

Prévoyez de servir deux petits documents de découverte JSON à partir du nom de domaine du serveur :

• https://example.com/.well-known/matrix/clientindique aux clients compatibles d'utiliser https://matrix.example.com.
• https://example.com/.well-known/matrix/serverindique aux autres serveurs d'accueil de contacter la fédération à matrix.example.com:443.

Le document client nécessite un Access-Control-Allow-Origin: *en-tête de réponse. Le guide de délégation Synapse inclut des exemples de ces enregistrements et leur structure attendue : Délégation de fédération Synapse .

2. Créez les enregistrements DNS Cloudflare

Dans Cloudflare DNS, créez un Aenregistrement pointant matrixvers l'adresse IPv4 publique du serveur. N'ajoutez cet AAAAenregistrement que si l'origine dispose d'une connectivité IPv6 fonctionnelle et d'un pare-feu configuré pour IPv6. Définissez le statut du proxy du nom d'hôte web sur « Proxy activé » (nuage orange). Si le domaine racine pointe également vers ce serveur et héberge les fichiers connus, configurez également son enregistrement web comme proxy.

Conservez les enregistrements non liés, y compris les enregistrements de messagerie, avec leurs paramètres DNS uniquement appropriés. Les enregistrements MX et TXT ne sont pas utilisés pour le proxy. Cloudflare explique qu'un enregistrement A, AAAA ou CNAME utilisé pour le proxy achemine les requêtes HTTP/HTTPS via Cloudflare, tandis qu'un enregistrement DNS uniquement renvoie directement l'adresse d'origine : Comportement de l'état du proxy Cloudflare .

Autorisez le trafic HTTPS entrant depuis Cloudflare vers le serveur d'origine. Pour une protection renforcée, limitez le pare-feu du serveur d'origine aux plages d'adresses IP publiées par Cloudflare et veillez à ce que ces plages soient toujours à jour. Si l'adresse IP du serveur était exposée avant l'activation de la zone, le proxy DNS ne la rend pas invalide ; il est donc conseillé de modifier l'adresse IP du serveur d'origine après l'activation. Ne présumez pas que le seul nuage orange empêche l'accès direct au serveur d'origine.

3. Configurez le protocole HTTPS entre Cloudflare et l'origine.

Dans les paramètres SSL/TLS de Cloudflare, utilisez le mode Complet (strict) lorsque l'origine présente un certificat valide pour le nom d'hôte, tel qu'un certificat de confiance publique ou un certificat d'autorité de certification d'origine Cloudflare. Le mode Complet (strict) chiffre la connexion entre Cloudflare et l'origine et valide le certificat d'origine ; le mode Flexible ne fournit pas ce même chemin TLS de bout en bout. Consultez la documentation relative au mode Complet (strict) de Cloudflare .

Installez le certificat et la clé privée sur le proxy inverse, et non nécessairement dans Synapse. Le proxy inverse doit écouter sur le port public 443 et rediriger les requêtes Matrix vers le serveur HTTP de Synapse, généralement sur le port 8008. Ne rendez pas le serveur HTTP de Synapse public si le proxy inverse est le seul point d'entrée.

4. Indiquez à Synapse qu'il se trouve derrière un proxy inverse de confiance.

Dans le gestionnaire HTTP concerné homeserver.yaml, activez la gestion des en-têtes transférés. Voici un exemple simplifié pour un serveur non conteneurisé :

listeners:
  - port: 8008
    type: http
    tls: false
    x_forwarded: true
    bind_addresses: ['127.0.0.1']
    resources:
      - names: [client, federation]
        compress: false

Intégrez ces paramètres au listener existant plutôt que de remplacer toute la configuration. La documentation de Synapse recommande x_forwarded: truel'utilisation d'un proxy inverse et suggère de se lier à localhost lorsque le proxy s'exécute sur le même hôte. Pour un déploiement conteneurisé, lier Synapse à l'adresse de bouclage du conteneur peut empêcher le proxy hôte de l'atteindre ; utilisez plutôt l'adresse réseau du conteneur ou du service et bloquez ce chemin avec un pare-feu. Consultez le guide du proxy inverse Synapse avant de modifier les paramètres du listener.

Les en-têtes transférés ne sont fiables que si Synapse accepte le trafic provenant de votre proxy contrôlé. Si Cloudflare est le seul point d'accès à Internet, empêchez l'accès public direct à l'origine et configurez le proxy pour qu'il transmette l'adresse client correcte. $remote_addrSinon, l'adresse de Nginx sera celle de Cloudflare, car Cloudflare est connecté à Nginx. Configurez le module real-IP de Nginx pour qu'il n'accepte que les plages d'adresses IP sources publiées par Cloudflare avant utilisationCF-Connecting-IP ; ne faites jamais confiance à cet en-tête provenant de clients Internet arbitraires. Gardez l'API d'administration de Synapse privée, sauf raison spécifique de l'exposer.

5. Chemins de la matrice de routage sans les réécrire

Configurez votre proxy inverse pour envoyer les deux requêtes /_matrixà /_synapse/clientSynapse. Conservez l'URI de la requête exacte. Les signatures des requêtes de fédération Synapse peuvent échouer si un proxy décode ou normalise les segments de chemin encodés.

Voici un exemple Nginx compact matrix.example.com. Il suppose que vos directives de certificat TLS sont déjà configurées pour ce bloc serveur et que le proxy inverse et Synapse s'exécutent sur le même hôte :

server {
    listen 443 ssl;
    server_name matrix.example.com;

    location ~ ^(/_matrix|/_synapse/client) {
        proxy_pass http://127.0.0.1:8008;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $host;
        proxy_http_version 1.1;
        client_max_body_size 50M;
    }
}

N'ajoutez pas de suffixe URI à l'emplacement de cette expression régulière proxy_pass. La documentation du proxy Synapse indique que la canonisation des URI peut être à l'origine d'erreurs de signature de fédération. Ajustez également la valeur client_max_body_sizepour qu'elle corresponde à la limite de chargement de Synapse et à toute limite de votre forfait Cloudflare. La 50Mvaleur ci-dessus n'est qu'un exemple et ne constitue pas une recommandation universelle.

Cloudflare prend en charge les WebSockets dans ses offres, et les clients Matrix peuvent utiliser des connexions persistantes. Vérifiez que votre proxy autorise la mise à niveau et que vos pare-feu applicatifs web (WAF) et règles de limitation de débit n'empêchent pas les requêtes Matrix légitimes. La documentation WebSockets de Cloudflare décrit la gestion des connexions mises à niveau.

6. Publier les réponses bien connues

Servez les deux réponses suivantes via example.comHTTPS. Vous pouvez les renvoyer depuis votre serveur web, un hôte statique ou un hôte virtuel distinct. Veillez à ce que les documents client et de fédération soient bien distincts.

GET /.well-known/matrix/client
HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Origin: *

{"m.homeserver":{"base_url":"https://matrix.example.com"}}

GET /.well-known/matrix/server
HTTP/1.1 200 OK
Content-Type: application/json

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

N’utilisez pas de redirection vers un hôte non lié sans avoir vérifié les exigences de découverte Matrix et le comportement du client. Assurez-vous que l’hôte du serveur possède un certificat HTTPS valide et que Cloudflare ne met pas en cache les réponses de découverte obsolètes pendant leur modification.

7. Maintenez un trafic API dynamique et limitez les chargements.

Ne mettez pas en cache les réponses authentifiées de l'API Matrix. Ajoutez une règle de cache Cloudflare pour contourner la mise en cache des chemins d'accès à l'API Matrix, y compris `< chemin_vers_l'API_Matrix>` /_matrix/*et ` /_synapse/client/*<chemin_vers_l'API_Matrix>`, sauf si vous avez une raison valable et testée de traiter différemment une réponse publique spécifique. Évitez les règles WAF ou anti-bots trop générales qui contestent ou bloquent les points de terminaison de fédération ; les requêtes de fédération proviennent de nombreux serveurs d'accueil indépendants. Si une règle de sécurité est nécessaire, testez-la sur la connexion client, la synchronisation, le chargement de médias et la fédération avant de l'appliquer de manière générale.

Les chargements sont soumis à plusieurs limites indépendantes : celles du client, celles de votre forfait ou zone Cloudflare, la limite de taille du corps de la requête du proxy inverse et celles de Synapse max_upload_size. Une erreur 413 signifie que l'une de ces limites a rejeté la requête. Cloudflare publie les limites de chargement spécifiques à chaque forfait et précise que ces paramètres peuvent être ajustés dans les limites indiquées : consultez la page de dépannage des erreurs 413 de Cloudflare . N'augmentez les limites que si nécessaire et effectuez un test avec un fichier plus petit que la limite configurée avant de les augmenter davantage.

8. Vérifier l'accès client, la découverte et la fédération

Exécutez ces vérifications depuis une machine située en dehors du réseau de votre serveur. Remplacez les noms d'hôtes d'exemple :

curl -i https://example.com/.well-known/matrix/client
curl -i https://example.com/.well-known/matrix/server
curl -i https://matrix.example.com/_matrix/client/versions
curl -i https://matrix.example.com/health

Les deux premières requêtes doivent renvoyer un code HTTP 200, un contenu JSON et les valeurs attendues. Le document client doit inclure l'en-tête CORS. Le point de terminaison des versions du client doit renvoyer du JSON de Synapse via Cloudflare. Le point de terminaison d'état de Synapse renvoie un code HTTP 200 lorsqu'il est atteint via un écouteur configuré, mais il ne remplace pas la vérification de connexion ou de fédération.

Connectez-vous ensuite avec un client Matrix à l'aide d'un identifiant se terminant par `.md` :example.com, rejoignez une salle hébergée ailleurs et vérifiez que les messages et les mises à jour d'adhésion sont synchronisés. Utilisez un testeur de fédération Matrix ou un second serveur d'accueil pour valider la découverte des serveurs et la fédération. Une requête réussie /_matrix/client/versionsprouve uniquement que la route côté client fonctionne ; elle ne prouve pas que la découverte de la fédération, la signature ou la fédération sortante sont correctes.

À quoi ressemble le succès — et quand faut-il changer de conception

• Les clients se connectent via Cloudflare : le DNS est résolu en adresses Cloudflare, le HTTPS utilise le certificat prévu et l’API client Matrix renvoie une réponse.
• La découverte est correcte : les deux URL connues renvoient le JSON correct et le document client réussit les tests d’origine croisée.
• La fédération fonctionne : un serveur distant détecte votre point de terminaison annoncé et peut échanger l’état de la salle. Si la délégation sur le port 443 échoue, mais que l’accès direct au port 8448 fonctionne, vérifiez l’enregistrement connu, le routage du proxy et les règles du pare-feu applicatif web (WAF).
• Les chargements fonctionnent à la taille attendue : effectuez un test avec un fichier représentatif. Si les petits fichiers sont correctement chargés mais que les plus volumineux renvoient une erreur 413, comparez les quatre limites de taille au lieu de modifier uniquement Synapse.
• L'origine n'est pas un chemin public alternatif : les requêtes directes vers l'origine doivent être bloquées ou limitées conformément à leur conception. Si elles parviennent malgré tout au service Matrix, corrigez la configuration du pare-feu et du proxy de confiance.

Utilisez la fédération DNS uniquement sur le port 8448 si vos exigences ou votre implémentation ne permettent pas le routage de la fédération sur le port 443. Sachez toutefois que cela expose l'adresse d'origine et supprime la protection du proxy HTTP de Cloudflare pour ce nom d'hôte. Spectrum est une autre option pour les ports non standard, sous réserve de disponibilité et des contraintes de votre abonnement. Le proxy Cloudflare implique également que la connexion TLS est terminée chez Cloudflare avant toute seconde connexion TLS vers votre origine. Le chiffrement de bout en bout de Matrix protège le contenu des messages chiffrés, mais ne masque pas les métadonnées de connexion ni le contenu non chiffré de bout en bout aux services traitant la requête HTTP. Choisissez la topologie en fonction de vos exigences en matière de confidentialité, de fédération et de disponibilité, puis effectuez des tests après toute modification des règles DNS, des certificats, de Synapse ou de Cloudflare.