Jeśli Matrix Synapse w CasaOS wyświetla komunikat „container is unhealthy”, zacznij od logów kontenera i wygenerowanego pliku homeserver.yaml, zamiast bez zastanowienia przeinstalowywać aplikację. Synapse ma oficjalny obraz Dockera, ale produkcyjny serwer domowy wymaga również trwałej konfiguracji i danych, prawidłowej nazwy serwera, PostgreSQL oraz planu dotyczącego HTTPS i federacji.
SQLite nadaje się do testów, ale aktualna dokumentacja Synapse zaleca PostgreSQL w niemal wszystkich rzeczywistych instalacjach. Kontener może się uruchomić, a mimo to pozostać w stanie niezdrowym, gdy jego konfiguracja, baza danych, uprawnienia lub migracja uruchamiana podczas startu zawiedzie.
Użyj oficjalnego obrazu Synapse
Aktualny przewodnik instalacji Synapse wskazuje ghcr.io/element-hq/synapse jako oficjalny obraz kontenera.
Wygeneruj początkową konfigurację
Utwórz trwały katalog i wygeneruj konfigurację przed zwykłym uruchomieniem:
mkdir -p /DATA/AppData/synapse
docker run --rm -it -v /DATA/AppData/synapse:/data -e SYNAPSE_SERVER_NAME=matrix.example.com -e SYNAPSE_REPORT_STATS=no ghcr.io/element-hq/synapse:latest generateZastąp przykładową domenę nazwą serwera Matrix, której zamierzasz używać na stałe.
Sprawdź, dlaczego kontener jest w stanie niezdrowym
docker ps -a | grep synapse
docker inspect synapse --format '{{json .State.Health}}'
docker logs --tail 200 synapseSzukaj błędów YAML, brakujących plików, problemów z uprawnieniami, błędów połączenia z bazą danych lub migracji, które nigdy się nie kończą.
Używaj PostgreSQL w środowisku produkcyjnym
Aktualny przewodnik Synapse dotyczący PostgreSQL wyjaśnia obsługiwaną konfigurację bazy danych. Przechowuj dane PostgreSQL w trwałym magazynie i twórz ich kopie zapasowe razem ze stanem Synapse.
Nie zmieniaj później server_name bez odpowiedniego planu
Identyfikatory Matrix są tworzone na podstawie nazwy serwera, na przykład @user:example.com. Wybierz docelową domenę przed zaproszeniem użytkowników.
HTTPS jest wymagany do praktycznego użytkowania
Synapse zwykle nasłuchuje wewnętrznie przez HTTP, najczęściej na porcie 8008. Użyj odwrotnego serwera proxy z HTTPS dla klientów i federacji, zamiast publicznie udostępniać bezpośrednio port kontenera.
Federacja wymaga dodatkowej konfiguracji DNS i serwera proxy
Jeśli chcesz komunikować się z innymi serwerami Matrix, prawidłowo skonfiguruj publiczną nazwę serwera, HTTPS i wykrywanie federacji. Test lokalny może być znacznie prostszy.
Twórz kopie zapasowe nie tylko kontenera
Zachowaj homeserver.yaml, klucze podpisywania, przesłane multimedia oraz bazę danych PostgreSQL. Ponowne pobranie obrazu nie przywróci tożsamości serwera domowego.
Przewodnik rozwiązywania problemów z Dockerem przedstawia ogólny model debugowania kontenerów.
Sprawdź właściciela plików w trwałym katalogu danych
Jeśli log kontenera zgłasza odmowę dostępu podczas odczytu homeserver.yaml, kluczy podpisywania lub multimediów, zmień właściciela zamapowanego katalogu danych Synapse na UID/GID oczekiwany przez obraz. Unikaj nadawania całemu drzewu danych CasaOS uprawnień do zapisu dla wszystkich użytkowników.
Poczekaj na migracje bazy danych przed oceną stanu
Po aktualizacji lub pierwszym połączeniu z PostgreSQL Synapse może potrzebować czasu na wykonanie migracji schematu. Obserwuj logi zamiast wielokrotnie uruchamiać ponownie kontener, ponieważ przerwane migracje mogą utrudnić diagnozę.
Przetestuj lokalne API przed skonfigurowaniem odwrotnego serwera proxy
Upewnij się, że wewnętrzny punkt końcowy HTTP Synapse odpowiada z hosta CasaOS, zanim dodasz HTTPS, DNS lub federację. Jeśli lokalne API jest w stanie niezdrowym, odwrotny serwer proxy tego nie naprawi.
Najczęściej zadawane pytania
Dlaczego Synapse jest w stanie niezdrowym?
Sprawdź logi i informacje o stanie kontenera pod kątem błędów konfiguracji, uprawnień, bazy danych lub migracji; wątek źródłowy nie zawierał potwierdzonej jednej przyczyny.
Czy mogę używać SQLite?
Tak, do testów. Aktualna dokumentacja Synapse zaleca PostgreSQL w niemal wszystkich instalacjach produkcyjnych.
Jakiego portu Synapse używa wewnętrznie?
W typowych konfiguracjach Dockera interfejs API klienta i serwera jest udostępniany za odwrotnym serwerem proxy na porcie 8008.
Czy potrzebuję Element?
Nie. Synapse to serwer domowy; Element jest jednym z możliwych klientów lub interfejsów internetowych.
