كيفية تشغيل 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 صلاحية الكتابة إلى دليل ملف تعريف المستخدم، وهو أمر بالغ الأهمية عند تشغيل حاوية كمستخدم غير الجذر أو عند جعل نظام ملفات الجذر للقراءة فقط. يُمكن الرجوع إلى مرجع سطر الأوامر المعتمد في: LibreOffice Help: Starting LibreOffice Software With Parameters .

وبالتالي فإن الهدف من الحاوية الجيدة محدد: يجب أن تبدأ بدون X11 أو سطح مكتب، وتقرأ مستند إدخال، وتكتب تنسيق الإخراج المتوقع، وتخرج بشكل نظيف، وتنتج ملفًا يكون تخطيطه مقبولًا لحجم العمل الخاص بك.

الخطوة 1: إنشاء صورة Docker صغيرة وقابلة للتكرار

للحصول على تغطية شاملة للتنسيقات على دبيان 13، libreoffice-noguiيُعدّ هذا خيارًا مفيدًا كنقطة انطلاق، إذ تُعرّفه دبيان بأنه حزمة شاملة بدون واجهة رسومية، مُخصصة في الغالب لكتابة البرامج النصية. إذا كنت تُحوّل مستندات 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 العديد من الحالات العامة. إذا كانت مستنداتك تستخدم خطوطًا خاصة بالشركات أو خطوطًا مرخصة، فقم بتثبيت هذه الخطوط أو تحميلها فقط عندما يسمح لك ترخيصك بذلك.

الخطوة الثانية: قم بإنشاء الصورة وتسجيل نسخة 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 الخاصة بعمليات الربط .

الخطوة الرابعة: تحويل مستند واحد إلى ملف 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 أيضًا معلمات المُرشِّح؛ راجع مرجع معلمات واجهة سطر الأوامر (CLI) الرسمي لملفات PDF .

الخطوة 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

يُعدّ ملف تعريف مؤقت خاص مفيدًا بشكل خاص للحاويات قصيرة العمر ومجموعات العمال. tmpfsيوثّق Docker عمليات ربط الملفات المؤقتة في الذاكرة. أما إذا كنت تُشغّل خدمة UNO طويلة الأمد، فاستخدم استراتيجية ملف تعريف دائم مدروسة، وقم بتسلسل الوصول أو عزله وفقًا لتصميم تطبيقك.

الخطوة 6: التحقق من وجود ملف الإخراج بالفعل

بعد خروج الحاوية، افحص دليل الإخراج الخاص بالمضيف:

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

يُعدّ الحصول على حالة خروج صفرية بالإضافة إلى ملف PDF غير فارغ بوابة أتمتة معقولة، لكنها لا تُمثّل اختبارًا كاملاً للدقة. بالنسبة لواجهة برمجة تطبيقات التحويل، يُنصح أيضًا بتحديد مهلة زمنية ورفض أي مخرجات مفقودة أو صغيرة الحجم بشكل غير متوقع. يعتمد الحد الأدنى الأمثل للحجم على مستنداتك، لذا تجنّب استخدام رقم ثابت مُضمّن في الكود إلا إذا قمت بقياس حجم مجموعة مستنداتك.

الخطوة 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وتأكد من أن نقطة التحميل الوجهة قابلة للكتابة بواسطة المستخدم ذي المعرف 10001. تربط عمليات التحميل في Docker أذونات نظام الملفات المضيفة بالحاوية. إذا كان دليل المضيف مملوكًا لمستخدم ذي معرف مختلف وغير قابل للكتابة من قِبل المجموعة، فقد لا تتمكن عملية LibreOffice غير الجذرية من إنشاء المخرجات.

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

يعتمد نجاح هذا الإجراء الأمني ​​مع جميع أنواع المستندات على الإضافات، والميزات المعتمدة على جافا، والقواميس، ومتطلبات وقت التشغيل الأخرى. أضف مسارات قابلة للكتابة فقط عندما يتطلبها عبء عمل مُتحقق منه، بدلاً من جعل الحاوية بأكملها قابلة للكتابة.

الفحص الذاتي: كيف تعرف أن الإعداد جاهز

قبل اعتبار الحاوية جاهزة للإنتاج، تحقق من كل ما يلي:

• soffice --versionيُبلغ عن إصدار LibreOffice الذي كنت تنوي نشره.
• يتم تحويل ملف DOCX معروف إلى PDF مع خروج نظيف من الحاوية.
• يظهر ملف PDF على الجهاز المضيف بحجم غير صفري ويمكن تحليله أو فتحه.
• يتم تثبيت دليل المصدر للقراءة فقط ويبقى دون تغيير.
• يتم تشغيل العملية كمستخدم غير جذري إلا إذا كان لديك سبب موثق لعدم القيام بذلك.
• تستخدم المستندات النموذجية الخطوط المتوقعة وتحافظ على تخطيط الصفحة المقبول.
• تستخدم عمليتا التحويل المتزامنتان ملفات تعريف مستخدمين منفصلة ولا تتداخلان مع بعضهما البعض.
• يتعامل تطبيقك مع حالات انتهاء المهلة، وأخطاء التحويل، وفقدان المخرجات على أنها حالات فشل بدلاً من إرجاع ملف فارغ أو قديم.

إذا اجتازت هذه الاختبارات بنجاح، فإن حاوية LibreOffice أحادية التشغيل بدون واجهة رسومية تُعدّ خيارًا مثاليًا لمهام تحويل المستندات التي تُولي أهميةً للعزل وإمكانية التكرار. أما إذا أصبح زمن بدء التشغيل هو التكلفة الرئيسية، أو كنتَ بحاجة إلى معالجة المستندات على مستوى واجهة برمجة التطبيقات (API) بدلًا من تحويل التنسيق، فانتقل إلى خدمة LibreOffice/UNO مُدارة ومستمرة، واختبر هذه البنية بشكل منفصل. يُقدّم Docker حلولًا للتغليف والعزل، ولكنه لا يُغني عن التحقق من دقة المستندات ومطابقتها مع الملفات التي يُعالجها تطبيقك فعليًا.