Come fare self-hosting di LibreTranslate nel 2026: modelli, limiti API e dati persistenti

Se hai già provato a eseguire LibreTranslate in self-hosting, probabilmente conosci bene questa situazione frustrante: l'interfaccia viene visualizzata, ma i modelli non sono stati scaricati oppure una determinata coppia di lingue non è disponibile. Ricreare il container risolve raramente un'incoerenza tra URL, stato e dipendenze.

Questa guida utilizza un unico criterio concreto per considerare l'operazione completata: elencare le lingue installate, tradurre una frase fissa in entrambe le direzioni e verificare la quota delle API key e le relative risposte di errore. Ogni scelta di configurazione viene valutata rispetto a questo criterio, non in base a un semplice badge che indica che il container è attivo.

Ripristinare LibreTranslate su un host vuoto

Elenca lo stato prima della creazione del primo record reale: modelli scaricati, database delle API key e configurazione personalizzata. Monta /home/libretranslate/.local prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per dimostrare che il percorso è realmente persistente. Verifica il mount scrivendo dati innocui, sostituendo LibreTranslate e rileggendoli.

Gli snapshot sono utili per un rapido rollback, ma quando l'host o il volume scompaiono è necessario un backup indipendente. Esegui il ripristino in un ambiente vuoto con l'immagine fissata a una versione specifica e verifica che i modelli e lo stato delle API key vengano ripristinati e che il corpus di regressione venga elaborato con un risultato accettabile. Usa volumi persistenti e snapshot per mantenere distinti questi due meccanismi di ripristino.

Porte, processi e servizi privati

Non lasciare che l'immagine di LibreTranslate determini accidentalmente l'architettura di produzione. L'immagine fornisce un processo sulla porta 5000; storage, routing e requisiti esterni richiedono comunque cicli di vita definiti intenzionalmente. Il requisito del runtime locale è uno storage per il download dei modelli e una CPU o GPU adeguata alle coppie di lingue. Mantieni esplicito il suo ciclo di vita, così spostare LibreTranslate tra host diversi non ne modificherà il comportamento senza preavviso.

Il deployment è pronto per test più approfonditi quando è in grado di elencare le lingue installate, tradurre una frase fissa in entrambe le direzioni e verificare la quota delle API key e le relative risposte di errore. Segui la transazione nei log e monitora i modelli linguistici caricati, il tempo di inferenza della CPU, le richieste parallele e lo spazio su disco consumato dai download dei modelli. Queste osservazioni mostrano se la topologia attuale isola il componente corretto.

Verificare il deployment di LibreTranslate end to end

Un gate di produzione per LibreTranslate dovrebbe poter essere eseguito da una persona che non ha realizzato il deployment. Fornisci a questa persona la versione fissata, un account di test non sensibile e questa attività: elencare le lingue installate, tradurre una frase fissa in entrambe le direzioni e verificare la quota delle API key e le relative risposte di errore. Se le istruzioni richiedono un accesso shell non documentato, il servizio non è ancora pronto dal punto di vista operativo.

Ripeti il gate dopo aver sostituito solo il container. Poi ripristina i modelli scaricati, il database delle API key e la configurazione personalizzata in un'infrastruttura vuota e dimostra che i modelli e lo stato delle API key vengono ripristinati e che il corpus di regressione viene elaborato con un risultato accettabile. Misura i modelli linguistici caricati, il tempo di inferenza della CPU, le richieste parallele e lo spazio su disco consumato dai download dei modelli durante entrambe le esecuzioni corrette; differenze impreviste rivelano spesso una cache, un indice, un worker o un mount dei dati mancante.

Aggiungi un test di gestione degli errori: invia un input innocuo vicino al limite di risorse o di formato associato a questa condizione: i modelli non sono stati scaricati oppure una determinata coppia di lingue non è disponibile. LibreTranslate dovrebbe restituire un errore utile, preservare lo stato esistente e ripristinare il funzionamento quando la condizione valida torna a essere soddisfatta. Salva i timestamp e le righe di log pertinenti, oscurando i segreti. Questa documentazione diventa il riferimento per la prossima modifica dell'immagine o della configurazione.

Impostazioni del container da verificare

Usa un comando che renda visibile ogni scelta importante. Questa configurazione di base associa LibreTranslate al loopback dell'host, aggiunge i mount dei dati noti e fornisce la prima impostazione necessaria. Conferma il requisito locale prima di esporre il servizio: uno storage per il download dei modelli e una CPU o GPU adeguata alle coppie di lingue.

docker run -d \
  --name libretranslate \
  --restart unless-stopped \
  -p 127.0.0.1:5000:5000 \
  -v libretranslate-data:/home/libretranslate/.local \
  -e LT_API_KEYS=true \
  libretranslate/libretranslate:latest

Sostituisci i tag mobili con una versione testata o con un digest. Dopo l'avvio, esegui docker logs --tail 200 libretranslate e conferma che il processo sia in ascolto sulla porta 5000. Poi esegui il test di accettazione di LibreTranslate; una risposta della pagina principale non dimostra che l'intero scenario abbia esito positivo: elencare le lingue installate, tradurre una frase fissa in entrambe le direzioni e verificare la quota delle API key e le relative risposte di errore.

Credenziali, ruoli e superfici esposte

Il rischio per la sicurezza specifico dell'applicazione consiste nell'eseguire un'API pubblica senza limiti che altri possono consumare fino a esaurirne le risorse. La soluzione operativa consiste nell'abilitare le API key o l'autenticazione upstream, applicare il rate limiting agli utenti pubblici e installare solo le coppie di lingue necessarie. Completa il bootstrap tramite una route con accesso limitato e rimuovi immediatamente l'accesso temporaneo al termine.

LT_API_KEYS controlla il comportamento, non la riservatezza; convalida il tipo e il valore e conserva separatamente le credenziali effettive di LibreTranslate. Concedi al processo di LibreTranslate solo i mount e le route verso le dipendenze documentati; evita l'accesso alla root dell'host e al socket Docker. Registra gli errori di autenticazione e di configurazione, ma oscura token, stringhe di connessione e contenuti degli utenti.

Mantenere distinti gli URL interni ed esterni

L'emissione del certificato TLS è solo metà del percorso di LibreTranslate. Servi l'API tramite HTTPS e documenta il base path corretto. Inoltra internamente il traffico verso la porta 5000 e trasmetti lo schema esterno, così gli URL generati e i cookie sicuri rimangono coerenti.

Usa lo scenario completo di LibreTranslate da una rete pulita, non soltanto la pagina principale. Un errore 502 o un errore del certificato può essere isolato con la configurazione automatica del dominio e di TLS. Se il traffico raggiunge il processo ma i modelli non sono stati scaricati oppure una determinata coppia di lingue non è disponibile, diagnostica la condizione nel punto in cui si verifica invece di concatenare redirect.

Test di gestione degli errori per LibreTranslate

I test di capacità devono esercitare i modelli linguistici caricati, il tempo di inferenza della CPU, le richieste parallele e lo spazio su disco consumato dai download dei modelli, non una richiesta ripetuta a /. Esegui lo scenario “elencare le lingue installate, tradurre una frase fissa in entrambe le direzioni e verificare la quota delle API key e le relative risposte di errore” con una concorrenza realistica e registra latenza, percentuale di errori e crescita dello storage.

La pianificazione degli aggiornamenti deve tenere conto di questo rischio: i pacchetti dei modelli e le release del server possono modificare l'output delle traduzioni, quindi mantieni un piccolo corpus di regressione. Testa la nuova release con input rappresentativi, poi ripeti la transazione di accettazione e confronta il risultato. Se i modelli non sono stati scaricati oppure una determinata coppia di lingue non è disponibile, acquisisci la transazione che fallisce e verifica il primo confine coinvolto invece di presumere che la responsabilità sia dell'ingress.

Eseguire il deployment di LibreTranslate su Dockup senza perdere i suoi confini

Un template Dockup dovrebbe codificare l'immagine, la porta 5000, i mount, le tempistiche dell'health check, il dominio, TLS e la distribuzione dei segreti. Dockup dovrebbe preservare le impostazioni del runtime di LibreTranslate mentre l'operatore conferma questo requisito locale: uno storage per il download dei modelli e una CPU o GPU adeguata alle coppie di lingue. Lo stesso deployment può essere destinato ai server Dockup o a capacità fornita dal cliente.

Dopo che la route è attiva, applica l'impostazione pubblica e prova a elencare le lingue installate, tradurre una frase fissa in entrambe le direzioni e verificare la quota delle API key e le relative risposte di errore. Esegui il backup dei modelli scaricati, del database delle API key e della configurazione personalizzata e mantieni il test di ripristino nel piano operativo; sono responsabilità di LibreTranslate che rimangono visibili anche dopo il provisioning dell'infrastruttura.

Domande frequenti

Di cosa ha bisogno LibreTranslate per un deployment di produzione?

Instrada il container di LibreTranslate sulla porta 5000 attraverso un'unica origine HTTPS. Il requisito del runtime locale è uno storage per il download dei modelli e una CPU o GPU adeguata alle coppie di lingue. Non considerare LibreTranslate pronto finché non puoi elencare le lingue installate, tradurre una frase fissa in entrambe le direzioni e verificare la quota delle API key e le relative risposte di errore.

Quali dati di LibreTranslate devono essere inclusi in un backup?

Rendi persistente /home/libretranslate/.local e includi nello stesso manifest di ripristino i modelli scaricati, il database delle API key e la configurazione personalizzata. Un ripristino pulito di LibreTranslate è riuscito solo quando i modelli e lo stato delle API key vengono ripristinati e il corpus di regressione viene elaborato con un risultato accettabile.

LibreTranslate richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origine pubblica di LibreTranslate e mantieni la porta 5000 nella route interna. Applica correttamente l'impostazione di LibreTranslate: servi l'API tramite HTTPS e documenta il base path corretto. Per LibreTranslate, 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 LibreTranslate?

Ripristina lo stato attuale di LibreTranslate in un deployment isolato, applica la versione candidata e ripeti la relativa transazione di accettazione. Presta particolare attenzione perché i pacchetti dei modelli e le release del server possono modificare l'output delle traduzioni, quindi mantieni un piccolo corpus di regressione. Conserva l'immagine precedente di LibreTranslate finché non saranno chiari i confini della migrazione dei dati e del rollback.