أمان محسّن
تُعد الترجمة المعزولة النهج الموصى به لـ Ayakaleaf Pro، نظرًا لأن كثيرًا من مستندات LaTeX تتطلب تنفيذ أوامر صدفة (shell) عشوائية أو تملك القدرة على ذلك كجزء من عملية ترجمة PDF. فإذا استخدمت الترجمة المعزولة، فإن كل عملية ترجمة تعمل في حاوية Docker منفصلة ذات قدرات محدودة لا تشاركها مع أي مستخدم أو مشروع آخر، ولا تملك أي وصول إلى الموارد الخارجية مثل شبكة المضيف.إدارة أسهل للحزم
لتجنّب تثبيت الحزم يدويًا، نوصي بتفعيل الترجمة المعزولة. وهو إعداد قابل للتهيئة في Ayakaleaf Pro يوفر لمستخدميك الوصول إلى بيئة TeX Live نفسها الموجودة على overleaf.com ولكن داخل تثبيتك المحلي. وتحتوي صور TeX Live التي تستخدمها الترجمة المعزولة على أكثر الحزم والخطوط شيوعًا والتي اختُبرت مع قوالب معرضنا، مما يضمن أقصى قدر من التوافق مع المشاريع المحلية. يتيح لك تفعيل الترجمة المعزولة تحديد إصدارات TeX Live التي يمكن للمستخدمين الاختيار منها داخل مشاريعهم، إلى جانب تعيين إصدار افتراضي لصورة TeX Live للمشاريع الجديدة.إذا حاولت تشغيل Ayakaleaf Pro دون الترجمة المعزولة، فسيستخدم المثيل افتراضيًا إصدارًا من TeX Live بالمخطط الأساسي (basic scheme) لعمليات الترجمة. وهذا الإصدار الأساسي خفيف ولا يحتوي إلا على مجموعة فرعية محدودة جدًا من حزم LaTeX، مما سيؤدي على الأرجح إلى أخطاء حزم مفقودة لدى مستخدميك، خاصةً إذا حاولوا استخدام قوالب جاهزة.
تتطلب الترجمة المعزولة أن يكون للحاوية
sharelatex وصول إلى مقبس Docker (Docker socket) على الجهاز المضيف (عبر ربط bind mount) حتى تتمكن من إدارة حاويات الترجمة الشقيقة هذه.كيف تعمل
عند تفعيل الترجمة المعزولة، يُربط مقبس Docker من الجهاز المضيف داخل الحاويةsharelatex، حتى تتمكن خدمة المترجم داخل الحاوية من إنشاء حاويات Docker جديدة على المضيف. ثم في كل مرة يُشغَّل فيها المترجم لكل مشروع، تقوم خدمة مترجم LaTeX (CLSI) بما يلي:
- كتابة ملفات المشروع إلى موقع داخل
OVERLEAF_DATA_PATH. - استخدام مقبس Docker المربوط لإنشاء حاوية
texliveجديدة لعملية الترجمة. - جعل الحاوية
texliveتقرأ بيانات المشروع من الموقع الموجود ضمنOVERLEAF_DATA_PATH. - ترجمة المشروع داخل الحاوية
texlive.
تفعيل الترجمة المعزولة
لمستخدمي Toolkit
لتفعيل الترجمة المعزولة (المعروفة أيضًا بالحاويات الشقيقة Sibling containers)، اضبط خيارات الإعداد التالية فيoverleaf-toolkit/config/overleaf.rc:
config/overleaf.rc
SIBLING_CONTAINERS_ENABLED=false وشغّل bin/up. تعمل عمليات الترجمة حينئذٍ داخل الحاوية sharelatex باستخدام TeX Live الأساسي فيها.
لمستخدمي Docker Compose
إعداد صورة TexLive
بالنسبة للمستخدمين في البر الرئيسي للصين، يمكنكم سحب الصور من المرآة لا تستخدموا
ghcr.nju.edu.cn لتسريع التنزيل، ثم وسمها باسمها على ghcr.io:ghcr.nju.edu.cn في إعدادات البيئة الخاصة بـ toolkit: أبقوا أسماء ghcr.io هناك. لمنع bin/up من سحب الصور من ghcr.io مجددًا، اضبطوا SIBLING_CONTAINERS_PULL=false في config/overleaf.rc. للحفاظ على تحديث الصور عبر المرآة، راجعوا تحديث صور TeX Live Full تلقائيًا.TEX_LIVE_DOCKER_IMAGE(اختياري)، صورة TeX Live التي تستخدمها المشاريع الجديدة. ويجب أن تكون إحدى الصور المُدرجة فيALL_TEX_LIVE_DOCKER_IMAGES. إذا لم تُضبط، تستخدم المشاريع الجديدة الصورة الأولى فيALL_TEX_LIVE_DOCKER_IMAGES.ALL_TEX_LIVE_DOCKER_IMAGE_NAMES(اختياري)، قائمة مفصولة بفواصل بأسماء الصور، بالترتيب نفسه، تُعرض في إعدادات المترجم. إذا لم تُضبط، أو كانت أقصر من قائمة الصور، تُعرض الصورة باستخدام وسمها، مثل2026.1.ALL_TEX_LIVE_DOCKER_IMAGES(مطلوب)، قائمة مفصولة بفواصل بصور TeX Live المراد استخدامها. وإذا استُخدمت Overleaf Toolkit للنشر، فستُنزَّل هذه الصور أو تُحدَّث. ولتخطي التنزيل، اضبطSIBLING_CONTAINERS_PULL=falseفيconfig/overleaf.rc.
bin/up، ستسحب Toolkit تلقائيًا جميع الصور المدرجة في ALL_TEX_LIVE_DOCKER_IMAGES.
إليك مثالًا نستخدم فيه TeX Live 2026 افتراضيًا للمشاريع الجديدة، ونُبقي على 2025 للمشاريع القديمة.
- التثبيت الأدنى
- التثبيت الكامل
تثبّت الإعدادات التالية جميع صور TeX Live Docker الكاملة من 2025 إلى 2026. نوصي بتوفر مساحة تخزين متاحة لا تقل عن 64 GB قبل استخدام هذه الإعدادات.
config/variables.env
يُوصى بشدة بتعيين صورتين على الأقل من texlive-full. لمعرفة السبب بالتفصيل، راجع #known-issues
صور TeX Live المتاحة
هذه سلسلة من صور TeX Live المحسّنة خصيصًا لـ Overleaf، ويمكن أيضًا إضافتها إلىTEX_LIVE_DOCKER_IMAGE وALL_TEX_LIVE_DOCKER_IMAGES:
ghcr.io/ayaka-notes/texlive-full:2026.1(وتحمل أيضًا الوسمlatest)ghcr.io/ayaka-notes/texlive-full:2025.1ghcr.io/ayaka-notes/texlive-full:2024.1ghcr.io/ayaka-notes/texlive-full:2023.1ghcr.io/ayaka-notes/texlive-full:2022.1ghcr.io/ayaka-notes/texlive-full:2021.1ghcr.io/ayaka-notes/texlive-full:2020.1
هل يمكنني استخدام سجل صور آخر؟
قد يتساءل بعض الناس: هل يمكنني استبدال ghcr.io بموقع مرآة آخر، أو التبديل إلى صورة texlive أخرى من Docker Hub؟
لا، لا نوصي بذلك لأن الإعداد معقد نسبيًا. فإذا كنت تنزّل من موقع مرآة، فيمكنك إعادة تسمية صورتك إلى ghcr.io/ayaka-notes/texlive-full.
لكن إذا كنت تريد حقًا استخدام سجل الصور (Image Registry) الخاص بك، فيُرجى إضافة:
config/variables.env
your-repo، مثل
hub.your.com/your-repo/texlive-full:2025.1hub.your.com/your-repo/texlive-full:2024.1
sandboxed-compiles/index.mjs
المزامنة التلقائية لصور TeX Live
لتجنّب التحديث اليدوي للمثيل باستخدامbin/up في كل مرة، يمكنك أتمتة تحديثات صورة TeX Live. راجع updating-tex-live-full-images-automatically.md.
المشكلات المعروفة
هذه حالة حقيقية من مجتمع Overleaf:أستخدم6.0.1-ext-v3.3، ولدي هذه الإعدادات فيvariables.env:يعمل هذا بشكل جيد معtexlive/texlive:latest-full. لكنني سحبت صورة texlive أخرىdanteev/texlive:2025-10-15وغيّرت كلا المتغيرين إلى اسم الصورة الجديدة، إلا أن ذلك لم ينجح:وفي السجلات، أرى ما يلي:
يبدو أن الإعدادات المحدّثة فيبسبب بعض القيود التقنية، إذا أعددت صورة Docker واحدة فقط لـ TeXLive، مثلvariables.envلا تسري. فلا تزال عملية الترجمة تحاول تشغيل الصورةtexlive/texlive:latest-full، لا الصورة الجديدة. جرّبت إعادة التشغيل، وحذف الحاويات وإعادة تشغيلها، لكن المشكلة نفسها ما زالت قائمة. هل من حلول؟
texlive-fullA:latest
texlive-fullB:latest. عندها سترى أن مستخدميك عاجزون عن ترجمة جميع المشاريع.
التصحيح والإبلاغ
شغّل الأمر التالي للتحقق من سجل clsi عبر toolkit:أسئلة وأجوبة
هل تُزال حاويات العزل وملفات الترجمة وصور TeX Live تلقائيًا؟
هل تُزال حاويات العزل وملفات الترجمة وصور TeX Live تلقائيًا؟
الإجابة: تُزال الحاويات وملفات الترجمة بعد مهلة زمنية؛ أما صور TeX Live فلا تُزال.
- حاويات الترجمة (
project-<project id>-<hash>) يُعاد استخدامها عبر عمليات ترجمة المشروع نفسه، لذا تبقى بعد الترجمة. يجري فحص كل ساعة ويزيل الحاويات التي يزيد عمرها على ساعة واحدة ولم يُترجم مشروعها خلال الساعة الأخيرة. تختفي الحاوية عادةً بعد ساعة إلى ساعتين من آخر ترجمة. لا تؤدي إعادة تشغيل Overleaf إلى إزالتها؛ بل يزيلها الفحص الدوري التالي. - حاويات عدّ الكلمات وSyncTeX والتحويل تُزال فور انتهائها.
- ملفات الترجمة (
data/overleaf/data/compilesوoutput) تُزال بعد مرور يوم واحد على عدم استخدام المشروع، ويُجرى الفحص كل 10 دقائق. عندما تنخفض المساحة المتاحة على القرص، تُقصَّر هذه المدة تدريجيًا حتى نصف يوم. - صور TeX Live لا تُزال أبدًا، لأن كل عملية ترجمة تحتاج إليها. لتحرير المساحة بعد إزالة صورة من
ALL_TEX_LIVE_DOCKER_IMAGES، احذفها باستخدامdocker image rm <image>.
هل يمكن لمشروع قراءة ملفات من مجلد على المضيف أو على NAS؟
هل يمكن لمشروع قراءة ملفات من مجلد على المضيف أو على NAS؟
الإجابة: لا. تركّب كل حاوية ترجمة مجلد الترجمة الخاص بمشروعها فقط، في
/compile، وليس لديها اتصال بالشبكة، ولا يوجد إعداد لتركيب مجلدات أخرى من المضيف فيها. بدلًا من ذلك، ارفع الملفات التي يحتاجها المشروع إلى المشروع نفسه.هل توجد صورة TeX Live أساسية (basic)، وكيف أُعِدّها؟
هل توجد صورة TeX Live أساسية (basic)، وكيف أُعِدّها؟
الإجابة: نعم. تحتوي الصورة الصورة
ghcr.io/ayaka-notes/texlive-basic:<year>.1 (من 2020.1 إلى 2026.1) على مخطط TeX Live الأساسي (basic scheme) بالإضافة إلى بضع حزم مثل latexmk وxetex وfontspec، من دون مجموعة الخطوط الكاملة. وهي أصغر بكثير من texlive-full، لكن المشاريع التي تستخدم حزمًا أخرى ستواجه أخطاء الحزم المفقودة. بالنسبة إلى TeX Live 2025 basic:config/variables.env
ghcr.io/ayaka-notes/texlive-full:base ليست صورة أساسية: فهي لا تحتوي على TeX Live ولا يمكنها الترجمة.أين يمكنني معرفة المدة التي استغرقتها الترجمة؟
أين يمكنني معرفة المدة التي استغرقتها الترجمة؟
الإجابة: لا يعرضها المحرر، ولا يسجّلها سجل
clsi إلا على مستوى debug. لكن كل طلب ترجمة يعيدها: افتح أدوات المطوّر في المتصفح، وانتقل إلى علامة التبويب Network، وأعد الترجمة، ثم اختر الطلب compile. تحتوي استجابته بصيغة JSON على timings بالمللي ثانية، حيث يمثل compileE2E عملية الترجمة كاملة في خدمة الترجمة، ويمثل compile تشغيل LaTeX نفسه.
