Wdrażanie Matrix Synapse z Docker Compose i PostgreSQL

Uruchom Synapse jako projekt Docker Compose z trwałym katalogiem konfiguracji i bazą danych PostgreSQL. Poniższa konfiguracja generuje klucze podpisu Synapse i homeserver.yamlłączy je z PostgreSQL, a także utrzymuje nasłuchiwacz HTTP na hoście lokalnym, dzięki czemu możesz umieścić HTTPS i federację za odwrotnym serwerem proxy przed otwarciem serwera na internet.

Synapse to serwer domowy Matrix: przechowuje konta, pokoje, zdarzenia i multimedia dla serwera. Docker Compose uruchamia kontenery Synapse i PostgreSQL z jednego pliku YAML. Jest to punkt wyjścia dla pojedynczej maszyny, a nie kompletne, publiczne wdrożenie Matrix.

Zanim zaczniesz

Zainstaluj Docker Engine i wtyczkę Docker Compose, a następnie sprawdź, czy docker compose versiondziałają. Docker Desktop zawiera Compose w systemach Windows i macOS; użytkownicy Linuksa mogą zainstalować wtyczkę Compose z repozytorium pakietów Dockera. Zobacz instrukcję instalacji Docker Compose .

Przed wygenerowaniem konfiguracji wybierz stałą nazwę serwera Matrix. Pojawia się ona w identyfikatorach użytkowników, takich jak @alex:matrix.example.org, a jej późniejsza zmiana nie jest rutynową edycją nazwy hosta. W tym przykładzie matrix.example.orgjest to zarówno nazwa serwera Matrix, jak i publiczna nazwa hosta. W przypadku serwera publicznego, skieruj jego rekord DNS na swojego hosta i zaplanuj odwrotny serwer proxy HTTPS. Wygenerowany przez Synapse nasłuch HTTP na porcie 8008 nadaje się do testów lokalnych; dokumentacja instalacyjna informuje, że praktyczne użycie wymaga protokołu HTTPS.

1. Utwórz projekt i sekret

Na hoście Dockera utwórz katalog roboczy i foldery trwałe. Folder synapsebędzie zawierał wygenerowaną konfigurację i klucz podpisu; data/postgresbędzie zawierał również pliki bazy danych.

mkdir -p ~/matrix-synapse/synapse ~/matrix-synapse/data/postgres
cd ~/matrix-synapse
umask 077
openssl rand -hex 32

Skopiuj dane wyjściowe polecenia do nowego .envpliku o nazwie DB_PASSWORD=.... Zachowaj ten plik w tajemnicy i utwórz jego bezpieczną kopię zapasową. Compose odczytuje .envpodstawienia w pliku Compose; Synapse nie rozszerza automatycznie tych zmiennych w pliku homeserver.yaml. To samo hasło wpiszesz w tej konfiguracji w kroku 3.

Ilustrujący widok terminala katalogu projektu matrix-synapse zawierającego docker-compose.yml, plik środowiskowy, folder konfiguracji Synapse i folder danych.
Folder projektu oddziela definicję Compose, konfigurację Synapse i trwałe pliki bazy danych.

2. Zdefiniuj dwie usługi

Utwórz docker-compose.ymlw katalogu projektu. W tym przykładzie użyto oficjalnego obrazu Synapse opublikowanego przez Element HQ i PostgreSQL 16. Port Synapse jest powiązany z pętlą zwrotną, a nie z każdym interfejsem sieciowym. Kontrola stanu pomaga Compose poczekać na PostgreSQL przed uruchomieniem Synapse.

services:
  synapse:
    image: ghcr.io/element-hq/synapse:latest
    restart: unless-stopped
    environment:
      SYNAPSE_CONFIG_PATH: /data/homeserver.yaml
    volumes:
      - ./synapse:/data
    ports:
      - "127.0.0.1:8008:8008"
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: --encoding=UTF-8 --lc-collate=C --lc-ctype=C
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U synapse -d synapse"]
      interval: 10s
      timeout: 5s
      retries: 5

Wpisz DB_PASSWORD=your-generated-value, .envużywając losowej wartości z kroku 1. Nie zatwierdzaj tego pliku w systemie kontroli wersji. Jeśli później zmienisz wersję główną PostgreSQL, postępuj zgodnie z procedurą aktualizacji PostgreSQL, zamiast po prostu wskazywać nowszy obraz na istniejący katalog danych.

3. Wygeneruj konfigurację Synapse i wybierz PostgreSQL

Wygeneruj klucz konfiguracji początkowej i podpisu w zamontowanym synapsekatalogu. Użyj tej samej nazwy serwera, którą wybrałeś powyżej. Ustaw jawnie ustawienia statystyk; tutaj jest to no…

docker compose run --rm --no-deps \
  -e SYNAPSE_SERVER_NAME=matrix.example.org \
  -e SYNAPSE_REPORT_STATS=no \
  synapse generate

Oficjalny generatetryb kontenera tworzy homeserver.yamlwymagany klucz podpisu. Otwórz synapse/homeserver.yamli zastąp sekcję bazy danych SQLite następującym kodem. Zastąp PASTE_THE_SAME_DB_PASSWORD_HEREdokładną wartością zapisaną w .env. To pole jest dosłowną wartością konfiguracji Synapse, a nie interpolacją Compose.

database:
  name: psycopg2
  args:
    user: synapse
    password: PASTE_THE_SAME_DB_PASSWORD_HERE
    dbname: synapse
    host: db
    port: 5432
    cp_min: 5
    cp_max: 10
Ilustrujący widok edytora homeserver.yaml z PostgreSQL skonfigurowanym przez psycopg2, bazę danych Synapse, bazę danych hosta, port 5432 i pulę połączeń.
Sekcja bazy danych Synapse wskazuje na nazwę usługi Compose, db, na wewnętrznym porcie PostgreSQL.

Zachowaj wygenerowane dane registration_shared_secretprywatne. Synapse używa ich do rejestracji użytkowników z poziomu wiersza poleceń; każdy, kto je uzyska, może tworzyć konta, w tym administratorzy. Rejestrację publiczną należy pozostawić wyłączoną, chyba że celowo zamierzasz ją udostępnić i zapoznałeś się z powiązanymi zabezpieczeniami przed nadużyciami.

4. Uruchom Synapse i sprawdź logi

Z katalogu zawierającego docker-compose.yml, sprawdź plik Compose i uruchom usługi:

docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail=100 synapse db

Pierwsze polecenie sprawdza, czy Compose może przeanalizować plik i rozwiązać problem DB_PASSWORD. Następne uruchamia bazę danych i serwer domowy w tle. Sprawdź logi pod kątem błędów połączenia z bazą danych lub brakującego pliku konfiguracyjnego. Ponieważ ta konfiguracja montuje foldery lokalne, konfiguracja bazy danych i Synapse jest zachowywana po ponownym utworzeniu kontenerów.

Przykładowy wiersz poleceń terminala z poleceniem docker compose up -d wprowadzonym w celu uruchomienia stosu Synapse.
Po wygenerowaniu i sprawdzeniu konfiguracji uruchom usługi Synapse i PostgreSQL.

5. Zweryfikuj lokalny punkt końcowy i utwórz konto

Uruchom żądanie wersji klienta Matrix z hosta Docker. Odpowiedź JSON oznacza, że ​​API klienta odpowiada; pusta odpowiedź, odmowa połączenia lub błąd HTTP oznacza, że ​​należy sprawdzić logi Synapse i potwierdzić, że port 8008 nasłuchuje.

curl -fsS http://127.0.0.1:8008/_matrix/client/versions

Gdy odpowie, utwórz konto użytkownika w trybie interaktywnym. To polecenie poprosi o podanie nazwy użytkownika i hasła; wybierz „nie” dla konta administratora, chyba że potrzebujesz konta administratora.

docker compose exec synapse register_new_matrix_user \
  -c /data/homeserver.yaml http://localhost:8008
Przykładowy monit terminala z żądaniem curl do punktu końcowego wersji klienta Matrix firmy Synapse na porcie lokalnym 8008.
Pomyślna odpowiedź punktu końcowego wersji potwierdza, że ​​Synapse odpowiada lokalnie. W tym przykładowym komunikacie wyświetlane jest sprawdzenie, a nie wynik testu.

Uczyń to dostępnym bezpiecznie

Mapowanie portów tylko dla hosta lokalnego jest celowe: uniemożliwia bezpośredni dostęp publiczny do niezaszyfrowanego programu nasłuchującego HTTP. W przypadku klientów zdalnych należy skonfigurować odwrotny serwer proxy z prawidłowym certyfikatem TLS i przekierować ścieżki Matrix do Synapse. Serwer proxy musi przekazać nagłówki X-Forwarded-Fori X-Forwarded-Proto; w wygenerowanej konfiguracji programu nasłuchującego należy włączyć obsługę x_forwarded: trueportu 8008. Nie należy ustawiać konteneryzowanego programu nasłuchującego Synapse tak, aby wiązał się tylko z 127.0.0.1, ponieważ uniemożliwia to kontenerowi proxy dotarcie do niego. Jeśli odwrotny serwer proxy również jest konteneryzowany, należy umieścić go i Synapse we współdzielonej sieci Docker i przekierować ścieżki do usługi o nazwie synapse:8008.

Federacja jest oddzielona od lokalnego uruchomienia. Inne serwery Matrix muszą wykryć i połączyć się z Twoim serwerem, zazwyczaj na porcie 8448 lub poprzez delegowane wykrywanie HTTPS. DNS, routing odwrotnego proxy i wszelkie wymagane rekordy muszą być zgodne z wybraną nazwą serwera. Przed zgłoszeniem publicznego serwera domowego należy zapoznać się z dokumentacją odwrotnego proxy i instrukcjami instalacji.well-known Synapse . Połączenia głosowe i wideo również wymagają serwera TURN dla zapewnienia niezawodnej łączności multimedialnej.

Jeśli Synapse nie może połączyć się z PostgreSQL, sprawdź, czy hostjest to db(nazwa usługi Compose), czy oba hasła są identyczne i czy kontener bazy danych jest sprawny. Jeśli nie można nawiązać połączenia z punktem końcowym, sprawdź docker compose pslogi Synapse i czy inna usługa nie korzysta już z portu hosta 8008. Utwórz kopię zapasową zarówno katalogu danych PostgreSQL, jak i klucza konfiguracji i podpisu Synapse; klucz podpisu jest niezbędny do identyfikacji serwera.

Szczegóły konfiguracji PostgreSQL można znaleźć w przewodniku PostgreSQL firmy Synapse . Informacje o opcjach kontenerów i tworzeniu użytkowników można znaleźć w oficjalnej dokumentacji Synapse Docker .

Zostaw komentarz

Skonfiguruj niestandardowy alias pokoju macierzy w swojej własnej domenie

Nadaj pokojowi Matrix łatwy do udostępniania adres w swojej domenie, korzystając z Element lub interfejsu API Matrix, ze sprawdzaniem uprawnień, nazewnictwem Synapse i federacją.

Skonfiguruj coturn, aby zapewnić niezawodne połączenia głosowe i wideo Matrix

Skonfiguruj coturn i Synapse przy użyciu zgodnych poświadczeń TURN, otwórz wymagane porty przekaźnikowe i sprawdź, czy klienci Matrix mogą uzyskać kandydatów na przekaźniki.

Wdrażanie Matrix Synapse z Docker Compose i PostgreSQL

Wdrażanie Matrix Synapse z Docker Compose i PostgreSQL

Skonfiguruj trwały serwer domowy Synapse z Docker Compose, PostgreSQL, prywatną konfiguracją i sprawdź, czy jest on udostępniany przez HTTPS.

Dostosuj motyw i branding Element Web

Ustaw nazwę marki, niestandardowe kolory i zasoby logowania dla wdrożenia Element Web, pamiętając jednocześnie, które części pozostaną markowe dla Element.

Podnieś limit plików Systemd w Synapse bez zgadywania

Podnieś limit plików Systemd w Synapse bez zgadywania

Sprawdź, czy Synapse osiągnął limit otwartych plików dla każdego procesu, ustaw drop-in systemd dla właściwej usługi lub pracownika i zweryfikuj limit aktywności.

Element wyświetla komunikat „Nie udało się odszyfrować”? Przywróć brakujący klucz do pokoju

Element wyświetla komunikat „Nie udało się odszyfrować”? Przywróć brakujący klucz do pokoju

Sprawdź, czy błąd dotyczy jednej przeglądarki lub jednego zdarzenia, a następnie użyj klucza odzyskiwania Element lub zaufanego urządzenia, nie ryzykując utraty zaszyfrowanej historii.

Oczyść stare wiadomości i media Synapse bez utraty danych

Użyj interfejsów API Synapse do czyszczenia historii i multimediów lub ustawień przechowywania, aby bezpiecznie usunąć nieaktualne dane, a następnie zweryfikuj ukończenie operacji i odzyskanie miejsca na dysku.

Zbuduj bota Matrix Echo w Pythonie za pomocą Simple-Matrix-Bot-Lib

Zbuduj bota Matrix Echo w Pythonie za pomocą Simple-Matrix-Bot-Lib

Zainstaluj aktualną bibliotekę, podłącz dedykowane konto Matrix i uruchom małego bota !echo z bezpieczniejszą obsługą poświadczeń i przejrzystym testem.

Połącz Matrix z WhatsApp, Telegramem i Discordem za pomocą oddzielnych mostów

Połącz Matrix z WhatsApp, Telegramem i Discordem za pomocą oddzielnych mostów

Skonfiguruj trzy mosty Mautrix z oddzielnymi rejestracjami, logowaniami i testami, aby uniknąć niespodzianek związanych z siecią Docker, polityką kont i synchronizacją.

Odzyskaj miejsce na dysku Synapse Media bez naruszania współdzielonych plików

Znajdź elementy zapełniające pamięć masową Synapse, ustaw bezpieczne przechowywanie multimediów i wyczyść zdalną pamięć podręczną bez konieczności usuwania plików bezpośrednio z dysku.