الترجمة المعزولة (Sandboxed Compiles)

ترجم LaTeX داخل حاويات TeX Live على عقد عنقود Kubernetes.

تُجري خدمة clsi عمليات الترجمة داخل كل pod من Ayakaleaf Pro. عند تفعيل الترجمة المعزولة، تطلب clsi من Docker Engine الخاص بالعقدة التي يعمل عليها الـ pod تشغيل حاوية TeX Live لكل عملية ترجمة، وتسلّمها مجلد المشروع عبر مساره على تلك العقدة. آلية العزل والصور المتوفرة موضّحة في الترجمة المعزولة (Sandboxed Compiles).

الخدمة	clsi (عمليات الترجمة)، وweb (قائمة الصور في إعدادات المترجم)، في كل pod من Ayakaleaf Pro
العقدة	Docker Engine وكل صورة من صور ALL_TEX_LIVE_DOCKER_IMAGES، على كل عقدة يمكنها تشغيل Ayakaleaf Pro
عمليات التركيب في الـ pod	/var/run/docker.sock، ومجلدات الترجمة والمخرجات وذاكرة التخزين المؤقت على هيئة وحدات تخزين hostPath
المهام الدورية	تحذف clsi مجلدات الترجمة التي لم تُستخدم منذ يوم، وتُزيل كل ساعة حاويات TeX Live القديمة من Docker على العقدة

​

الإعداد

يُعدّ التثبيت كل شيء: Docker والصور على العقد في 0. تجهيز العقد، والإعدادات في 4. تخصيص المثيل الخاص بك، ووحدات التخزين في 5. نشر Ayakaleaf Pro. الإعدادات، وكلها في الـ ConfigMap:

المتغيّر	القيمة
SANDBOXED_COMPILES، SANDBOXED_COMPILES_SIBLING_CONTAINERS، DOCKER_RUNNER	"true"
SANDBOXED_COMPILES_HOST_DIR_COMPILES	مسار وحدة التخزين على العقدة، والمُركّبة على /var/lib/overleaf/data/compiles
SANDBOXED_COMPILES_HOST_DIR_OUTPUT	مسار وحدة التخزين على العقدة، والمُركّبة على /var/lib/overleaf/data/output
SANDBOXED_COMPILES_HOST_DIR_CACHE	مسار وحدة التخزين على العقدة، والمُركّبة على /var/lib/overleaf/data/cache
ALL_TEX_LIVE_DOCKER_IMAGES، ALL_TEX_LIVE_DOCKER_IMAGE_NAMES، TEX_LIVE_DOCKER_IMAGE	الصور، كما في Toolkit

​

إضافة إصدار من TeX Live

1. اسحب الصورة على كل عقدة

   # on each node that can run Ayakaleaf Pro
   sudo docker pull ghcr.io/ayaka-notes/texlive-full:2025.1
   

   يسحب Toolkit الصور بنفسه؛ أما على Kubernetes فلا أحد يفعل ذلك. اسحبها إلى Docker، وليس باستخدام crictl: إذ تطلب clsi الصورة من Docker. وتفشل أي عملية ترجمة تستخدم صورة غير موجودة على العقدة.

2. أدرجها في الـ ConfigMap وأعد التشغيل

     ALL_TEX_LIVE_DOCKER_IMAGES: ghcr.io/ayaka-notes/texlive-full:2026.1,ghcr.io/ayaka-notes/texlive-full:2025.1
     ALL_TEX_LIVE_DOCKER_IMAGE_NAMES: TeX Live 2026,TeX Live 2025
     TEX_LIVE_DOCKER_IMAGE: ghcr.io/ayaka-notes/texlive-full:2026.1
   

   kubectl apply -f 30-config.yaml
   kubectl -n overleaf rollout restart deployment/overleaf     # or statefulset/overleaf
   

تحتاج أي عقدة تُضاف إلى العنقود لاحقًا إلى Docker وكل الصور قبل أن يعمل Ayakaleaf Pro عليها. ضع تسميات (labels) على هذه العقد وأبقِ Ayakaleaf Pro عليها باستخدام nodeSelector إذا لم تكن كل العقد مؤهلة.

​

عدة نسخ متماثلة

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

تعمل حاويات TeX Live بجانب الـ pod، خارج حدّ الذاكرة الخاص به وخارج نطاق رؤية المُجدوِل (scheduler). اترك ذاكرة متاحة على العقد من أجلها، راجع 0. تجهيز العقد.

​

الاختبار على Kubernetes

على Kubernetes 1.37 مع ثلاث نسخ متماثلة خلف HAProxy، واحدة لكل عقدة، ومع سحب TeX Live 2026 و2025 إلى Docker على كل عقدة، تنجح اختباراتنا الشاملة (end-to-end) للترجمة المعزولة (7 حالات): ترجمة مشروع جديد إلى PDF، وعرض إعدادات المترجم لكلتا الصورتين والتبديل بينهما، وXeLaTeX مع fontspec، وأخطاء LaTeX وإعادة الترجمة بعد الإصلاح، وإيقاف عملية ترجمة جارية، وSyncTeX في كلا الاتجاهين. وقد أجرى اختبار تحميل يضم 12 مستخدمًا يترجمون مستندًا من 600 صفحة في الوقت نفسه 4 عمليات ترجمة لكل عقدة، راجع ما الذي يمكن توقّعه.