Jak uruchomić LibreOffice w trybie headless w kontenerze Docker

Typowy problem po stronie serwera wydaje się na pierwszy rzut oka prosty: aplikacja otrzymuje plik DOCX, XLSX, ODT lub PPTX i musi zwrócić plik PDF, ale host nie powinien uruchamiać sesji pulpitu. Instalacja pełnego pakietu biurowego bezpośrednio na hoście również utrudnia odtworzenie wdrożeń. LibreOffice może działać bez interfejsu graficznego, a Docker może izolować środowisko wykonawcze konwersji, ale wiarygodne wyniki zależą od czegoś więcej niż tylko dodania --headlessdo polecenia.

Praktyczne przyczyny większości awarii są przewidywalne: obraz nie zawiera wymaganego komponentu LibreOffice, kontener nie może zapisać swojego profilu użytkownika, pliki montowane przez bind mają nieprawidłowe uprawnienia, brakuje czcionek, dwa zadania korzystają z tego samego profilu lub katalog wyjściowy nie jest zapisywalny. Niniejszy przewodnik rozpoczyna się od najprostszego działającego kontenera, a następnie wzmacnia go, aby umożliwić powtarzalną konwersję dokumentów.

Od października 2026 roku LibreOffice wymienia wersję 26.8 jako najnowszą gałąź funkcyjną, a 26.2.6 jako dojrzałą poprzednią gałąź, zalecaną do użytku korporacyjnego. Pakiety stabilne Debiana 13 mogą zawierać inną, utrzymywaną przez dystrybucję wersję LibreOffice, dlatego należy przypiąć obraz bazowy i zweryfikować rzeczywistą wersję w skompilowanym kontenerze, zamiast zakładać, że jest zgodna z wersją źródłową. Zapoznaj się z oficjalnymi informacjami o wydaniu LibreOffice oraz stroną pakietu Debian libreoffice-nogui .

Co tak naprawdę oznacza „Headless LibreOffice w Dockerze”

Dokumenty LibreOffice --headlessdziałają w trybie bez interfejsu użytkownika. W przypadku konwersji plików ważnymi opcjami towarzyszącymi są opcje --convert-toi --outdir. LibreOffice wymaga również dostępu do zapisu w katalogu profilu użytkownika, co ma znaczenie, gdy uruchamiasz kontener jako użytkownik inny niż root lub gdy ustawiasz system plików root jako tylko do odczytu. Autorytatywnym dokumentem CLI jest dokument LibreOffice Help: Starting LibreOffice Software With Parameters .

Cel dobrego kontenera jest zatem konkretny: powinien uruchamiać się bez środowiska X11 lub pulpitu, odczytywać dokument wejściowy, zapisywać oczekiwany format wyjściowy, kończyć pracę w czysty sposób i generować plik o układzie akceptowalnym dla danego obciążenia.

Krok 1: Utwórz mały, powtarzalny obraz Dockera

W przypadku szerokiego zakresu formatów w Debianie 13, libreoffice-noguijest to przydatny punkt wyjścia, ponieważ Debian opisuje go jako metapakiet bez interfejsu graficznego, przeznaczony głównie do skryptów. Jeśli konwertujesz tylko dokumenty Writera, możesz zmniejszyć zależności, instalując libreoffice-writer-noguitylko inne, potrzebne komponenty bez interfejsu graficznego.

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"]

Pakiety czcionek nie mają charakteru kosmetycznego. Dokumenty pakietu Office często odwołują się do czcionek, które nie są zainstalowane w minimalnym obrazie systemu Linux. LibreOffice zastąpi je inną czcionką, gdy żądana jest niedostępna, co może zmienić zawijanie wierszy, liczbę stron, szerokość tabeli i układ slajdów. Carlito i Caladea to powszechnie przydatne zamienniki zgodne ze standardem metrycznym dla czcionek Calibri i Cambria, natomiast Liberation i DejaVu sprawdzają się w wielu ogólnych przypadkach. Jeśli w dokumentach używane są czcionki firmowe lub licencjonowane, należy je instalować lub montować tylko wtedy, gdy zezwala na to licencja.

Krok 2: Utwórz obraz i zapisz wersję LibreOffice

docker build -t libreoffice-headless:debian13 .

Następnie sprawdź wersję, która faktycznie znajduje się na obrazie:

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

To sprawdzenie ma znaczenie, gdy obraz bazowy jest odbudowywany kilka tygodni później. Jeśli dokładne renderowanie jest ważne, należy użyć niezmiennego skrótu obrazu w środowisku produkcyjnym i celowo odbudować go po aktualizacjach zabezpieczeń lub LibreOffice. Tagi „Najnowsze” są wygodne podczas eksperymentów, ale utrudniają badanie różnic w wynikach.

Krok 3: Przygotuj oddzielne katalogi wejściowe i wyjściowe

Utwórz dwa katalogi hosta. Strona wejściowa może być tylko do odczytu; strona wyjściowa musi mieć uprawnienia do zapisu dla użytkownika kontenera.

mkdir -p input output
cp sample.docx input/

Docker zaleca tę --mountskładnię dla montowań typu bind. W dokumentacji zaznaczono również, że montowania typu bind są domyślnie zapisywalne, więc jawne ustawienie katalogu źródłowego jako tylko do odczytu jest przydatnym zabezpieczeniem. Zobacz dokumentację montowań typu bind w Dockerze .

Krok 4: Konwertuj jeden dokument do formatu PDF

Uruchom kontener jednorazowy i zamontuj katalog źródłowy w trybie tylko do odczytu:

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 oficjalnie obsługuje ten --convert-to OutputFileExtension[:OutputFilterName[:OutputFilterParams]]format. Aby umożliwić prostą konwersję z Writer do PDF, --convert-to pdfLibreOffice pozwala wybrać odpowiedni filtr eksportu PDF. Jeśli potrzebujesz konkretnego zachowania PDF, LibreOffice dokumentuje również parametry filtrów; zobacz oficjalne zestawienie parametrów PDF CLI .

Krok 5: Nadaj każdemu zadaniu współbieżnemu własny profil LibreOffice

Pojedyncza konwersja często działa bez dodatkowej konfiguracji profilu, co może maskować problem ze skalowaniem. LibreOffice przechowuje stan w profilu użytkownika i wymaga dostępu do zapisu. Równoległe procesy robocze nie powinny konkurować o ten sam katalog profilu.

Użyj udokumentowanej -env:UserInstallation=...zmiennej bootstrap, aby nadać zadaniu profil prywatny:

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

Prywatny profil tymczasowy jest szczególnie przydatny w przypadku kontenerów o krótkim czasie życia i pul roboczych. Docker dokumentuje tmpfsmontowanie tymczasowych plików w pamięci. Jeśli zamiast tego uruchamiasz usługę UNO o długim czasie życia, zastosuj przemyślaną strategię trwałego profilu i serializuj lub izoluj dostęp zgodnie z projektem aplikacji.

Krok 6: Sprawdź, czy plik wyjściowy rzeczywiście istnieje

Po wyjściu z kontenera sprawdź katalog wyjściowy hosta:

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

Zerowy status wyjścia i niepusty plik PDF to rozsądna bramka automatyzacji, ale nie jest to pełny test wierności. W przypadku interfejsu API konwersji należy również ustawić limit czasu i odrzucić brakujące lub nieoczekiwanie małe dane wyjściowe. Prawidłowy próg rozmiaru zależy od dokumentów, dlatego należy unikać uniwersalnej, zakodowanej na stałe wartości, chyba że dokonano pomiaru korpusu.

Krok 7: Ostrożnie obsługuj partie zamiast bezmyślnie udostępniać jeden proces

LibreOffice może akceptować wiele plików wejściowych za pomocą --convert-to, a pętla powłoki jest również prosta. Na przykład:

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

Aby zwiększyć przepustowość, wielokrotne uruchamianie LibreOffice może być kosztowne. W tym momencie można rozważyć trwały proces LibreOffice kontrolowany przez UNO za pomocą --accept=..., który LibreOffice dokumentuje jako interfejs do tworzenia akceptora. Zmienia to jednak model operacyjny: teraz potrzebny jest nadzór nad procesami, izolacja żądań, limity czasu, kontrole poprawności oraz strategia ponownego uruchamiania procesu po wystąpieniu problematycznych dokumentów. Kontener jednorazowy pozostaje łatwiejszy do zastosowania w przypadku małych lub średnich wolumenów.

Krok 8: Sprawdź wierność wizualną, a nie tylko skuteczność polecenia

Otwórz reprezentatywne wygenerowane pliki PDF i porównaj je z oczekiwanymi wynikami. Zwróć szczególną uwagę na podziały stron, podstawione czcionki, osadzone obrazy, równania, nagłówki i stopki, wykresy, obszary wydruku arkusza kalkulacyjnego oraz pola tekstowe prezentacji. Tryb bezgłowy eliminuje wymóg graficznego pulpitu; nie gwarantuje on jednak, że każda zastrzeżona funkcja pakietu Office będzie renderowana identycznie jak w pakiecie Microsoft Office.

Do zautomatyzowanych testów regresyjnych należy zachować wyselekcjonowany zestaw reprezentatywnych dokumentów i porównać mierzalne właściwości, takie jak liczba stron, wyodrębniony tekst, wymiary obrazów czy podobieństwo renderowanych stron. Należy dokładnie sprawdzić każdy próg, ponieważ nieszkodliwe aktualizacje LibreOffice mogą zmienić metadane PDF lub drobne szczegóły układu.

Gdy konwersja się nie powiedzie: najpierw napraw proste przyczyny

1. Kontener wychodzi, ale nie pojawia się żaden wynik

Najpierw sprawdź przekazaną ścieżkę --outdiri upewnij się, że docelowy punkt montowania jest dostępny do zapisu dla UID 10001. Punkty montowania Dockera mapują uprawnienia systemu plików hosta do kontenera. Jeśli katalog hosta jest własnością innego UID i nie jest dostępny do zapisu dla grupy, proces LibreOffice inny niż root może nie być w stanie utworzyć danych wyjściowych.

2. LibreOffice zgłasza problem z profilem lub blokadą

Użyj oddzielnej -env:UserInstallation=file:///...ścieżki dla każdego zadania jednocześnie. Nie kieruj kilku pracowników do jednego katalogu profilu z możliwością zapisu. LibreOffice dokumentuje zarówno wymagania dotyczące profilu, jak i jego UserInstallationnadpisanie.

3. Plik PDF został utworzony, ale układ jest nieprawidłowy

Sprawdź czcionki przed zmianą opcji eksportu. Użyj opcji fc-listwewnątrz obrazu, aby upewnić się, że wymagane czcionki są widoczne. Jeśli plik źródłowy opiera się na makrach, danych zewnętrznych, nietypowych obiektach osadzonych lub zastrzeżonych funkcjach, konwersja bezgłowa może nie odtworzyć dokładnie oryginalnej aplikacji. Przeprowadź test zgodności oparty na korpusie zamiast dodawać losowe przełączniki wiersza poleceń.

4. Arkusze kalkulacyjne i prezentacje nie konwertują

Upewnij się, że zainstalowane są odpowiednie komponenty LibreOffice. libreoffice-noguiMetapakiet Debiana zawiera programy Writer, Calc, Impress, Draw, Base i Math bez obsługi graficznego interfejsu użytkownika. Jeśli celowo utworzyłeś mniejszy obraz tylko za pomocą Writera, konwersja XLSX lub PPTX może nie zawierać wymaganego komponentu.

5. System plików głównych tylko do odczytu przerywa uruchamianie

Utwardzanie za pomocą Dockera --read-onlymoże być przydatne, ale LibreOffice nadal potrzebuje lokalizacji z możliwością zapisu dla swojego profilu i plików tymczasowych. Należy podać jawne zapisywalne lub woluminowe montowania dla tych ścieżek. Dokumentacja uruchamiania kontenerówtmpfs Dockera wyjaśnia, jak można łączyć systemy plików głównych tylko do odczytu z zapisywalnymi montowaniami.

Polecenie uruchomienia bardziej zorientowane na produkcję

Po uruchomieniu podstawowego przepływu bardziej rygorystyczne wywołanie może zachować dane wejściowe tylko do odczytu, odizolować stan tymczasowy i usunąć kontener po każdym zadaniu:

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

To, czy to konkretne wzmocnienie zadziała dla każdego typu dokumentu, zależy od rozszerzeń, funkcji zależnych od Javy, szablonów, słowników i innych potrzeb środowiska wykonawczego. Dodawaj ścieżki zapisu tylko wtedy, gdy wymaga tego zweryfikowane obciążenie, zamiast ustawiać cały kontener jako zapisywalny.

Samokontrola: jak sprawdzić, czy konfiguracja jest gotowa

Przed uznaniem kontenera za gotowy do produkcji należy sprawdzić wszystkie poniższe elementy:

• soffice --versionraportuje kompilację LibreOffice, którą zamierzasz wdrożyć.
• Znany plik DOCX jest konwertowany do pliku PDF z czystym wyjściem kontenera.
• Plik PDF pojawia się na hoście w rozmiarze różnym od zera i można go analizować i otwierać.
• Katalog źródłowy jest zamontowany w trybie tylko do odczytu i pozostaje niezmieniony.
• Proces ten jest uruchamiany przez użytkownika innego niż root, chyba że istnieją udokumentowane powody, dla których nie wolno tego robić.
• Dokumenty reprezentatywne używają oczekiwanych czcionek i zachowują akceptowalny układ strony.
• Dwie jednoczesne konwersje korzystają z oddzielnych profili użytkowników i nie kolidują ze sobą.
• Twoja aplikacja traktuje przekroczenia limitu czasu, błędy konwersji i brakujące dane wyjściowe jako błędy, zamiast zwracać pusty lub nieaktualny plik.

Jeśli te testy zakończą się sukcesem, kontener LibreOffice typu headless (bez interfejsu graficznego) idealnie nadaje się do zadań konwersji dokumentów, w których ważna jest izolacja i powtarzalność. Jeśli opóźnienie podczas uruchamiania stanie się dominującym kosztem lub potrzebujesz manipulacji dokumentami na poziomie API, a nie konwersji formatu, przejdź na nadzorowaną, trwałą usługę LibreOffice/UNO i przetestuj tę architekturę osobno. Docker rozwiązuje problemy z pakowaniem i izolacją, ale nie eliminuje konieczności weryfikacji zgodności dokumentów z plikami, które aplikacja faktycznie przetwarza.