Jak samodzielnie hostować LibreTranslate w 2026 roku: modele, limity API i trwałość danych
Samodzielnie hostuj LibreTranslate z poprawnie skonfigurowanymi portami, trwałym storage, HTTPS, sekretami, kopiami zapasowymi i kontrolą aktualizacji. Dowiedz się, jak naprawić problem z niepobranymi modelami.
Jeśli masz już za sobą próbę samodzielnego hostowania LibreTranslate, prawdopodobnie znasz ten frustrujący stan: interfejs się wyświetla, ale modele nie zostały pobrane albo żądana para językowa jest niedostępna. Ponowne utworzenie kontenera rzadko rozwiązuje niespójność między adresami URL, stanem i zależnościami.
W tym przewodniku korzystamy z jednego konkretnego kryterium ukończenia — wylistowania zainstalowanych języków, przetłumaczenia ustalonego zdania w obu kierunkach oraz sprawdzenia limitu klucza API i odpowiedzi błędów. Każda decyzja konfiguracyjna jest oceniana względem tego kryterium, a nie na podstawie zielonej plakietki kontenera.
Przywracanie LibreTranslate na pustym hoście
Przed utworzeniem pierwszego właściwego rekordu wylistuj stan: pobrane modele, bazę danych kluczy API i niestandardową konfigurację. Zamontuj /home/libretranslate/.local przed bootstrapem, zapisz nieszkodliwe dane testowe i zastąp kontener, aby potwierdzić, że ta ścieżka rzeczywiście jest trwała. Potwierdź montowanie, zapisując nieszkodliwe dane, zastępując LibreTranslate i odczytując je ponownie.
Snapshoty są przydatne do szybkiego wycofania zmian, ale gdy host lub volume zniknie, potrzebna jest niezależna kopia zapasowa. Przywróć dane w pustym środowisku z przypiętym obrazem i sprawdź, czy modele oraz stan kluczy API wróciły, a korpus regresji przechodzi z akceptowalnym wynikiem. Użyj trwałych wolumenów i snapshotów, aby zachować rozdział między tymi dwoma mechanizmami odtwarzania.
Porty, procesy i prywatne usługi
Nie pozwól, aby obraz LibreTranslate przypadkowo wyznaczył architekturę produkcyjną. Obraz udostępnia proces na porcie 5000, ale storage, routing i wymagania zewnętrzne nadal wymagają świadomie zaplanowanych cykli życia. Lokalne wymaganie środowiska uruchomieniowego to storage na pobierane modele oraz CPU lub GPU odpowiednie dla używanych par językowych. Zadbaj o jawne zarządzanie cyklem życia, aby przeniesienie LibreTranslate między hostami nie zmieniało po cichu jego działania.
Wdrożenie jest gotowe do dokładniejszych testów, gdy potrafi wylistować zainstalowane języki, przetłumaczyć ustalone zdanie w obu kierunkach oraz sprawdzić limit klucza API i odpowiedzi błędów. Śledź przebieg transakcji w logach i monitoruj załadowane modele językowe, czas inferencji CPU, równoległe żądania oraz miejsce na dysku zajmowane przez pobrane modele. Te obserwacje pokazują, czy bieżąca topologia izoluje właściwy komponent.
Kompleksowa weryfikacja wdrożenia LibreTranslate
Bramka produkcyjna dla LibreTranslate powinna być możliwa do wykonania przez osobę, która nie budowała wdrożenia. Przekaż jej przypiętą wersję, niewrażliwe konto testowe i następujące zadanie: wylistować zainstalowane języki, przetłumaczyć ustalone zdanie w obu kierunkach oraz sprawdzić limit klucza API i odpowiedzi błędów. Jeśli instrukcje wymagają nieudokumentowanego dostępu przez shell, usługa nie jest jeszcze gotowa operacyjnie.
Powtórz test po zastąpieniu wyłącznie kontenera. Następnie przywróć pobrane modele, bazę danych kluczy API i niestandardową konfigurację do pustej infrastruktury oraz potwierdź, że modele i stan kluczy API wróciły, a korpus regresji przechodzi z akceptowalnym wynikiem. Podczas obu udanych uruchomień zmierz załadowane modele językowe, czas inferencji CPU, równoległe żądania i miejsce na dysku zajmowane przez pobrane modele; nieoczekiwane różnice często wskazują na brakujący cache, indeks, worker lub mount danych.
Dodaj test awarii: wyślij nieszkodliwe dane w pobliżu limitu zasobów lub formatu związanego z tym przypadkiem brzegowym: modele nie zostały pobrane albo żądana para językowa jest niedostępna. LibreTranslate powinien zwrócić użyteczny błąd, zachować istniejący stan i odzyskać sprawność po przywróceniu prawidłowych warunków. Zapisz znaczniki czasu i odpowiednie fragmenty logów, usuwając sekrety. Te dane staną się punktem odniesienia dla kolejnej zmiany obrazu lub konfiguracji.
Ustawienia kontenera, które warto sprawdzić
Użyj polecenia, które ujawnia wszystkie istotne decyzje. Ta konfiguracja bazowa wiąże LibreTranslate z loopbackiem hosta, dodaje znane mounty danych i przekazuje pierwsze wymagane ustawienie. Przed wystawieniem usługi potwierdź lokalne wymaganie: storage na pobierane modele oraz CPU lub GPU odpowiednie dla używanych par językowych.
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
Zastąp pływające tagi przetestowaną wersją lub digestem. Po uruchomieniu sprawdź docker logs --tail 200 libretranslate i potwierdź, że proces nasłuchuje na porcie 5000. Następnie wykonaj test akceptacyjny LibreTranslate; odpowiedź strony głównej nie potwierdza powodzenia całego scenariusza: wylistuj zainstalowane języki, przetłumacz ustalone zdanie w obu kierunkach oraz sprawdź limit klucza API i odpowiedzi błędów.
Dane uwierzytelniające, role i wystawione powierzchnie
Ryzyko bezpieczeństwa specyficzne dla aplikacji polega na uruchomieniu nielimitowanego publicznego API, które inni mogą wyczerpać. Właściwym rozwiązaniem jest włączenie kluczy API lub uwierzytelniania upstream, ograniczenie częstotliwości żądań publicznych użytkowników oraz instalowanie wyłącznie wymaganych par językowych. Przeprowadź bootstrap przez ograniczoną trasę i natychmiast po jego zakończeniu usuń tymczasowy dostęp konfiguracyjny.
LT_API_KEYS steruje działaniem, a nie poufnością; zweryfikuj jego typ i wartość, a właściwe dane uwierzytelniające LibreTranslate przechowuj osobno. Nadaj procesowi LibreTranslate wyłącznie udokumentowane mounty i trasy zależności; unikaj dostępu do roota hosta i socketu Dockera. Rejestruj nieudane uwierzytelnienia i błędy konfiguracji, ale usuwaj z logów tokeny, connection stringi i treści użytkowników.
Prawidłowe rozróżnianie adresów wewnętrznych i zewnętrznych
Wydanie certyfikatu TLS to tylko połowa konfiguracji trasy LibreTranslate. Udostępnij API przez HTTPS i udokumentuj prawidłową ścieżkę bazową. Wewnętrznie kieruj ruch na port 5000 i przekazuj zewnętrzny scheme, aby generowane adresy URL i bezpieczne cookies pozostały spójne.
Pełny scenariusz LibreTranslate uruchamiaj z czystej sieci, a nie tylko ze strony głównej. Błąd 502 lub problem z certyfikatem można odizolować za pomocą automatycznej konfiguracji domeny i TLS. Jeśli ruch dociera do procesu, a modele nie zostały pobrane albo żądana para językowa jest niedostępna, diagnozuj ten warunek w miejscu jego wystąpienia, zamiast dokładać kolejne przekierowania.
Testy awarii dla LibreTranslate
Testy wydajności powinny obejmować załadowane modele językowe, czas inferencji CPU, równoległe żądania i miejsce na dysku zajmowane przez pobrane modele, a nie wielokrotne żądania do /. Uruchom scenariusz „wylistuj zainstalowane języki, przetłumacz ustalone zdanie w obu kierunkach oraz sprawdź limit klucza API i odpowiedzi błędów” przy realistycznej współbieżności, a następnie zapisz opóźnienie, odsetek błędów i przyrost zajętego miejsca.
Planowanie aktualizacji musi uwzględniać to ryzyko: pakiety modeli i wydania serwera mogą zmienić wynik tłumaczenia, dlatego należy utrzymywać niewielki korpus regresji. Przetestuj nowe wydanie na reprezentatywnych danych, a następnie powtórz transakcję akceptacyjną i porównaj wynik. Jeśli modele nie zostały pobrane albo żądana para językowa jest niedostępna, zarejestruj nieudaną transakcję i sprawdź pierwszą napotkaną granicę, zamiast zakładać, że odpowiada za to ingress.
Wdrażanie LibreTranslate na Dockup bez utraty kontroli nad granicami
Szablon Dockup powinien definiować obraz, port 5000, mounty, harmonogram kontroli zdrowia, domenę, TLS i dostarczanie sekretów. Dockup powinien zachować ustawienia środowiska uruchomieniowego LibreTranslate, podczas gdy operator potwierdza lokalne wymaganie: storage na pobierane modele oraz CPU lub GPU odpowiednie dla używanych par językowych. To samo wdrożenie może być kierowane na serwery Dockup lub zasoby podłączone przez klienta.
Po uruchomieniu trasy zastosuj ustawienie publiczne i spróbuj wylistować zainstalowane języki, przetłumaczyć ustalone zdanie w obu kierunkach oraz sprawdzić limit klucza API i odpowiedzi błędów. Wykonuj kopie zapasowe pobranych modeli, bazy danych kluczy API i niestandardowej konfiguracji, a ćwiczenie odtwarzania uwzględnij w planie operacyjnym; są to obowiązki LibreTranslate, które pozostają widoczne po zakończeniu provisioningu infrastruktury.
Najczęściej zadawane pytania
Czego LibreTranslate potrzebuje w środowisku produkcyjnym?
Kieruj kontener LibreTranslate przez port 5000 do jednego originu HTTPS. Lokalne wymaganie środowiska uruchomieniowego to storage na pobierane modele oraz CPU lub GPU odpowiednie dla używanych par językowych. Nie uznawaj LibreTranslate za gotowe, dopóki nie możesz wylistować zainstalowanych języków, przetłumaczyć ustalonego zdania w obu kierunkach oraz sprawdzić limitu klucza API i odpowiedzi błędów.
Jakie dane LibreTranslate należy uwzględnić w kopii zapasowej?
Utrwal /home/libretranslate/.local i uwzględnij pobrane modele, bazę danych kluczy API oraz niestandardową konfigurację w tym samym manifeście odtwarzania. Czyste odtworzenie LibreTranslate kończy się powodzeniem tylko wtedy, gdy modele i stan kluczy API wrócą, a korpus regresji przejdzie z akceptowalnym wynikiem.
Czy LibreTranslate wymaga HTTPS za reverse proxy?
Używaj HTTPS dla publicznego originu LibreTranslate i pozostaw port 5000 na trasie wewnętrznej. Zastosuj prawidłowo ustawienie LibreTranslate: udostępniaj API przez HTTPS i udokumentuj właściwą ścieżkę bazową. W przypadku LibreTranslate HTTPS chroni dane uwierzytelniające lub treści użytkowników podczas przesyłania i zapewnia spójność zachowania klienta zależnego od originu.
Jak testować aktualizację LibreTranslate?
Przywróć bieżący stan LibreTranslate w odizolowanym wdrożeniu, zastosuj wersję kandydującą i powtórz transakcję akceptacyjną. Zwróć szczególną uwagę na to, że pakiety modeli i wydania serwera mogą zmieniać wynik tłumaczenia, dlatego należy utrzymywać niewielki korpus regresji. Zachowaj poprzedni obraz LibreTranslate do czasu zrozumienia granic migracji danych i wycofania zmian.