So richten Sie einen Matrix-Server hinter einem Cloudflare-Proxy ein

Ein Matrix-Server kann hinter Cloudflare betrieben werden, die Konfiguration hängt jedoch davon ab, wie Clients und andere Homeserver ihn finden. Der Standard-HTTP-Proxy von Cloudflare unterstützt HTTPS auf Port 443; Synapse Federation verwendet üblicherweise Port 8448, der nicht in der Liste der standardmäßigen Proxy-Ports von Cloudflare enthalten ist. Eine zuverlässige Lösung besteht darin, Synapse über einen Reverse-Proxy auf Port 443 bereitzustellen und bekannte Matrix-Einträge zu veröffentlichen, die Client- und Federation-Traffic an diesen Hostnamen weiterleiten. Alternativ kann Federation auf Port 8448 belassen und dieser DNS-Eintrag als reiner DNS-Eintrag konfiguriert werden.

Diese Anleitung verwendet Synapse, die offizielle Matrix-Homeserver-Implementierung, mit den Beispiel-Matrix-IDs @alice:example.comund Client-Endpunkten matrix.example.com. Ersetzen Sie diese Namen und Adressen durch Ihre eigenen. Die Anweisungen setzen voraus, dass Synapse und ein HTTPS-Reverse-Proxy bereits installiert sind. Sie gelten nicht ohne Weiteres für jede Homeserver-Implementierung. Geprüft anhand der aktuellen Cloudflare- und Element-Synapse-Dokumentation vom 6. Oktober 2026.

Wählen Sie das richtige Netzwerk-Layout

Der Orange-Cloud-Proxy von Cloudflare ist ein HTTP/HTTPS-Reverse-Proxy. Er fungiert als Vermittler zwischen Clients und Ihrem Ursprungsserver für weitergeleitete Webanfragen; er unterstützt nicht jeden beliebigen TCP-Port. Zu seinen Standard-HTTPS-Ports gehören 443 und 8443, jedoch nicht der von Synapse häufig verwendete Federation-Port 8448. Weitere Informationen finden Sie unter den von Cloudflare unterstützten Netzwerkports und den Einschränkungen der Proxy-Funktion .

Das erste Layout wird im Folgenden verwendet. Ein proxied DNS-Eintrag konfiguriert allein weder Matrix-Discovery, Reverse-Proxying, TLS noch Firewall-Richtlinien.

1. Legen Sie den Namen des Matrix-Servers fest, bevor Sie DNS konfigurieren.

Der Matrix-Servername ist der Teil nach dem Doppelpunkt in der Benutzer-ID. In diesem Beispiel ist es `<servername>` example.com, daher haben Benutzer IDs wie `<servername> @alice:example.com`. Der technische Client-Hostname ist `<client-hostname>` matrix.example.com. Durch diese Trennung bleibt die in den Benutzer-IDs verwendete Domäne stabil, während der Datenverkehr an einen anderen Hostnamen weitergeleitet wird. Wenn Synapse bereits initialisiert ist, sollten Sie die Einstellungen nicht server_nameleichtfertig ändern: Sie sind Teil der Benutzer- und Raumidentität, und eine Änderung stellt eine Migration dar, keine Proxy-Anpassung.

Es ist geplant, zwei kleine JSON-Discovery-Dokumente von der Servernamensdomäne bereitzustellen:

• https://example.com/.well-known/matrix/clientweist kompatible Clients an, Folgendes zu verwenden https://matrix.example.com:
• https://example.com/.well-known/matrix/serverweist andere Homeserver an, die Föderation unter . zu erreichen matrix.example.com:443.

Das Clientdokument benötigt einen Access-Control-Allow-Origin: *Antwortheader. Der Synapse-Delegierungsleitfaden enthält Beispiele für diese Datensätze und deren erwartete Struktur: Synapse-Federationsdelegierung .

2. Erstellen Sie die Cloudflare-DNS-Einträge.

Erstellen Sie in Cloudflare DNS einen AEintrag matrix, der auf die öffentliche IPv4-Adresse des Servers verweist. Fügen Sie AAAAnur dann einen Eintrag hinzu, wenn der Ursprungsserver über eine funktionierende IPv6-Verbindung verfügt und eine Firewall für IPv6 konfiguriert ist. Setzen Sie den Proxy-Status des Web-Hostnamens auf „ Proxied “ (orangefarbene Wolke). Wenn die Stammdomäne ebenfalls auf diesen Server verweist und die bekannten Dateien bereitstellt, richten Sie auch deren Web-Eintrag als Proxy ein.

Unabhängige Datensätze, einschließlich E-Mail-Datensätze, sollten gemäß den entsprechenden DNS-Only-Einstellungen verwaltet werden. MX- und TXT-Einträge werden nicht über einen Proxy geleitet. Cloudflare erklärt, dass ein über einen Proxy geleiteter A-, AAAA- oder CNAME-Eintrag HTTP/HTTPS-Anfragen über Cloudflare weiterleitet, während DNS-Only die Ursprungsadresse direkt zurückgibt: Cloudflare-Proxy-Statusverhalten .

Erlauben Sie eingehende HTTPS-Verbindungen von Cloudflare zum Ursprungsserver. Für einen besseren Schutz beschränken Sie die Firewall des Ursprungsservers auf die von Cloudflare veröffentlichten IP-Bereiche und halten Sie diese aktuell. Falls die IP-Adresse des Servers vor der Aktivierung der Zone offengelegt wurde, wird diese alte Adresse durch die DNS-Proxy-Nutzung nicht ungültig. Erwägen Sie daher, die Ursprungs-IP-Adresse nach der Aktivierung zu ändern. Gehen Sie nicht davon aus, dass die orangefarbene Wolke allein den direkten Zugriff vom Ursprungsserver verhindert.

3. Konfigurieren Sie HTTPS zwischen Cloudflare und dem Ursprungsserver.

Verwenden Sie in den SSL/TLS-Einstellungen von Cloudflare die Option „ Vollständig (streng)“, wenn der Ursprungsserver ein gültiges Zertifikat für den Hostnamen vorlegt, z. B. ein öffentlich vertrauenswürdiges Zertifikat oder ein Cloudflare-Ursprungszertifizierungsstellenzertifikat. Die Option „Vollständig (streng)“ verschlüsselt die Verbindung zwischen Cloudflare und dem Ursprungsserver und validiert das Ursprungszertifikat. Der flexible Modus bietet diese durchgängige TLS-Verschlüsselung nicht. Weitere Informationen finden Sie in der Dokumentation zu „Vollständig (streng)“ von Cloudflare .

Installieren Sie das Zertifikat und den privaten Schlüssel auf dem Reverse-Proxy, nicht unbedingt in Synapse. Der Reverse-Proxy sollte auf dem öffentlichen Port 443 lauschen und Matrix-Anfragen intern an den HTTP-Listener von Synapse weiterleiten (üblicherweise Port 8008). Stellen Sie den Synapse-Listener nicht öffentlich zur Verfügung, wenn der Reverse-Proxy der einzige Zugangspunkt sein soll.

4. Teilen Sie Synapse mit, dass es sich hinter einem vertrauenswürdigen Reverse-Proxy befindet.

Aktivieren Sie im entsprechenden HTTP-Listener homeserver.yamldie Weiterleitung von Headern. Ein vereinfachtes Beispiel für einen nicht containerisierten Server:

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

Integrieren Sie diese Einstellungen in den bestehenden Listener, anstatt die gesamte Konfiguration zu ersetzen. Die Dokumentation von Synapse empfiehlt x_forwarded: truedie Verwendung eines Reverse-Proxys und schlägt vor, Synapse an localhost zu binden, wenn der Proxy auf demselben Host läuft. Bei einer Containerbereitstellung kann die Bindung von Synapse an den Loopback des Containers verhindern, dass der Host-Proxy den Listener erreicht. Verwenden Sie stattdessen die Netzwerkadresse des Containers oder Dienstes und schützen Sie diesen Pfad mit einer Firewall. Lesen Sie die aktuelle Synapse-Anleitung für Reverse-Proxys, bevor Sie die Listener-Einstellungen ändern.

Weitergeleitete Header sind nur dann vertrauenswürdig, wenn Synapse Datenverkehr von Ihrem kontrollierten Proxy akzeptiert. Wenn Cloudflare der einzige öffentliche Zugriff auf das Internet ist, verhindern Sie den direkten Zugriff auf den Ursprungsserver und konfigurieren Sie den Proxy so, dass er die korrekte Clientadresse weiterleitet. $remote_addrAndernfalls verwendet Nginx die Cloudflare-Adresse, da Cloudflare mit Nginx verbunden ist. Konfigurieren Sie das Real-IP-Modul von Nginx so, dass es nur den von Cloudflare veröffentlichten Quellbereichen vertraut, bevor Sie die Header verwenden CF-Connecting-IP; vertrauen Sie niemals diesem Header von beliebigen Internetclients. Halten Sie die Synapse-Admin-API privat, es sei denn, Sie haben einen triftigen Grund, sie offenzulegen.

5. Routenmatrixpfade erstellen, ohne sie neu zu schreiben

Konfigurieren Sie Ihren Reverse-Proxy so, dass er sowohl den Pfad /_matrixals auch /_synapse/clientdie Anfrage an Synapse sendet. Die Anfrage-URI muss exakt beibehalten werden. Signaturen von Synapse-Federationsanfragen können fehlschlagen, wenn ein Proxy kodierte Pfadsegmente dekodiert oder normalisiert.

Hier ist ein kompaktes Nginx-Beispiel für matrix.example.com. Es setzt voraus, dass Ihre TLS-Zertifikatdirektiven bereits für diesen Serverblock konfiguriert sind und dass der Reverse-Proxy und Synapse auf demselben Host laufen:

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;
    }
}

Fügen Sie diesem regulären Ausdruck kein URI-Suffix hinzu proxy_pass. Die Synapse-Proxy-Dokumentation weist darauf hin, dass die URI-Kanonisierung zu Fehlern bei der Verbundsignatur führen kann. Passen Sie den Wert außerdem client_max_body_sizean das Synapse-Uploadlimit und gegebenenfalls an das für Ihre Zone geltende Cloudflare-Tariflimit an. Der 50Moben genannte Wert ist lediglich ein Beispiel und keine allgemeingültige Empfehlung.

Cloudflare unterstützt WebSockets in seinen Tarifen, und Matrix-Clients können dauerhafte Verbindungen nutzen. Stellen Sie sicher, dass Ihr Proxy das Upgrade zulässt und dass WAF- oder Ratenbegrenzungsregeln legitime Matrix-Anfragen nicht ablehnen. Die WebSockets-Dokumentation von Cloudflare beschreibt die Handhabung aktualisierter Verbindungen.

6. Die bekannten Antworten veröffentlichen

Senden Sie die folgenden beiden Antworten über example.comHTTPS. Sie können diese von Ihrem Webserver, einem statischen Host oder einem separaten virtuellen Host zurückgeben. Halten Sie die Client- und Verbunddokumente getrennt:

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"}

Verwenden Sie keine Weiterleitung zu einem nicht zugehörigen Host als Ersatz, ohne vorher die Anforderungen der Matrix-Erkennung und das Clientverhalten zu prüfen. Stellen Sie sicher, dass der Servername über ein gültiges HTTPS-Zertifikat verfügt und dass Cloudflare keine veralteten Erkennungsantworten zwischenspeichert, während Sie diese ändern.

7. Halten Sie den API-Traffic dynamisch und die Uploads innerhalb der zulässigen Grenzen.

Authentifizierte Matrix-API-Antworten sollten nicht zwischengespeichert werden. Fügen Sie eine Cloudflare-Cache-Regel hinzu, um das Caching für die Matrix-API-Pfade (einschließlich `<Pfad1>` /_matrix/*und /_synapse/client/*`<Pfad2>`) zu umgehen, es sei denn, Sie haben einen sorgfältig getesteten Grund, eine bestimmte öffentliche Antwort anders zu behandeln. Vermeiden Sie allgemeine WAF- oder Bot-Regeln, die Verbundendpunkte abfragen oder blockieren; Verbundanfragen stammen von vielen unabhängigen Homeservern. Falls eine Sicherheitsregel erforderlich ist, testen Sie diese für Client-Login, Synchronisierung, Medien-Upload und Verbund, bevor Sie sie allgemein anwenden.

Uploads unterliegen mehreren unabhängigen Beschränkungen: der Client-Beschränkung, der Upload-Einstellung des Cloudflare-Tarifs oder der Zone, der Beschränkung der Dateigröße des Reverse-Proxys und der Beschränkung von Synapse max_upload_size. Ein 413-Fehler bedeutet, dass eine dieser Beschränkungen die Anfrage abgelehnt hat. Cloudflare veröffentlicht die tarifabhängigen Upload-Beschränkungen und weist darauf hin, dass diese Einstellungen innerhalb der dokumentierten Grenzen angepasst werden können: Cloudflare-Seite zur Fehlerbehebung bei 413-Fehlern . Erhöhen Sie nur die notwendigen Beschränkungen und testen Sie die Uploads mit einer Datei, die kleiner als die konfigurierte Obergrenze ist, bevor Sie die Beschränkungen weiter erhöhen.

8. Clientzugriff, -erkennung und -föderation überprüfen

Führen Sie diese Prüfungen von einem Rechner außerhalb des Netzwerks Ihres Servers aus. Ersetzen Sie die Beispiel-Hostnamen:

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

Die ersten beiden Anfragen sollten HTTP 200, JSON-Inhalt und die erwarteten Werte zurückgeben. Das Clientdokument sollte den CORS-Header enthalten. Der Clientversions-Endpunkt sollte JSON von Synapse über Cloudflare zurückgeben. Der Synapse-Health-Endpunkt gibt HTTP 200 zurück, wenn er über einen konfigurierten Listener erreicht wird, ersetzt aber nicht die Überprüfung von Login oder Federation.

Melden Sie sich anschließend mit einem Matrix-Client und einer ID an, die auf „.matrix“ endet :example.com, treten Sie einem extern gehosteten Raum bei und überprüfen Sie, ob Nachrichten und Mitgliedschaftsaktualisierungen synchronisiert werden. Verwenden Sie einen Matrix-Federationstester oder einen zweiten Homeserver, um die Servererkennung und die Federation zu validieren. Eine erfolgreiche Anfrage an „.matrix“ /_matrix/client/versionsbeweist lediglich, dass die clientseitige Route funktioniert; sie beweist nicht, dass die Federation-Erkennung, die Signierung oder die ausgehende Federation korrekt funktionieren.

Wie Erfolg aussieht – und wann man das Design ändern sollte

• Die Clients stellen eine Verbindung über Cloudflare her: DNS wird zu Cloudflare-Adressen aufgelöst, HTTPS verwendet das vorgesehene Zertifikat, und die Matrix-Client-API gibt eine Antwort zurück.
• Die Erkennung ist korrekt: Beide bekannten URLs liefern das richtige JSON und das Client-Dokument besteht die Cross-Origin-Prüfungen.
• Die Föderation funktioniert: Ein Remote-Server erkennt Ihren angekündigten Endpunkt und kann den Raumstatus austauschen. Falls die Delegierung von Port 443 fehlschlägt, die direkte Weiterleitung über Port 8448 jedoch funktioniert, überprüfen Sie den bekannten Eintrag, das Proxy-Pfad-Routing und die WAF-Regeln.
• Uploads funktionieren bei der erwarteten Größe: Testen Sie einen repräsentativen Upload. Wenn kleine Dateien erfolgreich hochgeladen werden, größere Dateien aber den Fehlercode 413 zurückgeben, vergleichen Sie alle vier Größenbeschränkungen, anstatt nur Synapse zu ändern.
• Der Ursprung ist kein alternativer öffentlicher Pfad: Direkte Anfragen an den Ursprung sollten wie vorgesehen blockiert oder eingeschränkt werden. Falls sie dennoch den Matrix-Dienst erreichen, korrigieren Sie die Firewall- und Trusted-Proxy-Konfiguration.

Verwenden Sie DNS-only-Federation auf Port 8448, falls Ihre Anforderungen oder Implementierung keine Federation-Weiterleitung über Port 443 zulassen. Beachten Sie jedoch, dass dadurch die Ursprungsadresse offengelegt und der HTTP-Proxy-Schutz von Cloudflare für diesen Hostnamen aufgehoben wird. Spectrum ist eine weitere Option für nicht standardmäßige Ports, abhängig von der Produktverfügbarkeit und den Tarifbeschränkungen. Cloudflare-Proxying bedeutet außerdem, dass TLS bei Cloudflare beendet wird, bevor eine zweite TLS-Verbindung zu Ihrem Ursprungsserver hergestellt wird. Die Ende-zu-Ende-Verschlüsselung von Matrix schützt zwar verschlüsselte Nachrichteninhalte, verbirgt aber weder Verbindungsmetadaten noch Inhalte, die nicht Ende-zu-Ende-verschlüsselt sind, vor den Diensten, die die HTTP-Anfrage verarbeiten. Wählen Sie die Topologie basierend auf Ihren Anforderungen an Datenschutz, Federation und Verfügbarkeit und testen Sie sie nach Änderungen an DNS, Zertifikaten, Synapse oder Cloudflare-Regeln erneut.