Как запустить LibreOffice в безголовом режиме внутри контейнера Docker

Распространенная серверная проблема на первый взгляд кажется простой: приложение получает файл DOCX, XLSX, ODT или PPTX и должно вернуть PDF-файл, но хост не должен запускать сессию рабочего стола. Установка полного пакета офисных программ непосредственно на хост также затрудняет воспроизведение проблем. LibreOffice может работать без графического интерфейса, а Docker может изолировать среду выполнения преобразования, но надежные результаты зависят не только от добавления чего-либо --headlessк команде.

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

По состоянию на октябрь 2026 года LibreOffice указывает версию 26.8 как последнюю функциональную ветку, а 26.2.6 — как зрелую предыдущую ветку, рекомендуемую для корпоративного использования. Стабильные пакеты Debian 13 могут содержать другую, поддерживаемую дистрибутивом версию LibreOffice, поэтому закрепите базовый образ и проверьте фактическую версию в собранном контейнере, а не предполагайте, что она совпадает с версией из исходного кода. См. официальные примечания к выпуску LibreOffice и страницу пакета Debian libreoffice-nogui .

Что на самом деле означает «безголовый LibreOffice в Docker»?

LibreOffice --headlessработает в режиме, не требующем пользовательского интерфейса, и обрабатывает документы. Для преобразования файлов важны дополнительные параметры --convert-toи --outdir. LibreOffice также требует доступа на запись к каталогу профиля пользователя, что важно при запуске контейнера от имени пользователя, не являющегося root, или при установке корневой файловой системы в режим только для чтения. Наиболее авторитетный справочник по CLI находится в LibreOffice Help: Starting LibreOffice Software With Parameters .

Таким образом, цель хорошего контейнера конкретна: он должен запускаться без X11 или рабочего стола, считывать входной документ, записывать ожидаемый формат выходных данных, корректно завершать работу и создавать файл, структура которого приемлема для вашей рабочей нагрузки.

Шаг 1: Создайте небольшой, воспроизводимый образ Docker.

Для широкого охвата форматов в Debian 13 libreoffice-noguiполезной отправной точкой является этот пакет, поскольку Debian описывает его как метапакет без графического интерфейса, предназначенный в основном для написания скриптов. Если вы конвертируете только документы Writer, вы можете уменьшить зависимости, установив libreoffice-writer-noguiтолько необходимые компоненты без графического интерфейса.

FROM debian:13-slim

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y --no-install-recommends \
    libreoffice-nogui \
    fonts-dejavu-core \
    fonts-liberation2 \
    fonts-crosextra-carlito \
    fonts-crosextra-caladea \
    ca-certificates \
 && rm -rf /var/lib/apt/lists/*

RUN useradd --create-home --uid 10001 office

WORKDIR /work
USER office

ENTRYPOINT ["soffice","--headless","--nologo","--nodefault","--norestore"]

Пакеты шрифтов не являются косметическими. В документах Office часто используются шрифты, которые не установлены в минимальном образе Linux. LibreOffice заменит запрошенный шрифт другим, если он недоступен, что может изменить перенос строк, количество страниц, ширину таблиц и макет слайда. Carlito и Caladea — это часто используемые и совместимые с метрической системой шрифты заменители Calibri и Cambria, а Liberation и DejaVu охватывают множество общих случаев. Если в ваших документах используются корпоративные или лицензионные шрифты, устанавливайте или монтируйте их только в том случае, если это разрешено вашей лицензией.

Шаг 2: Создайте образ и запишите версию LibreOffice.

docker build -t libreoffice-headless:debian13 .

Затем проверьте версию, которая фактически присутствует на изображении:

docker run --rm --entrypoint soffice   libreoffice-headless:debian13 --version

Эта проверка важна, когда базовый образ перестраивается спустя несколько недель. Если важна точная передача изображения, используйте неизменяемый дайджест образа в рабочей среде и намеренно перестраивайте его после обновлений безопасности или LibreOffice. Теги «Последний» удобны во время экспериментов, но затрудняют исследование различий в выходных данных.

Шаг 3: Подготовьте отдельные каталоги для ввода и вывода.

Создайте две директории на хосте. Входная директория может быть только для чтения; выходная директория должна быть доступна для записи пользователем контейнера.

mkdir -p input output
cp sample.docx input/

Docker рекомендует использовать следующий --mountсинтаксис для монтирования каталогов. В документации также отмечается, что по умолчанию каталоги, монтированные с помощью bind mount, доступны для записи, поэтому явное указание исходного каталога в режиме только для чтения является полезной мерой предосторожности. См. документацию Docker по bind mounts .

Шаг 4: Преобразуйте один документ в PDF.

Запустите временный контейнер и смонтируйте исходный каталог в режиме только для чтения:

docker run --rm   --mount type=bind,src="$(pwd)/input",dst=/input,readonly   --mount type=bind,src="$(pwd)/output",dst=/output   libreoffice-headless:debian13   --convert-to pdf   --outdir /output   /input/sample.docx

LibreOffice официально поддерживает этот --convert-to OutputFileExtension[:OutputFilterName[:OutputFilterParams]]формат. Для простого преобразования файла Writer в PDF, --convert-to pdfLibreOffice позволяет выбрать соответствующий фильтр экспорта PDF. Если вам требуется определенное поведение PDF-файла, LibreOffice также описывает параметры фильтра; см. официальный справочник параметров командной строки PDF .

Шаг 5: Присвойте каждому одновременно выполняемому заданию собственный профиль LibreOffice.

Однократное преобразование часто проходит без дополнительной настройки профиля, что может скрывать проблему масштабирования. LibreOffice хранит состояние в профиле пользователя и требует доступа на запись к нему. Параллельные рабочие процессы не должны конкурировать за один и тот же каталог профилей.

Используйте описанную в документации -env:UserInstallation=...переменную bootstrap, чтобы присвоить заданию частный профиль:

docker run --rm   --mount type=bind,src="$(pwd)/input",dst=/input,readonly   --mount type=bind,src="$(pwd)/output",dst=/output   --tmpfs /tmp   libreoffice-headless:debian13   -env:UserInstallation=file:///tmp/lo-profile   --convert-to pdf   --outdir /output   /input/sample.docx

Приватный временный профиль особенно полезен для кратковременных контейнеров и пулов рабочих процессов. Документы Docker tmpfsмонтируются для временных файлов в оперативной памяти. Если же вы используете долгоживущий сервис UNO, применяйте продуманную стратегию постоянного профиля и сериализуйте или изолируйте доступ в соответствии с архитектурой вашего приложения.

Шаг 6: Убедитесь, что выходной файл действительно существует.

После завершения работы контейнера проверьте выходной каталог хоста:

ls -lh output/sample.pdf
file output/sample.pdf

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

Шаг 7: Бережно обращайтесь с партиями, вместо того чтобы слепо использовать один и тот же процесс.

LibreOffice может принимать несколько входных файлов --convert-to, а также легко создать цикл в командной оболочке. Например:

for f in input/*.docx; do
  docker run --rm     --mount type=bind,src="$(pwd)/input",dst=/input,readonly     --mount type=bind,src="$(pwd)/output",dst=/output     --tmpfs /tmp     libreoffice-headless:debian13     -env:UserInstallation=file:///tmp/lo-profile     --convert-to pdf     --outdir /output     "/input/$(basename "$f")"
done

Для повышения пропускной способности многократный запуск LibreOffice может стать затратным. В этом случае можно рассмотреть возможность использования постоянного процесса LibreOffice, управляемого через UNO с помощью интерфейса --accept=..., который LibreOffice описывает как интерфейс для создания акцептора. Однако это меняет операционную модель: теперь необходимы контроль процесса, изоляция запросов, тайм-ауты, проверки работоспособности и стратегия перезапуска процесса после проблемных документов. Одноразовый контейнер остается более удобным вариантом для небольших или средних объемов данных.

Шаг 8: Проверьте визуальное качество, а не только успешность выполнения команды.

Откройте созданные PDF-файлы и сравните их с ожидаемым результатом. Обратите особое внимание на разрывы страниц, замененные шрифты, встроенные изображения, уравнения, верхние и нижние колонтитулы, диаграммы, области печати электронных таблиц и текстовые поля презентаций. Безголовый режим исключает необходимость использования графического рабочего стола; он не гарантирует, что все фирменные функции Office будут отображаться идентично Microsoft Office.

Для автоматизированного регрессионного тестирования подготовьте тщательно отобранный набор репрезентативных документов и сравните измеримые свойства, такие как количество страниц, извлеченный текст, размеры изображений или сходство отображаемых страниц. Тщательно проверьте пороговые значения, поскольку даже безобидные обновления LibreOffice могут изменить метаданные PDF-файлов или мелкие детали макета.

Если преобразование не удается: сначала устраните простые причины.

1. Контейнер завершает работу, но никаких результатов не отображается.

Сначала проверьте указанный путь --outdirи убедитесь, что целевой каталог доступен для записи пользователю с UID 10001. Привязка Docker к каталогу сопоставляет права доступа к файловой системе хоста с правами доступа в контейнере. Если каталог вашего хоста принадлежит пользователю с другим UID и не имеет прав на запись для группы, процесс LibreOffice, не являющийся root-пользователем, может не суметь создать выходные данные.

2. LibreOffice сообщает о проблеме с профилем или блокировкой.

Используйте отдельный -env:UserInstallation=file:///...путь для каждого одновременно выполняемого задания. Не указывайте нескольким рабочим процессам путь к одному каталогу профиля с возможностью записи. В документации LibreOffice описаны как требования к профилю, так и способы их UserInstallationпереопределения.

3. PDF-файл создан, но макет отображается неправильно.

Проверьте шрифты перед изменением параметров экспорта. Используйте встроенные средства проверки шрифтов fc-listвнутри изображения, чтобы убедиться, что необходимые шрифты отображаются. Если исходный файл использует макросы, внешние данные, необычные встроенные объекты или собственные функции, преобразование в безголовый режим может не воспроизвести исходное приложение в точности. Перейдите к проверке совместимости на основе корпуса файлов, а не к добавлению случайных параметров командной строки.

4. Электронные таблицы или презентации не конвертируются.

Убедитесь, что установлены соответствующие компоненты LibreOffice. libreoffice-noguiМетапакет Debian включает Writer, Calc, Impress, Draw, Base и Math без поддержки графического интерфейса. Если вы намеренно создали образ меньшего размера только с Writer, при преобразовании в формат XLSX или PPTX может отсутствовать необходимый компонент.

5. Файловая система с корневым каталогом, доступная только для чтения, нарушает запуск системы.

Усиление безопасности с помощью Docker --read-onlyможет быть полезным, но LibreOffice по-прежнему нуждается в местах с правами записи для файлов профиля и временных файлов. Укажите явные пути с правами записи tmpfsили монтированием томов для этих путей. В документации Docker по запуску контейнеров объясняется, как можно комбинировать корневые файловые системы только для чтения с правами записи.

Более ориентированная на производство команда запуска

После того, как базовый процесс заработает, более строгий вызов может сохранять входные данные только для чтения, изолировать временное состояние и удалять контейнер после каждой задачи:

docker run --rm   --read-only   --mount type=bind,src="$(pwd)/input",dst=/input,readonly   --mount type=bind,src="$(pwd)/output",dst=/output   --tmpfs /tmp:rw,nosuid,nodev   --tmpfs /home/office:rw,nosuid,nodev   libreoffice-headless:debian13   -env:UserInstallation=file:///tmp/lo-profile   --convert-to pdf   --outdir /output   /input/sample.docx

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

Самопроверка: как узнать, что настройка готова.

Прежде чем объявить контейнер готовым к использованию в производственной среде, проверьте все следующие параметры:

• soffice --versionсообщает о сборке LibreOffice, которую вы планировали развернуть.
• Известный файл DOCX преобразуется в PDF с корректным завершением работы контейнера.
• PDF-файл отображается на хосте в ненулевом размере и может быть проанализирован или открыт.
• Исходный каталог монтируется только для чтения и остается неизменным.
• Процесс запускается от имени пользователя без прав root, если у вас нет документально подтвержденной причины этого не делать.
• В типовых документах используются стандартные шрифты и сохраняется приемлемая верстка страниц.
• Два одновременных преобразования используют отдельные профили пользователей и не мешают друг другу.
• Ваше приложение рассматривает тайм-ауты, ошибки преобразования и отсутствие выходных данных как сбои, а не как возврат пустого или устаревшего файла.

Если эти проверки пройдут успешно, одноразовый контейнер LibreOffice без графического интерфейса отлично подойдет для задач преобразования документов, где важны изоляция и воспроизводимость. Если основной проблемой станет задержка при запуске, или вам потребуется манипулирование документами на уровне API, а не преобразование форматов, переключитесь на контролируемый постоянный сервис LibreOffice/UNO и протестируйте эту архитектуру отдельно. Docker решает проблемы упаковки и изоляции; он не устраняет необходимости проверки соответствия документов файлам, которые фактически обрабатывает ваше приложение.