在 Docker 中以無頭模式運行 LibreOffice 進行 PDF 轉換

是的。對於一次性文件轉換，可以建立一個安裝了 LibreOffice 的小型 Docker 映像並運行soffice --headless。--convert-to將輸入目錄掛載為唯讀，並將一個單獨的輸出目錄設定為寫入，這樣 PDF 檔案就會出現在您的主機上。本範例使用基於 Debian 的鏡像，並將一個 DOCX 檔案轉換為 PDF；它不會將 LibreOffice 作為網路服務公開。

終端編輯器顯示基於 Debian 的 Dockerfile，其中已安裝 LibreOffice Writer 和字型。 — Dockerfile 安裝了 LibreOffice Writer 和一個基礎字型包，然後使用 soffice 作為容器指令。

無頭模式的作用是什麼？ Docker 在什麼情況下有用？

無頭模式啟動 LibreOffice 時不顯示圖形介面。 LibreOffice 文件中提供了該模式的命令列和 API 控制使用說明，其命令列選項支援檔案轉換並指定輸出目錄。 Docker 將應用程式及其相依性打包，因此腳本或工作站無需在主機上安裝桌面套件即可執行相同的容器映像。

此模式適用於本機批次作業、持續整合任務或接收檔案並保存轉換結果的後端工作流程。普通的無頭容器本身並非 HTTP 轉換 API：它不監聽任何端口，也不接受任何 Web 上傳請求。如果您需要持久化服務，請在轉換過程周圍新增 API 和作業佇列，並設定請求驗證、逾時、檔案大小限制和隔離機制。

1. 建立輸入和輸出資料夾

在 Linux 或 macOS 主機上使用 Bash 或類似 shell，建立一個包含多個子目錄的專案資料夾。將來源文件放入其中input，並output在首次運行時留空：

mkdir -p lo-work/input lo-work/output
cp report.docx lo-work/input/
cd lo-work

以下 Docker 指令使用 Unix 風格的路徑和 shell 語法。在 Windows 系統上，請根據 PowerShell 或命令提示字元調整主機路徑語法，並確保 Docker Desktop 有權共用包含這些資料夾的磁碟機。

2. 建造包含 LibreOffice 的鏡像。

Dockerfile建立一個名為inside 的文件，lo-work內容如下：

FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y --no-install-recommends \
    libreoffice-writer fonts-liberation \
    && rm -rf /var/lib/apt/lists/*

ENTRYPOINT ["soffice"]

libreoffice-writer提供 Writer 和常用文字處理格式所需的轉換過濾器。如果需要轉換電子表格或簡報，請新增相應的篩選器。字體包libreoffice-calc僅供libreoffice-impress參考；請安裝文件所需且您擁有使用權限的字體，因為缺少字體可能會影響換行和分頁。

從包含 Dockerfile 的目錄建立映像：

docker build -t lo-headless .

本範例使用 Debian Bookworm 軟體包名稱。基礎鏡像標籤和軟體倉庫軟體包會隨時間變化；對於生產環境構建，請選擇維護良好的基礎鏡像，定期重新構建以進行安全更新，如果需要可復現的構建，則通過摘要鎖定基礎鏡像。避免為了模仿教學而安裝來自無關軟體倉庫的軟體包。

終端機顯示 docker build -t lo-headless . 正在完成容器映像構建 — 在執行轉換容器之前，請根據 Dockerfile 建置本機映像。

3. 使用單獨的掛載點來執行 LibreOffice

啟動一個一次性容器，並在鏡像名稱後傳遞轉換選項。輸入掛載點為唯讀；只有輸出目錄可寫入。此--user選項在 Linux 系統上使用您的主機使用者和群組 ID 運行進程，同時HOME=/tmp為 LibreOffice 提供一個可寫入的主目錄。如果主機使用者沒有寫入權限，請調整資料夾權限output。

docker run --rm \
  --user "$(id -u):$(id -g)" \
  --env HOME=/tmp \
  -v "$PWD/input:/input:ro" \
  -v "$PWD/output:/output" \
  lo-headless \
  --headless --nologo \
  -env:UserInstallation=file:///tmp/lo-profile \
  --convert-to pdf:writer_pdf_Export \
  --outdir /output \
  /input/report.docx

--headless此操作會抑制圖形使用者介面 (GUI)，--convert-to pdf:writer_pdf_Export選擇 PDF 匯出過濾器，並將--outdir結果導向已掛載的輸出資料夾。唯一的使用者設定檔路徑為該進程提供了一個可寫入的 LibreOffice 配置目錄；如果在一個長期運行的容器中同時執行多個轉換任務，請為每個進程使用不同的設定檔路徑。

如果您喜歡 Docker 更明確的掛載語法，請使用` --mount<mk>` 而不是-v`<mk>`。綁定掛載綁定到 Docker 守護程序所在主機上的路徑，而讀寫掛載允許容器程序修改主機檔案。請盡量縮小掛載範圍，避免掛載您的主目錄或 Docker 套接字，並且不要執行具有不必要權限的文件轉換工作進程。

使用終端命令運行具有唯讀輸入、可寫入輸出、無頭轉換和獨立設定檔的 lo-headless 容器 — 運行命令將來源檔案傳遞給 soffice，同時限制主機對兩個專案資料夾的存取權限。

4. 確認 PDF 檔案已建立

Docker 退出後，檢查主機輸出目錄：

ls -l output/
file output/report.pdf
test -s output/report.pdf

PDF 檔案必須存在且不為空。在確認轉換結果之前，請使用 PDF 閱讀器開啟它，並檢查頁數、表格、圖像、分頁符號和字體。即使轉換過程成功退出，也不能保證所有元素都按預期渲染，尤其當文件使用了容器中不支援的字體或功能時。每次執行轉換時，請使用乾淨的輸出目錄或新的輸出檔名，以免將舊的 PDF 檔案誤認為是最新的轉換結果。

終端輸出目錄中的 report.pdf 文件，並將其識別為 PDF 文件。 — 檢查輸出文件是否存在且被識別為 PDF 文件，然後檢查頁面佈局是否有更改。

如果轉換失敗，我該檢查什麼？

沒有輸出檔案：input請確認掛載點處的來源檔案名稱和容器路徑，並確認所選使用者對/input主機目錄具有寫入權限。output
設定檔或鎖定錯誤：請確認-env:UserInstallation路徑可寫入。請為每個同時執行的 LibreOffice 進程使用單獨的設定檔目錄。
版面配置已變更：請在影像中安裝所需字型並檢查 PDF 檔案。由於字體可用性、匯出濾鏡和版本差異，渲染效果可能與桌上型系統有所不同。
Docker 掛載錯誤：-v在使用 `docker mount`或 ` docker mount` 之前，請先驗證兩個主機目錄是否存在--mount，並驗證守護程式是否可以存取它們。

若要了解特定選項行為，請參閱LibreOffice 的命令列參數參考文件。您可以在Debian Bookworm 軟體包清單中找到 LibreOffice Writer 的軟體包名稱。 Docker 的官方文件解釋了綁定掛載和Dockerfile 指令。