Uczyń swój serwer Matrix Synapse dostępnym dla federacji

Aby skonfigurować serwer domowy Matrix Synapse jako federacyjny, należy skonfigurować jego nazwę serwera jako wykrywalną i dostępną z publicznego internetu przez HTTPS, a następnie kierować żądania między serwerami Matrix do Synapse. W typowej konfiguracji odwrotny serwer proxy obsługuje TLS na porcie 443, a plik /.well-known/matrix/serverkieruje domenę Matrix do tego serwera proxy. Jeśli Synapse już odpowiada w domenie o nazwie serwera na porcie 8448, delegowanie może nie być konieczne.

W tym przewodniku użyj example.comstałej nazwy serwera Matrix oraz matrix.example.comnazwy komputera lub punktu końcowego proxy. Zastąp obie własnymi nazwami. Serwer domowy przechowuje konta i pokoje Matrix; federacja umożliwia komunikację między serwerami domowymi. DNS, reguły zapory sieciowej, składnia proxy, obsługa kontenerów sieciowych i certyfikaty zależą od hosta.

Przed zmianą konfiguracji

Zdecyduj, czy identyfikatory użytkowników Matrix mają wyglądać jak @name:example.com, czy @name:matrix.example.com. Wartość „ server_namein” homeserver.yamlstaje się częścią identyfikatorów Matrix i adresów pokoi. Dokumentacja instalacyjna Synapse zaleca wybranie tej opcji przed instalacją, ponieważ nie można jej później zmienić bez konsekwencji. Jeśli Synapse jest już używany, nie zmieniaj go tylko po to, by dopasować go do adresu internetowego; użyj delegacji, aby zachować istniejące identyfikatory.

Edytor YAML wyświetla server_name: example.com i przypomnienie o konieczności wybrania wartości przed instalacją.
Nazwa serwera jest częścią identyfikatora Matrix, dlatego przed kontynuowaniem należy ją potwierdzić.

Przed edycją upewnij się, że masz dostęp do Synapse, serwera proxy i publicznego DNS oraz posiadasz ważny certyfikat TLS dla punktu końcowego federacji. Utwórz kopię zapasową homeserver.yamlklucza podpisu, który określa tożsamość serwera domowego. Przechowuj ten klucz w bezpiecznym miejscu; rutynowa konfiguracja federacji nie wymaga jego ponownego generowania.

Skonfiguruj trasę publiczną

1. Potwierdź nasłuchiwanie HTTP Synapse

Synapse zazwyczaj nasłuchuje HTTP na porcie 8008za odwrotnym serwerem proxy. W odbiorniku akceptującym ruch proxy należy ustawić opcję, x_forwarded: trueaby Synapse mógł korzystać z przekierowanego adresu klienta i schematu serwera proxy. Serwer proxy musi ustawić odpowiednie nagłówki X-Forwarded-Fori X-Forwarded-Proto, zamiast przekazywać dowolne wartości dostarczane przez zewnętrznych klientów.

Fragment programu nasłuchującego YAML pokazuje Synapse na porcie HTTP 8008 z włączoną opcją x_forwarded i adresem powiązania pętli zwrotnej.
Obiekt nasłuchujący akceptuje protokół HTTP z lokalnego serwera proxy i włącza obsługę przekazywanego nagłówka przez program Synapse.

Powiązanie z 127.0.0.1jest odpowiednie, gdy serwer proxy działa na tym samym hoście. Nie jest ono odpowiednie, gdy serwer proxy znajduje się w innym kontenerze lub na innym komputerze, chyba że adres ten jest dostępny z serwera proxy. W przypadku wdrożenia kontenera należy użyć adresu sieciowego lub nazwy usługi, do których serwer proxy może dotrzeć, i ograniczyć dostęp przez sieć kontenera lub zaporę sieciową. Zachowaj istniejącą strukturę nasłuchiwacza i edytuj odpowiednie wartości; nie wklejaj fragmentu bezmyślnie na resztę konfiguracji.

2. Trasy macierzy tras przez serwer proxy

Skonfiguruj wirtualny host HTTPS serwera proxy, aby przekierowywał zarówno dane, /_matrixjak i /_synapse/clientdo nasłuchiwacza HTTP Synapse. Pierwsza ścieżka przenosi interfejsy API Matrix, w tym federację; druga jest używana dla punktów końcowych klienta Synapse. Postępuj zgodnie z oficjalnym przykładem dla swojego oprogramowania proxy, zachowaj ścieżkę żądania i wyślij przekierowane nagłówki, których oczekuje Synapse. Nie normalizuj, nie dekoduj ani nie przepisuj ścieżek URI: podpisy żądań Matrix mogą się nie powieść, jeśli serwer proxy zmieni zakodowaną ścieżkę.

Edytor konfiguracji odwrotnego serwera proxy pokazuje ścieżki klienta Matrix API i Synapse kierowane do portu lokalnego 8008 z przekierowanymi nagłówkami.
Serwer proxy musi przekazać obie ścieżki API Matrix do Synapse bez ponownego przepisywania URI.

Dokładna konfiguracja różni się w zależności od Nginx, Caddy, Apache, modułów równoważenia obciążenia i hostingu zarządzanego. Jako odniesienia należy użyć aktualnej składni dostawcy i dokumentacji odwrotnego proxy Synapse . Reguła proxy obsługująca klienta webowego, ale pomijająca ścieżkę API federacji, nie jest wystarczająca.

3. Upewnij się, że DNS, HTTPS i wybrany port są zgodne

Na przykład, matrix.example.commusi być przekierowany do serwera proxy lub modułu równoważenia obciążenia, a port 443musi być dostępny z zewnątrz. Serwer proxy wymaga ważnego certyfikatu dla matrix.example.com. Jeśli zamiast tego obsługujesz federację bezpośrednio w example.com:8448, opublikuj tę trasę i certyfikat oraz otwórz port 8448. Użyj albo bezpośredniego portu 8448, standardowego portu domyślnego, albo delegowania do innego hosta i portu, takiego jak 443.

Potwierdź reguły DNS, zapory sieciowej lub grupy zabezpieczeń w chmurze oraz certyfikat spoza sieci prywatnej. Jeśli na pierwszym planie znajduje się sieć CDN lub tunel, to czy obsługuje on wymagany ruch Matrix, zależy od bieżącej konfiguracji tej usługi; sprawdź jej dokumentację i przetestuj rzeczywistą trasę, zamiast zakładać zgodność.

Publikuj odkrycie federacji, gdy jest to potrzebne

4. Dodaj delegację serwera dla osobnego punktu końcowego

Jeżeli domeną identyfikatora Matrix jest , example.comale Synapse jest dostępny pod adresem matrix.example.com:443, prześlij ten JSON przez HTTPS pod adresem https://example.com/.well-known/matrix/server:

{
  "m.server": "matrix.example.com:443"
}
Widok JSON w stylu przeglądarki pod adresem example.com/.well-known/matrix/server zawiera wartość m.server matrix.example.com:443.
Ten rekord wykrywania federacji deleguje example.com do punktu końcowego HTTPS w matrix.example.com na porcie 443.

Port 443 jest w tym przykładzie jawny; jeśli pominiesz port, funkcja Matrix Discovery domyślnie ustawi port 8448. Nie należy mylić tego pliku z plikiem /.well-known/matrix/client, który pomaga klientom znaleźć API klient-serwer i jest niezależny od federacji serwer-serwer. Synapse może sam udostępnić plik znanego serwera, gdy domena nazwy serwera jest kierowana bezpośrednio do Synapse, ale z oddzielnym punktem końcowym zazwyczaj publikujesz plik na serwerze internetowym domeny nazwy serwera.

Odkrywanie federacji jest określone przez Matrix i udokumentowane przez Synapse. Specyfikacja Matrix umożliwia odnajdywanie poprzez /.well-known/matrix/server; przed wyborem innej metody, takiej jak rekord SRV, należy sprawdzić instrukcje delegacji Synapse , co również wpływa na oczekiwania TLS.

Testuj spoza serwera

5. Zweryfikuj rekord, a następnie uruchom sprawdzanie federacji

Zażądaj adresu URL wykrywania z komputera spoza prywatnej sieci serwera. Powinien on zwrócić powyższy obiekt JSON przez HTTPS bez strony logowania, przekierowania HTML, ostrzeżenia o certyfikacie ani niepowiązanej witryny. Następnie sprawdź, czy delegowana nazwa hosta jest rozpoznawana, jej certyfikat jest prawidłowy i czy jej port reklamowy dociera do Synapse. Przed testowaniem skorzystaj z narzędzia do sprawdzania konfiguracji i procedury przeładowania serwera proxy.

Na koniec wprowadź nazwę swojego serwera (na przykład , example.comnie delegowaną nazwę hosta, chyba że to Twój server_name) w oficjalnym narzędziu Matrix Federation Tester . Przewodnik po federacji Synapse sugeruje również testowanie poprzez dołączenie do pokoju publicznego, takiego jak #synapse:matrix.org. Pomyślne sprawdzenie potwierdza, że ​​typowe testy wykrywania i dostępności zostały pomyślnie wykonane; nie gwarantuje to jednak, że każdy zdalny serwer lub każda operacja w pokoju będzie działać, ponieważ zasady zdalne i warunki sieciowe są różne.

Jeśli tester zgłosi brak połączenia z serwerem, sprawdź domenę i port, które testował, DNS, reguły zapory sieciowej, nazwę certyfikatu, ścieżki proxy, przekierowane nagłówki oraz to, czy przekierowanie zmieniło żądanie. Aktualna dokumentacja federacji Synapse wyraźnie ostrzega, że ​​serwery federacyjne Synapse mogą w niektórych przypadkach nie stosować przekierowań HTTP 308. Unikaj polegania na przekierowaniu 308 dla punktu końcowego federacji i przetestuj ponownie po jego poprawieniu. Zapoznaj się z dokumentacją odpowiadającą zainstalowanej wersji Synapse, aby poznać zachowanie specyficzne dla danej wersji.

Federacja wymaga, aby zdalne serwery domowe wykryły i nawiązały dostęp do interfejsu API federacji. Nie można stwierdzić, czy to zadziała dla każdego serwera zdalnego, wyłącznie na podstawie konfiguracji. Potwierdź trasę z testerem i rzeczywistym połączeniem z pokojem, a następnie zbadaj konkretny niedziałający punkt końcowy lub błąd.

Te panele interfejsu to schematyczne przykłady danych konfiguracyjnych i wykrywania, a nie zrzuty ekranu z działającego serwera. Odniesienia do dokumentacji sprawdzono 10 października 2026 r.

Zostaw komentarz

Rozwiąż błędy uprawnień administratora pokoju Matrix za pomocą działania

Prześledź M_FORBIDDEN do poziomów mocy pokoju, członkostwa lub dostępu administratora serwera Synapse, a następnie przywróć tylko uprawnienia potrzebne do zablokowanej akcji.

Uczyń swój serwer Matrix Synapse dostępnym dla federacji

Uczyń swój serwer Matrix Synapse dostępnym dla federacji

Skonfiguruj wykrywanie Synapse, protokół HTTPS i routing proxy, aby inne serwery domowe Matrix mogły znaleźć Twój serwer i nawiązać z nim kontakt.

Połącz Element Web z Keycloak przez Synapse OIDC

Skonfiguruj klienta Keycloak OIDC i dostawcę Synapse, aby użytkownicy Element Web mogli logować się za pośrednictwem serwera tożsamości bez ujawniania tajnych danych klienta.

Bezpieczna konfiguracja kopii zapasowej klucza elementu i podpisywania krzyżowego

Bezpieczna konfiguracja kopii zapasowej klucza elementu i podpisywania krzyżowego

Zapisz klucz odzyskiwania, zweryfikuj sesje Element i sprawdź, czy zaszyfrowane klucze wiadomości można odzyskać, nie myląc kopii zapasowej z hasłem do konta.

Zatrzymaj awarię pamięci Matrix Synapse podczas synchronizacji klienta

Diagnozuj błędy braku pamięci w Synapse podczas synchronizacji, bezpiecznie dostosowuj buforowanie, identyfikuj zaległości w żądaniach i weryfikuj stabilne wykorzystanie pamięci.

Rozwiązywanie błędów certyfikatu TLS federacji Synapse

Śledź błędy certyfikatu federacji Matrix na właściwym serwerze, napraw łańcuch TLS lub zaufanie urzędu certyfikacji i zweryfikuj poprawkę bez wyłączania kontroli bezpieczeństwa.

Bezpiecznie umieść serwer Synapse Matrix za Cloudflare

Bezpiecznie umieść serwer Synapse Matrix za Cloudflare

Klienci i federacja Matrix korzystają z usługi Cloudflare na protokole HTTPS 443, zachowując wykrywanie Synapse i unikając buforowania ruchu API lub przerywania przesyłania multimediów.

Bezpieczne przywracanie Matrix Synapse za pomocą zrzutu PostgreSQL

Utwórz kopię zapasową Synapse za pomocą pg_dump, chroń jej klucz podpisu i nośnik, a następnie przywróć do czystej bazy danych PostgreSQL bez ponownego używania nieaktualnych kluczy jednorazowych.

Uruchom Mjölnir jako bota moderującego pokój Matrix za pomocą Dockera

Uruchom Mjölnir jako bota moderującego pokój Matrix za pomocą Dockera

Skonfiguruj Mjölnir przy użyciu dedykowanego konta Matrix, szyfrowanego pokoju zarządzania, Docker Compose, listy zasad i kontroli uprawnień.

Włącz natywną synchronizację Matrix Sliding, aby przyspieszyć ładowanie urządzeń mobilnych

Włącz natywną synchronizację Matrix Sliding, aby przyspieszyć ładowanie urządzeń mobilnych

Pomiń wycofany serwer proxy i skonfiguruj wbudowaną funkcję Sliding Sync w Synapse. Sprawdź wykrywanie klientów, a następnie zmierz ładowanie listy pokoi i zachowanie ponownego łączenia na kompatybilnym telefonie.