Jak skonfigurować serwer Matrix za serwerem proxy Cloudflare

Serwer Matrix może znajdować się za Cloudflare, ale konfiguracja zależy od tego, jak klienci i inne serwery domowe go wykrywają. Standardowy serwer proxy HTTP Cloudflare obsługuje HTTPS na porcie 443; federacja Synapse zazwyczaj domyślnie korzysta z portu 8448, który nie znajduje się na standardowej liście portów proxy Cloudflare. Niezawodnym rozwiązaniem jest udostępnienie Synapse przez odwrotny serwer proxy na porcie 443 i opublikowanie znanych rekordów Matrix, które kierują klientów i ruch federacji do tej nazwy hosta. Alternatywnie, można zachować federację na porcie 8448 i ustawić ten rekord DNS jako przeznaczony wyłącznie dla DNS.

W tym przewodniku wykorzystano Synapse, oficjalną implementację serwera domowego Matrix, z przykładowymi identyfikatorami Matrix @alice:example.comi punktami końcowymi klienta matrix.example.com. Zastąp te nazwy i adresy własnymi. Instrukcje zakładają, że Synapse i odwrotny serwer proxy HTTPS są już zainstalowane. Instrukcje nie obowiązują bez zmian dla każdej implementacji serwera domowego. Sprawdzono z aktualną dokumentacją Cloudflare i Element Synapse z 6 października 2026 r.

Wybierz odpowiedni układ sieci

Serwer proxy Orange-Cloud firmy Cloudflare to odwrotny serwer proxy HTTP/HTTPS. Działa on pomiędzy klientami a źródłem proxy dla żądań internetowych; nie obsługuje każdego dowolnego portu TCP. Standardowe porty HTTPS obejmują porty 443 i 8443, ale nie obsługuje powszechnie używanego portu federacyjnego Synapse – 8448. Zobacz obsługiwane porty sieciowe i ograniczenia proxy w Cloudflare .

Poniżej zastosowano pierwszy układ. Sam rekord DNS z serwerem proxy nie konfiguruje wykrywania macierzy, odwrotnego proxy, protokołu TLS ani zasad zapory sieciowej.

1. Przed skonfigurowaniem DNS wybierz nazwę serwera Matrix

Nazwa serwera Matrix to część identyfikatora użytkownika po dwukropku. W tym przykładzie jest to example.com, więc użytkownicy mają identyfikatory takie jak @alice:example.com. Techniczna nazwa hosta klienta to matrix.example.com. To rozdzielenie pozwala domenie używanej w identyfikatorach użytkowników zachować stabilność, podczas gdy ruch jest delegowany do innej nazwy hosta. Jeśli Synapse jest już zainicjowany, nie zmieniaj go server_nameprzypadkowo: jest on częścią tożsamości użytkownika i pokoju, a jego zmiana jest migracją, a nie dostosowaniem serwera proxy.

Zaplanuj obsługę dwóch małych dokumentów JSON z domeny nazwy serwera:

• https://example.com/.well-known/matrix/clientinformuje zgodnych klientów o konieczności użycia https://matrix.example.com.
• https://example.com/.well-known/matrix/serverinformuje inne serwery domowe, aby osiągnęły federację pod adresem matrix.example.com:443.

Dokument klienta wymaga Access-Control-Allow-Origin: *nagłówka odpowiedzi. Przewodnik po delegowaniu Synapse zawiera przykłady takich rekordów i ich oczekiwaną strukturę: Delegacja federacji Synapse .

2. Utwórz rekordy DNS Cloudflare

W systemie DNS Cloudflare utwórz Arekord o nazwie matrixwskazującej na publiczny adres IPv4 serwera. Dodaj AAAArekord tylko wtedy, gdy źródło ma sprawne połączenie IPv6 i zaporę sieciową skonfigurowaną dla IPv6. Ustaw status proxy nazwy hosta internetowego na Proxied (pomarańczowa chmurka). Jeśli domena główna również wskazuje na ten serwer i będzie obsługiwać znane pliki, przekaż również jej rekord internetowy do proxy.

Zachowaj niepowiązane rekordy, w tym rekordy poczty, z odpowiednimi ustawieniami „tylko DNS”. ​​Rekordy MX i TXT nie są obsługiwane przez serwer proxy. Cloudflare wyjaśnia, że ​​rekord A, AAAA lub CNAME z obsługą serwera proxy kieruje żądania HTTP/HTTPS przez Cloudflare, podczas gdy ustawienia „tylko DNS” zwracają adres źródłowy bezpośrednio: Zachowanie statusu serwera proxy Cloudflare .

Zezwól na przychodzące połączenia HTTPS z Cloudflare do źródła. Aby zapewnić silniejszą ochronę, ogranicz zaporę źródła do opublikowanych zakresów adresów IP Cloudflare i aktualizuj te zakresy. Jeśli adres IP serwera został ujawniony przed aktywacją strefy, serwer proxy DNS nie unieważnia starego adresu; rozważ zmianę adresu IP źródła po aktywacji. Nie zakładaj, że sama pomarańczowa chmura uniemożliwia bezpośredni dostęp do źródła.

3. Skonfiguruj protokół HTTPS między Cloudflare a źródłem

W ustawieniach SSL/TLS Cloudflare należy użyć trybu Pełnego (ścisłego), gdy źródło przedstawia prawidłowy certyfikat dla nazwy hosta, taki jak certyfikat publicznie zaufany lub certyfikat urzędu certyfikacji źródła Cloudflare. Tryb Pełnego (ścisłego) szyfruje połączenie między Cloudflare a źródłem i weryfikuje certyfikat źródła; tryb Elastyczny nie zapewnia tej samej ścieżki TLS od początku do końca. Zobacz dokumentację Cloudflare w trybie Pełnego (ścisłego) .

Zainstaluj certyfikat i klucz prywatny na serwerze proxy odwrotnego, niekoniecznie w Synapse. Serwer proxy odwrotnego powinien nasłuchiwać na publicznym porcie 443 i wewnętrznie przekazywać żądania Matrix do odbiornika HTTP Synapse, zazwyczaj na porcie 8008. Nie udostępniaj publicznie odbiornika Synapse, jeśli serwer proxy odwrotnego ma być jedynym punktem wejścia.

4. Poinformuj Synapse, że znajduje się za zaufanym odwrotnym serwerem proxy

W odpowiednim programie nasłuchującym HTTP w homeserver.yaml, włącz obsługę przekierowanych nagłówków. Uproszczony przykład dla serwera niekonteneryzowanego to:

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

Scal te ustawienia z istniejącym programem nasłuchującym zamiast zastępować całą konfigurację. Utrzymywana dokumentacja Synapse zaleca x_forwarded: truekorzystanie z odwrotnego serwera proxy i sugeruje powiązanie z hostem lokalnym, gdy serwer proxy działa na tym samym hoście. W przypadku wdrożenia kontenera powiązanie Synapse z pętlą zwrotną kontenera może uniemożliwić dotarcie do niego przez serwer proxy hosta; zamiast tego należy użyć adresu sieciowego kontenera lub usługi oraz zapory sieciowej. Przed zmianą ustawień programu nasłuchującego zapoznaj się z aktualnym przewodnikiem po odwrotnym serwerze proxy Synapse .

Przekierowane nagłówki są godne zaufania tylko wtedy, gdy Synapse akceptuje ruch z kontrolowanego serwera proxy. Jeśli Cloudflare jest jedyną trasą internetową, należy uniemożliwić bezpośredni dostęp publiczny do źródła i skonfigurować serwer proxy tak, aby przekazywał prawidłowy adres klienta. $remote_addrW przeciwnym razie adres Nginx będzie adresem Cloudflare, ponieważ Cloudflare jest połączony z Nginx. Skonfiguruj moduł Nginx Real-IP tak, aby ufał tylko opublikowanym zakresom źródłowym Cloudflare przed użyciem CF-Connecting-IP; nigdy nie ufaj temu nagłówkowi od dowolnych klientów internetowych. Utrzymuj interfejs API administratora Synapse w trybie prywatnym, chyba że masz konkretny powód, aby go udostępnić.

5. Trasuj ścieżki macierzy bez ich przepisywania

Skonfiguruj serwer proxy odwrotnego, aby wysyłał zarówno dane, /_matrixjak i /_synapse/clientdo Synapse. Dokładnie zachowaj URI żądania. Sygnatury żądań federacyjnych Synapse mogą się nie powieść, jeśli serwer proxy zdekoduje lub znormalizuje zakodowane segmenty ścieżki.

Oto kompaktowy przykład Nginx dla matrix.example.com. Zakłada on, że dyrektywy certyfikatu TLS są już skonfigurowane dla tego bloku serwera, a odwrotny serwer proxy i Synapse działają na tym samym hoście:

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

Nie dodawaj sufiksu URI do tego wyrażenia regularnego proxy_pass. Dokumentacja serwera proxy Synapse wskazuje kanoniczność URI jako przyczynę błędów podpisu federacyjnego. Dostosuj również client_max_body_sizelimit przesyłania Synapse i limity planu Cloudflare obowiązujące w Twojej strefie. 50MPowyższa wartość jest tylko przykładem, a nie uniwersalnym zaleceniem.

Cloudflare obsługuje WebSockets w swoich planach, a klienci Matrix mogą korzystać z połączeń o długim czasie trwania. Sprawdź, czy Twój serwer proxy zezwala na aktualizację i czy reguły WAF lub limity przepustowości nie odrzucają uzasadnionych żądań Matrix. Dokumentacja WebSockets Cloudflare opisuje sposób obsługi zaktualizowanych połączeń.

6. Opublikuj znane odpowiedzi

Obsłuż poniższe dwie odpowiedzi przez example.comHTTPS. Możesz je zwrócić z serwera WWW, hosta statycznego lub oddzielnego hosta wirtualnego. Zachowaj oddzielne dokumenty klienta i federacji:

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

Nie używaj przekierowania do niepowiązanego hosta jako zamiennika bez sprawdzenia wymagań wykrywania Matrix i zachowania klienta. Upewnij się, że host o nazwie serwera jest objęty ważnym certyfikatem HTTPS i że Cloudflare nie buforuje nieaktualnych odpowiedzi wykrywania podczas ich zmiany.

7. Utrzymuj dynamiczny ruch API i przesyłanie danych w ramach limitów

Nie buforuj uwierzytelnionych odpowiedzi API Matrix. Dodaj regułę Cloudflare Cache, aby pominąć buforowanie dla ścieżek API Matrix, w tym /_matrix/*i /_synapse/client/*, chyba że masz starannie przetestowany powód, aby inaczej obsłużyć konkretną odpowiedź publiczną. Unikaj ogólnych reguł WAF lub botów, które kwestionują lub blokują punkty końcowe federacji; żądania federacji pochodzą z wielu niezależnych serwerów domowych. Jeśli reguła bezpieczeństwa jest konieczna, przetestuj ją pod kątem logowania klienta, synchronizacji, przesyłania multimediów i federacji, zanim ją generalnie wymusisz.

Przesyłanie danych ma kilka niezależnych limitów: klienta, ustawienia planu lub strefy przesyłania Cloudflare, limit rozmiaru treści odwrotnego serwera proxy oraz limit Synapse max_upload_size. Błąd 413 oznacza, że ​​jeden z tych limitów odrzucił żądanie. Cloudflare publikuje limity przesyłania zależne od planu i zaznacza, że ​​ustawienia te można dostosować w ramach udokumentowanych ograniczeń: strona rozwiązywania problemów z błędem 413 Cloudflare . Podnieś tylko niezbędne limity i przetestuj plik mniejszy niż skonfigurowany limit, zanim je jeszcze bardziej zwiększysz.

8. Sprawdź dostęp klienta, wykrywanie i federację

Uruchom te sprawdzenia z komputera spoza sieci serwera. Zastąp przykładowe nazwy hostów:

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

Pierwsze dwa żądania powinny zwrócić HTTP 200, zawartość JSON oraz oczekiwane wartości. Dokument klienta powinien zawierać nagłówek CORS. Punkt końcowy wersji klienta powinien zwracać JSON z Synapse przez Cloudflare. Punkt końcowy kondycji Synapse zwraca HTTP 200 po osiągnięciu przez skonfigurowany odbiornik, ale nie zastępuje on sprawdzania logowania ani federacji.

Następnie zaloguj się za pomocą klienta Matrix, używając identyfikatora kończącego się na :example.com, dołącz do pokoju hostowanego gdzie indziej i sprawdź, czy wiadomości i aktualizacje członkostwa są synchronizowane. Użyj testera federacji Matrix lub drugiego serwera domowego, aby zweryfikować wykrywanie serwerów i federację. Pomyślne żądanie dowodzi /_matrix/client/versionsjedynie, że trasa skierowana do klienta działa; nie dowodzi ono, że wykrywanie federacji, podpisywanie lub federacja wychodząca są poprawne.

Jak wygląda sukces i kiedy zmienić projekt

• Klienci łączą się przez Cloudflare: DNS rozwiązuje adresy Cloudflare, HTTPS używa właściwego certyfikatu, a interfejs API klienta Matrix zwraca odpowiedź.
• Odkrycie jest poprawne: oba znane adresy URL zwracają właściwy JSON, a dokument klienta przechodzi kontrolę międzydomenową.
• Federacja działa: serwer zdalny wykrywa Twój reklamowany punkt końcowy i może wymieniać stany pomieszczeń. Jeśli delegowanie 443 się nie powiedzie, ale bezpośrednie 8448 działa, sprawdź dobrze znany rekord, routing ścieżek proxy i reguły WAF.
• Przesyłanie działa w oczekiwanym rozmiarze: przetestuj przesyłanie reprezentatywne. Jeśli małe pliki zostaną przesłane poprawnie, ale większe zwrócą błąd 413, porównaj wszystkie cztery limity rozmiaru, zamiast zmieniać tylko Synapse.
• Źródło nie jest alternatywną ścieżką publiczną: bezpośrednie żądania do źródła powinny być blokowane lub ograniczane zgodnie z przeznaczeniem. Jeśli nadal docierają do usługi Matrix, popraw konfigurację zapory sieciowej i zaufanego serwera proxy.

Użyj federacji tylko DNS na porcie 8448, jeśli Twoje wymagania lub implementacja nie umożliwiają kierowania federacji na port 443. Pamiętaj jednak, że ujawnia to adres źródłowy i usuwa ochronę proxy HTTP Cloudflare dla tej nazwy hosta. Spectrum to kolejna opcja dla niestandardowych portów, zależna od dostępności produktu i ograniczeń planu. Proxy Cloudflare oznaczają również, że protokół TLS kończy się w Cloudflare przed drugim połączeniem TLS z Twoim źródłem. Szyfrowanie typu end-to-end w Matrix chroni zaszyfrowaną treść wiadomości, ale nie ukrywa metadanych połączenia ani treści, które nie są szyfrowane end-to-end, przed usługami obsługującymi żądanie HTTP. Wybierz topologię na podstawie wymagań dotyczących prywatności, federacji i dostępności, a następnie przetestuj ponownie po zmianach w DNS, certyfikatach, Synapse lub regułach Cloudflare.