Как развернуть LibreTranslate на собственном сервере в 2026 году: модели, ограничения API и постоянные данные

Если вы уже пытались развернуть LibreTranslate самостоятельно, вам наверняка знакомо это раздражающее состояние: интерфейс открывается, но модели не были загружены или нужная языковая пара недоступна. Пересоздание контейнера редко устраняет несоответствие между URL, состоянием и зависимостями.

В этом руководстве используется один конкретный критерий готовности — получить список установленных языков, перевести фиксированное предложение в обоих направлениях и проверить квоту API-ключа и ответы с ошибками. Каждое решение по конфигурации оценивается относительно этого критерия, а не по зелёному индикатору контейнера.

Восстановление LibreTranslate на пустом хосте

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

Снимки состояния удобны для быстрого отката, но при исчезновении хоста или тома потребуется независимая резервная копия. Восстановите данные в пустой среде с зафиксированным образом и убедитесь, что модели и состояние API-ключей вернулись, а регрессионный набор тестов выполняется с приемлемым результатом. Используйте постоянные тома и снимки состояния, чтобы не смешивать эти два механизма восстановления.

Порты, процессы и внутренние сервисы

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

Развёртывание готово к более глубокому тестированию, когда оно может вывести список установленных языков, перевести фиксированное предложение в обоих направлениях и проверить квоту API-ключа и ответы с ошибками. Отслеживайте транзакцию в логах и наблюдайте за загруженными языковыми моделями, временем inference на CPU, параллельными запросами и объёмом диска, занятым загруженными моделями. Эти наблюдения показывают, изолирует ли текущая топология нужный компонент.

Сквозная проверка развёртывания LibreTranslate

Production-проверка LibreTranslate должна выполняться человеком, который не создавал это развёртывание. Передайте ему зафиксированную версию, тестовую учётную запись без конфиденциальных данных и следующую задачу: вывести список установленных языков, перевести фиксированное предложение в обоих направлениях и проверить квоту API-ключа и ответы с ошибками. Если для выполнения инструкции требуется недокументированный доступ к shell, сервис ещё не готов к эксплуатации.

Повторите проверку, заменив только контейнер. Затем восстановите загруженные модели, базу данных API-ключей и пользовательскую конфигурацию в пустой инфраструктуре и убедитесь, что модели и состояние API-ключей вернулись, а регрессионный набор тестов выполняется с приемлемым результатом. Во время обоих успешных запусков измерьте загруженные языковые модели, время inference на CPU, количество параллельных запросов и объём диска, занятый загруженными моделями; неожиданные различия часто указывают на отсутствующий cache, index, worker или mount с данными.

Добавьте проверку отказоустойчивости: отправьте безвредный запрос, близкий к ограничению ресурса или формата, связанному с этой границей: модели не были загружены или нужная языковая пара недоступна. LibreTranslate должен вернуть понятную ошибку, сохранить существующее состояние и восстановить работу, когда условие снова станет допустимым. Сохраните временные метки и относящиеся к делу строки логов, предварительно удалив секреты. Эти данные станут эталоном для следующего изменения образа или конфигурации.

Параметры контейнера, которые стоит проверить

Используйте команду, в которой явно указаны все важные параметры. Этот базовый вариант привязывает LibreTranslate к loopback-интерфейсу хоста, добавляет известные mount с данными и передаёт первую обязательную настройку. До публикации сервиса проверьте требование локальной среды: хранилище для загрузки моделей и 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

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

Учётные данные, роли и внешние поверхности

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

LT_API_KEYS управляет поведением, а не конфиденциальностью; проверьте его тип и значение, а настоящие учётные данные LibreTranslate храните отдельно. Предоставьте процессу LibreTranslate только документированные mount и маршруты к зависимостям; не давайте доступ к root хоста и Docker socket. Записывайте неудачные попытки аутентификации и ошибки конфигурации, но удаляйте из логов токены, строки подключения и пользовательское содержимое.

Не путайте внутренние и внешние URL

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

Проверяйте полный сценарий LibreTranslate из чистой сети, а не только корневую страницу. Ошибку 502 или проблему с сертификатом можно изолировать с помощью автоматической настройки домена и TLS. Если трафик достигает процесса, а модели не были загружены или нужная языковая пара недоступна, диагностируйте проблему в месте её возникновения, а не добавляйте новые редиректы.

Проверки отказоустойчивости LibreTranslate

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

При планировании обновления необходимо учитывать следующий риск: пакеты моделей и релизы сервера могут изменить результаты перевода, поэтому поддерживайте небольшой регрессионный набор тестов. Протестируйте новый релиз на репрезентативных входных данных, затем повторите приёмочную транзакцию и сравните результат. Если модели не были загружены или нужная языковая пара недоступна, сохраните неудачную транзакцию и проверьте первую задействованную границу, вместо того чтобы предполагать, что проблема связана с ingress.

Развёртывание LibreTranslate в Dockup без потери границ

Шаблон Dockup должен описывать образ, порт 5000, mount, параметры health check, домен, TLS и передачу секретов. Dockup должен сохранять настройки среды выполнения LibreTranslate, пока оператор подтверждает это требование локальной среды: хранилище для загрузки моделей и CPU или GPU, подходящие для выбранных языковых пар. Одно и то же развёртывание может использовать серверы Dockup или ресурсы, подключённые клиентом.

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

Часто задаваемые вопросы

Что требуется LibreTranslate для production-развёртывания?

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

Какие данные LibreTranslate нужно включать в резервную копию?

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

Требуется ли LibreTranslate HTTPS за reverse proxy?

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

Как тестировать обновление LibreTranslate?

Восстановите текущее состояние LibreTranslate в изолированном развёртывании, примените candidate-версию и повторите приёмочную транзакцию. Обратите особое внимание на то, что пакеты моделей и релизы сервера могут изменить результаты перевода, поэтому поддерживайте небольшой регрессионный набор тестов. Сохраняйте предыдущий образ LibreTranslate, пока не будут понятны границы миграции данных и отката.