Як самостійно розгорнути LibreTranslate у 2026 році: моделі, обмеження API та постійні дані

Якщо ви вже намагалися самостійно розгорнути LibreTranslate, вам, імовірно, знайома ця неприємна ситуація: інтерфейс відкривається, але моделі не завантажилися або потрібна мовна пара недоступна. Повторне створення контейнера рідко усуває розбіжність між URL-адресами, станом і залежностями.

У цьому посібнику використовується один конкретний критерій готовності — отримати список встановлених мов, перекласти фіксоване речення в обох напрямках і перевірити квоту API-ключа та відповіді на помилки. Кожне рішення щодо конфігурації оцінюється за цим критерієм, а не за зеленим статусом контейнера.

Відновлення LibreTranslate на порожньому хості

До створення першого реального запису перевірте стан: завантажені моделі, базу даних API-ключів і власну конфігурацію. Підключіть /home/libretranslate/.local до bootstrap, запишіть безпечні тестові дані та замініть контейнер, щоб довести фактичну постійність цього шляху. Перевірте mount, записавши безпечні дані, замінивши LibreTranslate і прочитавши їх назад.

Snapshots корисні для швидкого відкату, але якщо хост або volume зникне, знадобиться незалежна резервна копія. Відновіть дані в порожньому середовищі з pinned image і перевірте, що моделі та стан API-ключів повернулися, а regression corpus завершується з прийнятною якістю результату. Використовуйте постійні volumes і snapshots, щоб розділяти ці два механізми відновлення.

Порти, процеси та приватні сервіси

Не дозволяйте образу LibreTranslate випадково визначати production-архітектуру. Образ надає процес на порту 5000, але для сховища, маршрутизації та зовнішніх вимог усе одно потрібні продумані lifecycle. Локальна вимога середовища виконання — сховище для завантаження моделей і CPU або GPU, що відповідає мовним парам. Явно керуйте його lifecycle, щоб перенесення LibreTranslate між хостами непомітно не змінило поведінку.

Розгортання готове до глибшого тестування, коли воно може отримати список встановлених мов, перекласти фіксоване речення в обох напрямках і перевірити квоту API-ключа та відповіді на помилки. Відстежуйте транзакцію в логах і спостерігайте за завантаженими мовними моделями, часом inference на CPU, паралельними запитами та дисковим простором, зайнятим завантаженими моделями. Ці спостереження показують, чи ізолює поточна топологія потрібний компонент.

Перевірка розгортання LibreTranslate від початку до кінця

Production-gate для LibreTranslate має виконувати людина, яка не створювала це розгортання. Передайте їй pinned version, тестовий обліковий запис без конфіденційних даних і таке завдання: отримати список встановлених мов, перекласти фіксоване речення в обох напрямках і перевірити квоту API-ключа та відповіді на помилки. Якщо інструкції вимагають недокументованого shell-доступу, сервіс ще не готовий до експлуатації.

Повторіть gate, замінивши лише контейнер. Потім відновіть завантажені моделі, базу даних API-ключів і власну конфігурацію в порожній інфраструктурі та доведіть, що моделі й стан API-ключів повернулися, а regression corpus завершується з прийнятною якістю результату. Під час обох успішних запусків виміряйте завантажені мовні моделі, час inference на CPU, паралельні запити та дисковий простір, зайнятий завантаженнями моделей; неочікувані відмінності часто вказують на відсутній cache, index, worker або data mount.

Додайте drill для помилок: надішліть безпечні тестові дані поблизу обмеження ресурсу або формату, пов’язаного з цією межею: моделі не завантажилися або потрібна мовна пара недоступна. LibreTranslate має повертати корисну помилку, зберігати наявний стан і відновлювати роботу, коли коректна умова повертається. Збережіть часові мітки та відповідні рядки логів, видаливши секрети. Ці докази стануть еталоном для наступної зміни образу або конфігурації.

Параметри контейнера, які варто перевірити

Використовуйте команду, яка явно задає всі важливі параметри. Цей базовий варіант прив’язує LibreTranslate до loopback хоста, додає відомі data mounts і передає перше необхідне налаштування. Перед відкриттям доступу перевірте локальну вимогу: сховище для завантаження моделей і CPU або GPU, що відповідає мовним парам.

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

Замініть floating tags на протестовану версію або digest. Після запуску перегляньте docker logs --tail 200 libretranslate і переконайтеся, що процес слухає порт 5000. Потім виконайте acceptance action для LibreTranslate; відповідь root page не доводить успішність усього сценарію: отримайте список встановлених мов, перекладіть фіксоване речення в обох напрямках і перевірте квоту API-ключа та відповіді на помилки.

Облікові дані, ролі та відкриті поверхні

Основний ризик безпеки для цього застосунку — необмежений публічний API, ресурс якого можуть вичерпати сторонні користувачі. Операційне рішення — увімкнути API-ключі або upstream authentication, обмежити rate limit для публічних клієнтів і встановити лише потрібні мовні пари. Завершіть bootstrap через обмежений маршрут і одразу після цього видаліть тимчасовий доступ для налаштування.

LT_API_KEYS керує поведінкою, а не конфіденційністю; перевірте його тип і значення, а справжні облікові дані LibreTranslate зберігайте окремо. Надайте процесу LibreTranslate лише задокументовані mounts і маршрути до залежностей; не надавайте доступу до root хоста та Docker socket. Записуйте невдалі спроби автентифікації та помилки конфігурації, але видаляйте з логів токени, connection strings і вміст користувачів.

Розрізняйте внутрішні та зовнішні URL

Видача TLS-сертифіката — лише половина маршруту LibreTranslate. Обслуговуйте API через HTTPS і задокументуйте правильний base path. Надсилайте трафік усередині на порт 5000 і передавайте зовнішню схему, щоб згенеровані URL та secure cookies залишалися узгодженими.

Перевіряйте повний сценарій LibreTranslate із чистої мережі, а не лише root page. Помилку 502 або проблему із сертифікатом можна ізолювати за допомогою автоматичного налаштування домену й TLS. Якщо трафік доходить до процесу, а моделі не завантажилися або потрібна мовна пара недоступна, діагностуйте цю умову в місці її виникнення, а не додавайте нові redirects.

Drills для помилок у LibreTranslate

Capacity-тести мають перевіряти завантажені мовні моделі, час inference на CPU, паралельні запити та дисковий простір, зайнятий завантаженнями моделей, а не повторний запит до /. Запустіть сценарій «отримати список встановлених мов, перекласти фіксоване речення в обох напрямках і перевірити квоту API-ключа та відповіді на помилки» з реалістичною concurrency і зафіксуйте latency, error rate та зростання обсягу сховища.

Планування оновлення має враховувати такий ризик: пакети моделей і server releases можуть змінити результат перекладу, тому підтримуйте невеликий regression corpus. Протестуйте новий release на репрезентативних вхідних даних, потім повторіть acceptance transaction і порівняйте результат. Якщо моделі не завантажилися або потрібна мовна пара недоступна, зафіксуйте невдалу транзакцію та перевірте першу залучену boundary, а не припускайте, що відповідальний ingress.

Розгортання LibreTranslate на Dockup без втрати його меж

Шаблон Dockup має містити image, порт 5000, mounts, health timing, domain, TLS і доставку секретів. Dockup має зберігати runtime settings LibreTranslate, а оператор — підтвердити цю локальну вимогу: сховище для завантаження моделей і CPU або GPU, що відповідає мовним парам. Те саме розгортання може працювати на серверах Dockup або на ресурсах, підключених клієнтом.

Після активації маршруту застосуйте публічне налаштування та спробуйте отримати список встановлених мов, перекласти фіксоване речення в обох напрямках і перевірити квоту API-ключа та відповіді на помилки. Створюйте резервні копії завантажених моделей, бази даних API-ключів і власної конфігурації та включіть вправу з відновлення до операційного плану; це відповідальність LibreTranslate, яка залишається видимою після provisioning інфраструктури.

Поширені запитання

Що потрібно LibreTranslate для production-розгортання?

Маршрутизуйте контейнер LibreTranslate на порту 5000 через один HTTPS origin. Локальна вимога середовища виконання — сховище для завантаження моделей і CPU або GPU, що відповідає мовним парам. Не вважайте LibreTranslate готовим, доки не зможете отримати список встановлених мов, перекласти фіксоване речення в обох напрямках і перевірити квоту API-ключа та відповіді на помилки.

Які дані LibreTranslate потрібно включити до резервної копії?

Зберігайте /home/libretranslate/.local і додайте завантажені моделі, базу даних API-ключів та власну конфігурацію до того самого recovery manifest. Чисте відновлення LibreTranslate успішне лише тоді, коли моделі й стан API-ключів повернулися, а regression corpus завершується з прийнятною якістю результату.

Чи потрібен LibreTranslate HTTPS за reverse proxy?

Використовуйте HTTPS для публічного LibreTranslate origin, а порт 5000 залишайте у внутрішньому маршруті. Правильно застосуйте налаштування LibreTranslate: обслуговуйте API через HTTPS і задокументуйте правильний base path. Для LibreTranslate HTTPS захищає облікові дані або вміст користувачів під час передавання та забезпечує узгоджену поведінку клієнта, чутливу до origin.

Як тестувати оновлення LibreTranslate?

Відновіть поточний стан LibreTranslate в ізольованому розгортанні, застосуйте candidate version і повторіть acceptance transaction. Приділіть цьому особливу увагу, оскільки пакети моделей і server releases можуть змінити результат перекладу, тому підтримуйте невеликий regression corpus. Зберігайте попередній image LibreTranslate, доки не зрозумієте межі міграції даних і rollback.