Se Matrix Synapse su CasaOS mostra “container non integro”, inizia dai log del container e dal file homeserver.yaml generato, invece di reinstallare alla cieca. Synapse dispone di un'immagine Docker ufficiale, ma un homeserver di produzione richiede anche configurazione e dati persistenti, un nome del server corretto, PostgreSQL e una pianificazione per HTTPS e la federazione.
SQLite è accettabile per i test, ma la documentazione attuale di Synapse raccomanda PostgreSQL per quasi tutte le installazioni reali. Un container può avviarsi e rimanere comunque non integro quando la configurazione, il database, i permessi o la migrazione all'avvio presentano errori.
Usa l'immagine ufficiale di Synapse
L'attuale guida all'installazione di Synapse indica ghcr.io/element-hq/synapse come immagine container ufficiale.
Genera la configurazione iniziale
Crea una directory persistente e genera la configurazione una volta prima dell'avvio normale:
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 generateSostituisci il dominio di esempio con il nome del server Matrix che intendi mantenere.
Verifica perché il container non è integro
docker ps -a | grep synapse
docker inspect synapse --format '{{json .State.Health}}'
docker logs --tail 200 synapseCerca errori YAML, file mancanti, problemi di permessi, errori di connessione al database o migrazioni che non vengono completate.
Usa PostgreSQL in produzione
L'attuale guida PostgreSQL di Synapse illustra la configurazione del database supportata. Mantieni persistenti i dati di Postgres ed esegui il backup insieme allo stato di Synapse.
Non modificare successivamente server_name senza pianificare
Gli ID Matrix derivano dal nome del server, ad esempio @user:example.com. Scegli il dominio definitivo prima di invitare gli utenti.
HTTPS è necessario per un utilizzo pratico
Synapse normalmente ascolta internamente su HTTP (comunemente sulla porta 8008). Usa un reverse proxy con HTTPS per client e federazione, invece di esporre pubblicamente la porta grezza del container.
La federazione aggiunge altri requisiti DNS e del proxy
Se vuoi comunicare con altri server Matrix, configura correttamente il nome pubblico del server, HTTPS e il rilevamento della federazione. Un test solo locale può essere molto più semplice.
Esegui il backup di più del solo container
Conserva homeserver.yaml, le chiavi di firma, i media caricati e il database PostgreSQL. Scaricare nuovamente l'immagine non ripristina l'identità di un homeserver.
La guida alla risoluzione dei problemi Docker illustra il modello generale per il debug dei container.
Controlla la proprietà dei file nella cartella dei dati persistenti
Se il log del container segnala un errore di autorizzazione durante la lettura di homeserver.yaml, delle chiavi di firma o dei media, correggi la proprietà della directory dei dati Synapse collegata al container in base all'UID/GID previsto dall'immagine. Evita di rendere scrivibile da chiunque l'intero albero dei dati di CasaOS.
Attendi il completamento delle migrazioni del database prima di valutare lo stato
Dopo un aggiornamento o la prima connessione a PostgreSQL, Synapse potrebbe aver bisogno di tempo per eseguire le migrazioni dello schema. Controlla i log invece di riavviare ripetutamente il container, perché interrompere le migrazioni può rendere più difficile la diagnosi.
Testa l'API locale prima del reverse proxy
Verifica che l'endpoint HTTP interno di Synapse risponda dall'host CasaOS prima di aggiungere HTTPS, DNS o la federazione. Se l'API locale non è integra, un reverse proxy non può risolvere il problema.
FAQ
Perché Synapse non è integro?
Controlla i log e l'output dello stato per individuare errori di configurazione, permessi, database o migrazione; il thread di origine non forniva una causa unica verificata.
Posso usare SQLite?
Per i test, sì. La documentazione attuale di Synapse raccomanda PostgreSQL per quasi tutte le installazioni di produzione.
Quale porta usa internamente Synapse?
Le configurazioni Docker comuni espongono l'API client/server sulla porta 8008 dietro un reverse proxy.
Ho bisogno di Element?
No. Synapse è l'homeserver; Element è un possibile client o frontend web.
