Se Matrix Synapse esaurisce la memoria durante la sincronizzazione dei client, verificare innanzitutto se Linux ha effettivamente terminato un processo Synapse, quindi misurare l'utilizzo della memoria durante un normale /_matrix/client/v3/synccarico di lavoro. Se la causa è la crescita della cache, apportare una modesta regolazione della cache anziché imporre immediatamente un limite estremamente basso; le risposte lente del database possono generare un accumulo di richieste che aggrava il problema.
Al 10 ottobre 2026, la cronologia ufficiale delle versioni di Synapse indica la 1.162.0 (29 settembre) come l'ultima versione stabile e la 1.163.0rc1 come versione preliminare. Aggiornare un'installazione obsoleta è una scelta prudente, ma il solo numero di versione non è sufficiente per diagnosticare o garantire una soluzione ai problemi di esaurimento della memoria legati alla sincronizzazione.
1. Dimostra che si tratta di un errore di memoria insufficiente.
I client che mostrano una sincronizzazione infinita, un errore del gateway o una sessione disconnessa non generano di per sé un evento OOM (Out Of Memory). In una tipica installazione di systemd su Linux, controllare il kernel e il registro dei servizi in prossimità dell'ora in cui si è verificato l'errore del client:
sudo journalctl -k --since "1 hour ago" | grep -Ei 'oom|out of memory|killed process'
sudo journalctl -u matrix-synapse --since "1 hour ago" --no-pager
Cerca un messaggio di OOM-killer del kernel che indichi un processo Synapse o Python, uno stato di systemd come oom-kill, o un Python MemoryError. Questi indicano diversi meccanismi di errore: il kernel può terminare un processo quando viene raggiunto un limite di memoria dell'host o del container, mentre MemoryErrorpuò verificarsi all'interno di Python prima di una terminazione OOM a livello di sistema. Il nome del servizio varia a seconda dei pacchetti; sostituiscilo con il nome effettivo dell'unità o del container.
Successivamente, registra la pressione sul sistema host e i processi più pesanti durante la riproduzione di una normale sincronizzazione:
free -h
ps -eo pid,rss,%mem,args --sort=-rss | head -n 12
systemctl show matrix-synapse -p MemoryCurrent -p MemoryMax
RSSLa memoria residente è espressa in kilobyte e non rappresenta una misura precisa della memoria specifica di un'applicazione; le pagine condivise possono essere conteggiate in più processi. Su Docker, è inoltre necessario verificare docker statsil limite di memoria configurato per il container. Se PostgreSQL, Redis e più processi worker di Synapse condividono l'host, è opportuno valutare il loro consumo di memoria complessivo anziché attribuire la colpa esclusivamente al processo principale di Synapse.
2. Ottimizzare la memoria cache in modo conservativo
Synapse mantiene intenzionalmente in memoria gli eventi recenti e i dati delle stanze per gestire rapidamente le richieste di sincronizzazione. Il caches.global_factorvalore predefinito documentato è 0.5; la riduzione di questo fattore generalmente riduce le dimensioni della cache, ma aumenta la probabilità di un maggiore carico di lavoro del database. Le FAQ per gli amministratori di Synapse avvertono che una cache eccessivamente piccola su un'archiviazione lenta può creare richieste in arretrato e un utilizzo complessivo della memoria ancora maggiore.
Esegui il backup del file attivo homeserver.yaml, verifica la presenza di un blocco esistente caches:e modifica solo i valori pertinenti. Questa è una configurazione di prova per un'istanza che mostra un utilizzo crescente della cache, non un obiettivo di ottimizzazione universale:
caches:
global_factor: 0.3
sync_response_cache_duration: 1m
L'impostazione della cache di risposta sincrona controlla per quanto tempo /synci risultati completati rimangono nella cache; Synapse documenta un 2mvalore predefinito. Un intervallo più breve può ridurre le risposte conservate, ma può anche aumentare il carico di lavoro per i client con connessioni intermittenti. Non aggiungere una seconda caches:chiave se ne esiste già una. Se l'installazione imposta SYNAPSE_CACHE_FACTORquesta variabile nel suo ambiente di servizio o container, tale variabile ha la precedenza sul fattore YAML.
Convalida il file con l'ambiente Python utilizzato dalla tua installazione di Synapse, modificando il percorso di configurazione secondo necessità:
python -m synapse.config -c /etc/matrix-synapse/homeserver.yaml
Riavviare solo dopo la convalida. Per i pacchetti systemd in stile Debian, questo avviene spesso sudo systemctl restart matrix-synapse; le distribuzioni di container utilizzano la propria orchestrazione. Controllare immediatamente dopo il log del servizio per eventuali errori di configurazione. Il riferimento di configurazione di Synapse documenta anche il ricaricamento dei fattori della cache con SIGHUP, ma ciò non implica che altre impostazioni, inclusa la conservazione della risposta di sincronizzazione, siano ricaricabili. Un riavvio controllato è più chiaro quando si modificano entrambi.
3. Verificare se si stanno accumulando sincronizzazioni lente
Se la memoria continua ad aumentare mentre i client rimangono bloccati, ridurre ulteriormente la cache potrebbe essere controproducente. Confronta la tempistica dell'aumento dell'RSS con la pressione della CPU, l'I/O del disco e l'attività del database. Un host sovraccarico o query PostgreSQL lente possono causare un maggior numero di richieste simultanee in corso, ognuna delle quali potrebbe conservare i dati fino al completamento.
Innanzitutto, verifica che il database sia responsivo e che lo spazio su disco e le operazioni di I/O siano integri. Synapse in ambiente di produzione è progettato per PostgreSQL anziché per SQLite, come documentato nella documentazione di riferimento sulla configurazione di Synapse . Se si tratta di un'istanza precedente basata su SQLite, pianifica una migrazione del database supportata con un backup testato; non tentare uno scambio del database in tempo reale come soluzione di emergenza per problemi di memoria.
Se in precedenza hai ridotto global_factoril valore a un livello estremo e la latenza di sincronizzazione è peggiorata, ripristina il valore precedente o prova un'impostazione leggermente più alta monitorando sia i tempi di risposta che la memoria totale. Le FAQ per gli amministratori di Synapse indicano esplicitamente che una maggiore quantità di cache può essere utile quando i backend lenti causano code. Non esiste un valore fisso di RAM sicuro che si adatti a ogni numero di stanze, carico di federazione e configurazione di implementazione.
In un'implementazione multi-processo con un elevato carico di lavoro, è necessario identificare se la crescita è dovuta al processo principale o a uno specifico worker di sincronizzazione. I worker consentono di distribuire il traffico di sincronizzazione dei client, ma ciascun worker necessita anche di memoria, pertanto l'aggiunta di worker senza un aumento di capacità può aggravare la pressione dovuta all'esaurimento della memoria (OOM) dell'host. È consigliabile seguire la documentazione di Synapse relativa ai worker anziché instradare le richieste dei client a worker arbitrari senza la configurazione condivisa necessaria.
4. Valutare l'ottimizzazione automatica della cache solo se vengono soddisfatti i prerequisiti.
Su un sistema in cui è già supportata e verificata una configurazione jemalloc appropriata, Synapse fornisce cache_autotuning. Richiede tutti e tre i valori documentati max_cache_memory_usage: , target_cache_memory_usagee min_cache_ttl, e utilizza l'eliminazione della cache per mantenere l'utilizzo della cache attorno a un target. Le seguenti figure sono illustrative e devono essere dimensionate per lasciare spazio a Python, al database, ad altri servizi e a picchi di richieste attive:
caches:
cache_autotuning:
max_cache_memory_usage: 512M
target_cache_memory_usage: 384M
min_cache_ttl: 5m
Unisci questo blocco con le impostazioni della cache esistenti invece di sostituirle. Questi numeri rappresentano i budget della cache, non i limiti RSS del processo ; il loro utilizzo non garantisce che il processo rimanga al di sotto di 512 MiB. Il riferimento di configurazione di Synapse richiede jemalloc per questa funzionalità e le FAQ dell'amministratore di Synapse avvertono che l'allocatore di Python può interferire con la contabilizzazione di jemalloc, potenzialmente richiedendo PYTHONMALLOC=malloc. Poiché i percorsi di precaricamento dell'allocatore e il packaging variano, verifica la libreria effettiva della tua distribuzione e l'ambiente di avvio prima di modificarlo LD_PRELOAD. Non copiare ciecamente un percorso di libreria specifico dell'architettura.
5. Verificare che la sincronizzazione sia stabile
Dopo ogni singola modifica, eseguire la stessa attività client realistica che in precedenza ha causato l'errore: riconnettere un client esistente, consentire una sincronizzazione iniziale laddove possibile e attendere il completamento di diverse sincronizzazioni incrementali normali. Registrare il picco RSS di tutti i processi Synapse, l'attività di swap, la reattività del database e se il kernel registra un altro evento OOM. Un breve calo immediatamente dopo il riavvio non è indice di una soluzione duratura; le cache, per loro natura, si avviano a freddo.
Se il monitoraggio è abilitato, confronta la memoria di processo e il comportamento delle richieste nel tempo utilizzando l'endpoint delle metriche di Synapse. La documentazione sul monitoraggio di Synapse spiega che i worker espongono le metriche in modo indipendente e devono essere monitorati separatamente; mantieni gli endpoint delle metriche privati o protetti anziché pubblicare apertamente i dati interni.
La modifica ha funzionato se i client completavano la sincronizzazione senza riconnessioni ripetute, i log non mostravano nuovi errori di memoria e la memoria si stabilizzava a un livello sostenibile con lo stesso carico di lavoro. Se gli errori di memoria insufficiente persistevano nonostante una latenza di sincronizzazione accettabile e cache attentamente configurate, il passo successivo pratico consisteva nell'aumentare la RAM disponibile o ridurre il carico di lavoro per host, utilizzando il consumo di picco misurato anziché una dimensione del server consigliata arbitrariamente.