Come fare il self-hosting di Trilium Notes nel 2026: directory dei dati, WebSockets e backup

Un container Trilium Notes può risultare operativo mentre l'attività che interessa agli utenti non funziona. Nel caso di Trilium Notes, questo errore nascosto è solitamente dovuto al fatto che la directory dei dati è montata nel percorso sbagliato o non è scrivibile. Questa guida considera come test di accettazione la seguente attività: “creare note collegate, aggiungere un allegato e una relazione, cercarle e verificare la cronologia delle revisioni dopo un riavvio”, quindi costruisce il deployment a ritroso partendo da questo risultato.

Trilium Notes svolge un ruolo specifico nello stack: una knowledge base personale organizzata ad albero. La domanda in produzione non è quindi se la porta 8080 risponda una volta, ma se stato, dipendenze e indirizzo pubblico continuino a essere coerenti dopo un riavvio, un aggiornamento e un ripristino.

Mappa Trilium Notes prima di intervenire su Docker

Il processo HTTP di Trilium Notes è in ascolto sulla porta 8080; mantieni questa porta sulla rete dell'applicazione e pubblica solo la route della piattaforma. Il requisito del runtime locale è una directory dei dati durevole e memoria sufficiente per l'indicizzazione. Convalidalo usando il carico del test di accettazione: un health check a riposo non può dimostrare che la risorsa sia sufficiente.

Metti per iscritto il confine sotto forma di un breve contratto: chi è responsabile del requisito, quale credenziale viene utilizzata, quale timeout è accettabile e come si manifesta l'errore. Esegui quindi questa transazione: crea note collegate, aggiungi un allegato e una relazione, cercale e verifica la cronologia delle revisioni dopo un riavvio. Durante l'esecuzione, osserva l'indicizzazione delle note, la dimensione degli allegati, lo scripting e la crescita di document.db, perché questo carico fornisce una dimensione iniziale più utile rispetto a un container inattivo.

Testa Trilium Notes dall'esterno del server

Esponi un unico hostname HTTPS per Trilium Notes e mantieni privata la porta 8080 esposta direttamente. Pubblica la web UI tramite HTTPS mantenendo attivi i WebSockets. In questo modo impedisci a browser e client API di apprendere due indirizzi in concorrenza.

Da un client pulito, esegui la transazione verificata e analizza la prima richiesta che fallisce. Usa la guida sui domini personalizzati quando DNS o TLS non sono configurati correttamente. Considera “la directory dei dati è montata nel percorso sbagliato o non è scrivibile” come una diagnosi applicativa separata, una volta verificata la route.

Avvia Trilium Notes con impostazioni predefinite osservabili

Un avvio con caratteristiche da produzione è volutamente semplice: stato nominato, porta esplicita e nessun secret nell'immagine.

docker run -d \
  --name trilium-notes \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v trilium-notes-data:/home/node/trilium-data \
  -e TRILIUM_DATA_DIR=/home/node/trilium-data \
  triliumnext/notes:latest

L'esempio è una baseline, non uno stack di supporto completo. Verifica il requisito locale prima dell'esposizione: una directory dei dati durevole e memoria sufficiente per l'indicizzazione. Controlla i mount effettivi e il listener, quindi prova a creare note collegate, aggiungere un allegato e una relazione, cercarle e verificare la cronologia delle revisioni dopo un riavvio. Fissa l'immagine funzionante prima del riavvio successivo.

Monitora il carico di lavoro, non solo il container

Osserva il lavoro eseguito da Trilium Notes: indicizzazione delle note, dimensione degli allegati, scripting e crescita di document.db. Imposta i limiti lasciando margine per questo lavoro ed evita un liveness probe che entri in competizione con esso. Il controllo dell'operatore dovrebbe comunque provare, secondo una pianificazione, a creare note collegate, aggiungere un allegato e una relazione, cercarle e verificare la cronologia delle revisioni dopo un riavvio.

Per gli aggiornamenti, ricorda che le migrazioni di TriliumNext, gli script e le estensioni dei temi devono essere testati su una directory dei dati duplicata. Esegui il candidato su una copia ripristinata e ripeti il test noto. Se la directory dei dati è montata nel percorso sbagliato o non è scrivibile, usa i log del runtime e la richiesta di rete effettiva per individuare quale ipotesi è cambiata.

Cosa deve funzionare prima di usare dati Trilium Notes reali

Il record di release per Trilium Notes deve contenere dati concreti, non un semplice “sembra tutto a posto”. Salva il digest dell'immagine selezionata, il checksum della configurazione, l'hostname pubblico e un risultato con timestamp per: creare note collegate, aggiungere un allegato e una relazione, cercarle e verificare la cronologia delle revisioni dopo un riavvio. Usa dati di esempio non di produzione, in modo che il controllo possa essere eseguito dopo ogni deployment.

Dimostra separatamente due eventi del ciclo di vita. La sostituzione di un container deve preservare il normale funzionamento; un ripristino pulito deve dimostrare che note, relazioni, allegati, attributi e revisioni vengono recuperati e che la ricerca nota trova la stessa nota. Mentre esegui i controlli, misura l'indicizzazione delle note, la dimensione degli allegati, lo scripting e la crescita di document.db, quindi conserva il risultato come envelope atteso per questa versione.

Testa anche una condizione negata o non valida: invia un input innocuo vicino al limite di risorse o di formato associato a questo confine: la directory dei dati è montata nel percorso sbagliato o non è scrivibile. Trilium Notes dovrebbe fallire in modo diagnosticabile senza sovrascrivere lo stato integro. Ripristina la condizione valida, riesegui l'esempio e allega i log pertinenti dopo averli anonimizzati. Questi artefatti forniscono prove concrete per una futura decisione di rollback.

Esegui il backup dello stato che Trilium Notes non può ricreare

Definisci il recovery point e il recovery time di Trilium Notes in termini di document.db, allegati, revisioni e configurazione. Monta /home/node/trilium-data prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per dimostrare che il percorso è realmente persistente. Un volume nominato risolve la persistenza durante il redeploy, ma non protegge da una compromissione o dalla perdita del server.

Prepara un ambiente di ripristino pulito, usa la stessa versione applicativa fissata e dimostra che note, relazioni, allegati, attributi e revisioni vengono recuperati e che la ricerca nota trova la stessa nota. Registra i comandi, le correzioni dei proprietari e il tempo trascorso. La guida ai backup è un riferimento utile: un backup è affidabile dopo il ripristino, non dopo l'upload.

Scegli il confine di attendibilità di Trilium Notes

Chiudi la finestra di bootstrap non appena esiste il primo amministratore attendibile. La trappola concreta di Trilium Notes consiste nell'esporre una knowledge base personale senza un login adeguatamente sicuro; il confine più prudente è trattare il notebook come dati privati, richiedere un login robusto e non esporre una porzione del filesystem più ampia della sua directory dei dati.

TRILIUM_DATA_DIR controlla il comportamento, non la riservatezza; convalidane tipo e valore e conserva separatamente le credenziali reali di Trilium Notes. La rete privata dovrebbe trasportare le credenziali delle dipendenze e i ruoli all'interno di Trilium Notes dovrebbero concedere solo l'azione minima necessaria. Evita di inserire nei log di routine i body sensibili delle richieste e le risposte dei provider.

Cosa dovrebbe automatizzare Dockup per Trilium Notes

Per Trilium Notes, Dockup può creare la route e il certificato TLS, preservare i mount, distribuire i secret e predisporre una directory dei dati durevole e memoria sufficiente per l'indicizzazione su una rete privata, eseguendo il deployment su Dockup o su server collegati.

Il release gate resta comunque la transazione concreta di Trilium Notes: creare note collegate, aggiungere un allegato e una relazione, cercarle e verificare la cronologia delle revisioni dopo un riavvio. Verifica anche la condizione di ripristino: note, relazioni, allegati, attributi e revisioni vengono recuperati e la ricerca nota trova la stessa nota. Questi due controlli dimostrano se il deployment funziona e se può essere ripristinato.

Domande frequenti

Di cosa ha bisogno Trilium Notes per un deployment in produzione?

Instrada il container Trilium Notes sulla porta 8080 attraverso un'unica origine HTTPS. Il requisito del runtime locale è una directory dei dati durevole e memoria sufficiente per l'indicizzazione. Non considerare Trilium Notes pronto finché non puoi creare note collegate, aggiungere un allegato e una relazione, cercarle e verificare la cronologia delle revisioni dopo un riavvio.

Quali dati di Trilium Notes devono essere inclusi in un backup?

Rendi persistente /home/node/trilium-data e includi document.db, allegati, revisioni e configurazione nello stesso manifest di ripristino. Un ripristino pulito di Trilium Notes è riuscito solo quando note, relazioni, allegati, attributi e revisioni vengono recuperati e la ricerca nota trova la stessa nota.

Trilium Notes richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origine pubblica di Trilium Notes e mantieni la porta 8080 sulla route interna. Applica correttamente l'impostazione di Trilium Notes: pubblica la web UI tramite HTTPS mantenendo attivi i WebSockets. Per Trilium Notes, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento del client sensibile all'origine.

Come deve essere testato un aggiornamento di Trilium Notes?

Ripristina lo stato corrente di Trilium Notes in un deployment isolato, applica la versione candidata e ripeti la transazione di accettazione. Presta particolare attenzione perché le migrazioni di TriliumNext, gli script e le estensioni dei temi devono essere testati su una directory dei dati duplicata. Conserva l'immagine precedente di Trilium Notes finché non hai compreso i confini della migrazione dei dati e del rollback.