วิธีใช้งาน LibreOffice แบบ Headless ภายในคอนเทนเนอร์ Docker

ปัญหาฝั่งเซิร์ฟเวอร์ทั่วไปที่ดูเหมือนจะง่ายในตอนแรกคือ แอปพลิเคชันรับไฟล์ DOCX, XLSX, ODT หรือ PPTX และต้องการแปลงกลับเป็นไฟล์ PDF แต่โฮสต์ไม่ควรใช้งานเซสชันเดสก์ท็อป การติดตั้งชุดโปรแกรมสำนักงานแบบเต็มรูปแบบลงบนโฮสต์โดยตรงก็ทำให้การปรับใช้ทำซ้ำได้ยากขึ้นเช่นกัน LibreOffice สามารถทำงานได้โดยไม่ต้องมีอินเทอร์เฟซแบบกราฟิก และ Docker สามารถแยกการทำงานของการแปลงไฟล์ได้ แต่ผลลัพธ์ที่เชื่อถือได้นั้นขึ้นอยู่กับมากกว่าแค่การเพิ่ม--headlessคำสั่งลงไป

สาเหตุหลักของความล้มเหลวส่วนใหญ่สามารถคาดเดาได้ เช่น รูปภาพไม่มีส่วนประกอบ LibreOffice ที่จำเป็น คอนเทนเนอร์ไม่สามารถเขียนโปรไฟล์ผู้ใช้ได้ ไฟล์ที่เชื่อมต่อมีสิทธิ์การเข้าถึงไม่ถูกต้อง ฟอนต์หายไป งานสองงานใช้โปรไฟล์เดียวกัน หรือไดเร็กทอรีเอาต์พุตไม่สามารถเขียนได้ คู่มือนี้เริ่มต้นด้วยคอนเทนเนอร์ที่ใช้งานได้แบบง่ายที่สุด จากนั้นจึงปรับปรุงให้มีความแข็งแกร่งมากขึ้นเพื่อให้สามารถแปลงเอกสารซ้ำได้

ณ เดือนตุลาคม 2026 LibreOffice ระบุเวอร์ชัน 26.8 เป็นเวอร์ชันล่าสุดที่มีฟีเจอร์ครบครัน และ 26.2.6 เป็นเวอร์ชันก่อนหน้าที่มีความเสถียรและแนะนำสำหรับการใช้งานในองค์กร แพ็กเกจ Debian 13 เวอร์ชันเสถียรอาจมีเวอร์ชัน LibreOffice ที่แตกต่างกัน ซึ่งดูแลโดยระบบปฏิบัติการ ดังนั้นควรกำหนดเวอร์ชันพื้นฐานของอิมเมจและตรวจสอบเวอร์ชันจริงในคอนเทนเนอร์ที่สร้างขึ้นแทนที่จะสันนิษฐานว่าตรงกับเวอร์ชันต้นทาง โปรดดูบันทึกการเผยแพร่ LibreOffice อย่างเป็นทางการและ หน้าแพ็กเก จlibreoffice-nogui ของ Debian

“LibreOffice แบบไม่มีส่วนติดต่อผู้ใช้ใน Docker” หมายความว่าอย่างไรกันแน่

LibreOffice --headlessมีโหมดการทำงานที่ไม่มีส่วนติดต่อผู้ใช้ สำหรับการแปลงไฟล์ ตัวเลือกที่สำคัญคือ--convert-toและ นอกจากนี้--outdirLibreOffice ยังต้องการสิทธิ์ในการเขียนไปยังไดเร็กทอรีโปรไฟล์ผู้ใช้ ซึ่งเป็นรายละเอียดที่สำคัญเมื่อคุณเรียกใช้คอนเทนเนอร์ในฐานะผู้ใช้ที่ไม่ใช่ root หรือทำให้ระบบไฟล์ root เป็นแบบอ่านอย่างเดียว เอกสารอ้างอิง CLI ที่เชื่อถือได้คือLibreOffice Help: Starting LibreOffice Software With Parameters

ดังนั้นเป้าหมายของคอนเทนเนอร์ที่ดีจึงมีความเฉพาะเจาะจง: ควรเริ่มต้นโดยไม่ต้องใช้ 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"]

ชุดฟอนต์ไม่ได้มีไว้เพื่อตกแต่งเท่านั้น เอกสาร 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 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 แบบตรงไปตรง มา LibreOffice จะเลือกตัวกรองการส่งออก PDF ที่เหมาะสมให้ เมื่อคุณต้องการพฤติกรรม PDF ที่เฉพาะเจาะจง LibreOffice ยังได้จัดทำเอกสารเกี่ยวกับพารามิเตอร์ตัวกรองไว้ด้วย โปรด--convert-to pdfดูเอกสารอ้างอิงพารามิเตอร์ CLI ของ 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 ระบุว่าเป็นอินเทอร์เฟซสำหรับการสร้างตัวรับ (acceptor) อย่างไรก็ตาม วิธีนี้จะเปลี่ยนรูปแบบการทำงาน: ตอนนี้คุณต้องการการกำกับดูแลกระบวนการ การแยกคำขอ การหมดเวลา การตรวจสอบสถานะ และกลยุทธ์สำหรับการนำกระบวนการกลับมาใช้ใหม่หลังจากเอกสารที่มีปัญหา คอนเทนเนอร์แบบใช้ครั้งเดียว (one-shot container) ยังคงเข้าใจง่ายกว่าสำหรับปริมาณงานต่ำหรือปานกลาง

ขั้นตอนที่ 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 โดยไม่มีการสนับสนุน GUI หากคุณสร้างอิมเมจขนาดเล็กโดยตั้งใจให้มีเฉพาะ Writer เท่านั้น การแปลงเป็นไฟล์ XLSX หรือ PPTX อาจขาดส่วนประกอบที่จำเป็น

5. ระบบไฟล์รูทแบบอ่านอย่างเดียวทำให้การเริ่มต้นระบบล้มเหลว

การเสริมความปลอดภัยด้วย Docker --read-onlyอาจมีประโยชน์ แต่ LibreOffice ยังคงต้องการตำแหน่งที่สามารถเขียนได้สำหรับไฟล์โปรไฟล์และไฟล์ชั่วคราว จึงควรระบุการเชื่อมต่อแบบเขียนได้หรือแบบ Volume Mount สำหรับเส้นทางเหล่านั้นอย่างชัดเจนเอกสารประกอบการใช้งานคอนเทนเนอร์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 จะปรากฏบนเครื่องโฮสต์โดยมีขนาดไม่เป็นศูนย์ และสามารถแยกวิเคราะห์หรือเปิดได้
• ไดเร็กทอรีต้นทางถูกเมานต์ในโหมดอ่านอย่างเดียวและจะไม่มีการเปลี่ยนแปลงใดๆ
• กระบวนการนี้จะทำงานโดยใช้สิทธิ์ผู้ใช้ทั่วไป เว้นแต่จะมีเหตุผลที่ระบุไว้เป็นลายลักษณ์อักษรที่ห้ามใช้สิทธิ์นั้น
• เอกสารตัวอย่างใช้แบบอักษรที่คาดหวังและรักษาเค้าโครงหน้าเว็บที่ยอมรับได้
• การแปลงข้อมูลพร้อมกันสองครั้งจะใช้โปรไฟล์ผู้ใช้แยกกันและจะไม่รบกวนซึ่งกันและกัน
• แอปพลิเคชันของคุณถือว่าการหมดเวลา ข้อผิดพลาดในการแปลง และผลลัพธ์ที่หายไปเป็นความล้มเหลว แทนที่จะส่งคืนไฟล์ว่างเปล่าหรือไฟล์ที่ล้าสมัย

หากการตรวจสอบเหล่านั้นผ่าน การใช้คอนเทนเนอร์ LibreOffice แบบ one-shot headless จะเหมาะสมกับงานแปลงเอกสารที่ให้ความสำคัญกับการแยกส่วนและการทำซ้ำได้ แต่หากเวลาในการเริ่มต้นทำงานกลายเป็นต้นทุนหลัก หรือคุณต้องการการจัดการเอกสารในระดับ API มากกว่าการแปลงรูปแบบ ให้เปลี่ยนไปใช้บริการ LibreOffice/UNO แบบถาวรที่มีการดูแล และทดสอบสถาปัตยกรรมนั้นแยกต่างหาก Docker ช่วยแก้ปัญหาเรื่องการบรรจุและการแยกส่วน แต่ไม่ได้ขจัดความจำเป็นในการตรวจสอบความถูกต้องของเอกสารกับไฟล์ที่แอปพลิเคชันของคุณประมวลผลจริง