如何在 Docker 容器內以無頭模式運行 LibreOffice？

一個常見的伺服器端問題乍看之下很簡單：應用程式接收到 DOCX、XLSX、ODT 或 PPTX 文件，需要返回 PDF 文件，但主機不應該運行桌面會話。直接在主機上安裝完整的辦公室套件也會增加部署的可複現性。 LibreOffice 可以在沒有圖形介面的情況下運行，Docker 也可以隔離轉換運行時，但要獲得可靠的結果，僅僅--headless在命令中添加一些參數是不夠的。

大多數失敗的實際原因都是可以預見的：鏡像缺少所需的 LibreOffice 組件、容器無法寫入其用戶配置文件、綁定掛載的文件權限錯誤、缺少字體、兩個作業共享同一個配置文件，或者輸出目錄不可寫。本指南從最簡單的可用容器入手，然後逐步增強其安全性，以確保文件轉換的可重複性。

截至 2026 年 10 月，LibreOffice 將 26.8 列為其最新特性分支，並將 26.2.6 列為其成熟版本，推薦企業用戶使用。 Debian 13 穩定版軟體套件可能包含不同的、由發行版維護的 LibreOffice 版本，因此請鎖定基礎鏡像並驗證建置容器中的實際版本，而不是假設它與上游版本一致。請參閱LibreOffice 官方發行說明和Debian libreoffice-nogui 軟體包頁面。

「Docker 中的無頭 LibreOffice」究竟是什麼意思？

LibreOffice 文件--headless以無使用者介面模式運作。對於檔案轉換，重要的配套選項是 `--external-file` 和 `--external- --convert-tofile`。 LibreOffice--outdir還需要對其使用者設定檔目錄擁有寫入權限，當您以非 root 使用者身分執行容器或將其根檔案系統設定為唯讀時，這一點尤其重要。權威的 CLI 參考文件是《LibreOffice 幫助：使用參數啟動 LibreOffice 軟體》。

因此，一個好的容器的目標很明確：它應該無需 X11 或桌面即可啟動，讀取輸入文檔，寫入預期的輸出格式，乾淨地退出，並產生一個佈局符合您的工作負載要求的文件。

步驟 1：建立一個小的、可重複的 Docker 映像

對於 Debian 13 上的各種格式轉換，libreoffice-nogui這是一個不錯的起點，因為 Debian 將其描述為主要用於腳本編寫的無 GUI 元軟體包。如果您只轉換 Writer 文檔，則可以透過libreoffice-writer-nogui僅安裝所需的其他無 GUI 元件來減少依賴項。

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

字體包並非只是裝飾性的。辦公室文件經常會引用一些在最小化 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使用綁定掛載的語法。其文件還指出，綁定掛載預設是可寫入的，因此明確地將來源目錄設定為只讀是一種有效的安全措施。請參閱Docker 綁定掛載文件。

步驟 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 pdf請讓 LibreOffice 選擇合適的 PDF 匯出過濾器。如果您需要特定的 PDF 行為，LibreOffice 也提供了過濾器參數的文件；請參閱官方 PDF CLI 參數參考。

步驟 5：為每個並發作業指派一個 LibreOffice 設定檔

單次轉換通常無需額外的設定檔即可完成，但這可能會掩蓋擴充性問題。 LibreOffice 將狀態保存在使用者設定檔中，並且需要對其具有寫入權限。並行工作進程不應爭用同一個設定檔目錄。

使用文件中-env:UserInstallation=...提供的引導變數為工作建立私有設定檔：

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，而且使用 shell 循環也很簡單。例如：

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 可能會很耗費資源。這時，您可以考慮使用 UNO 控制的持久化 LibreOffice 進程--accept=...，LibreOffice 文件中將其作為創建接收器的介面。然而，這會改變操作模式：您現在需要進程監控、請求隔離、逾時、健康檢查以及在處理問題文件後回收進程的策略。對於低或中等吞吐量，一次性容器仍然更容易理解。

步驟 8：檢查視覺效果，而不僅僅是命令是否成功

開啟生成的範例 PDF 文件，並與預期輸出進行比較。特別注意分頁符號、替換字體、嵌入圖像、公式、頁首和頁尾、圖表、電子表格列印區域以及簡報文字方塊。無頭模式無需圖形桌面環境，但並不能保證所有 Office 專有功能都能與 Microsoft Office 完全相同地呈現。

對於自動化回歸測試，請保留一組精心挑選的代表性文檔，並比較諸如頁數、提取文字、圖像尺寸或渲染頁面相似度等可衡量的屬性。請務必仔細審查任何閾值，因為即使是看似無害的 LibreOffice 更新也可能更改 PDF 元資料或細微的佈局細節。

轉換失敗時：先修復簡單的原因。

1. 容器已退出，但沒有輸出。

首先檢查傳遞給 Docker 的路徑--outdir，並確認目標掛載點對 UID 10001 具有寫入權限。 Docker 綁定掛載會將主機檔案系統權限對應到容器中。如果您的主機目錄屬於不同的 UID 且不具有群組寫入權限，則非 root 使用者執行的 LibreOffice 進程可能無法建立輸出。

2. LibreOffice 報告設定檔或鎖定問題

每個並發作業應使用不同的-env:UserInstallation=file:///...路徑。不要讓多個工作進程指向同一個可寫入設定檔目錄。 LibreOffice 文件中同時包含了設定檔要求和UserInstallation覆寫方法。

3. PDF文件已創建，但佈局錯誤

更改匯出選項前請檢查字體。fc-list在圖像內部使用指令確認所需字體是否可見。如果原始檔案依賴巨集、外部資料、特殊的嵌入物件或專有功能，則無頭轉換可能無法完全還原原始應用程式。建議使用基於語料庫的兼容性測試，而不是隨意添加命令列開關。

4. 電子表格或簡報無法轉換

請確保已安裝相應的 LibreOffice 組件。 Debianlibreoffice-nogui元軟體包包含 Writer、Calc、Impress、Draw、Base 和 Math，但不包含圖形使用者介面 (GUI)。如果您特意建立了一個僅包含 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 解決了打包和隔離問題；但它並不能消除驗證文件與應用程式實際處理的文件是否一致的必要性。