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

يأتي Ayakaleaf Pro مع خيار تشغيل عمليات الترجمة في بيئة معزولة وآمنة (sandbox) لتحقيق أمان على مستوى المؤسسات. ويتم ذلك عبر تشغيل كل مشروع في بيئة Docker آمنة خاصة به.

​

أمان محسّن

تُعد الترجمة المعزولة النهج الموصى به لـ Ayakaleaf Pro، نظرًا لأن كثيرًا من مستندات LaTeX تتطلب تنفيذ أوامر صدفة (shell) عشوائية أو تملك القدرة على ذلك كجزء من عملية ترجمة PDF. فإذا استخدمت الترجمة المعزولة، فإن كل عملية ترجمة تعمل في حاوية Docker منفصلة ذات قدرات محدودة لا تشاركها مع أي مستخدم أو مشروع آخر، ولا تملك أي وصول إلى الموارد الخارجية مثل شبكة المضيف.

إذا حاولت تشغيل Ayakaleaf Pro دون الترجمة المعزولة، فإن عملية الترجمة تعمل إلى جانب عمليات الترجمة المتزامنة الأخرى داخل حاوية Docker الرئيسية، ويحصل المستخدمون على صلاحيات قراءة وكتابة كاملة على موارد الحاوية sharelatex (نظام الملفات والشبكة ومتغيرات البيئة) عند تشغيل عمليات ترجمة LaTeX.

​

إدارة أسهل للحزم

لتجنّب تثبيت الحزم يدويًا، نوصي بتفعيل الترجمة المعزولة. وهو إعداد قابل للتهيئة في Server Pro يوفر لمستخدميك الوصول إلى بيئة TeX Live نفسها الموجودة على overleaf.com ولكن داخل تثبيتك المحلي. وتحتوي صور TeX Live التي تستخدمها الترجمة المعزولة على أكثر الحزم والخطوط شيوعًا والتي اختُبرت مع قوالب معرضنا، مما يضمن أقصى قدر من التوافق مع المشاريع المحلية.

يتيح لك تفعيل الترجمة المعزولة تحديد إصدارات TeX Live التي يمكن للمستخدمين الاختيار منها داخل مشاريعهم، إلى جانب تعيين إصدار افتراضي لصورة TeX Live للمشاريع الجديدة.

إذا حاولت تشغيل Ayakaleaf Pro دون الترجمة المعزولة، فسيستخدم المثيل افتراضيًا إصدارًا من TeX Live بالمخطط الأساسي (basic scheme) لعمليات الترجمة. وهذا الإصدار الأساسي خفيف ولا يحتوي إلا على مجموعة فرعية محدودة جدًا من حزم LaTeX، مما سيؤدي على الأرجح إلى أخطاء حزم مفقودة لدى مستخدميك، خاصةً إذا حاولوا استخدام قوالب جاهزة.

بما أن Ayakaleaf Pro قد صُمّم للعمل دون اتصال بالإنترنت، فلا توجد طريقة مؤتمتة لدمج قوالب معرض overleaf.com في تثبيتك المحلي؛ لكن يمكن فعل ذلك يدويًا لكل قالب على حدة. لمزيد من المعلومات حول كيفية ذلك، يُرجى الاطلاع على دليلنا لنقل القوالب من overleaf.com: #transferring-templates-from-overleaf.com.

تتطلب الترجمة المعزولة أن يكون للحاوية 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

SERVER_PRO=true
SIBLING_CONTAINERS_ENABLED=true

​

لمستخدمي Docker Compose

بدءًا من Overleaf CE/Server Pro 5.0.3، تغيّرت تسمية متغيرات البيئة من SHARELATEX_* إلى OVERLEAF_*.

إذا كنت تستخدم إصدارًا من السلسلة 4.x (أو أقدم)، فيُرجى التأكد من أن المتغيرات تحمل البادئة المناسبة (مثل SHARELATEX_MONGO_URL بدلًا من OVERLEAF_MONGO_URL).

version: '2'
services:
    sharelatex:
        #...
        volumes:
            - /data/overleaf_data:/var/lib/overleaf
            - /var/run/docker.sock:/var/run/docker.sock
        environment:
            #...
            DOCKER_RUNNER: "true"
            SANDBOXED_COMPILES: "true"
            SANDBOXED_COMPILES_HOST_DIR: "/data/overleaf_data/data/compiles"
            #...
        #...

​

إعداد صورة TexLive

بالنسبة للمستخدمين في البر الرئيسي للصين، يمكنكم استبدال ghcr.io بـ ghcr.nju.edu.cn لتسريع التنزيل. لكن لا تستخدموا ghcr.nju.edu.cn مباشرةً في إعدادات البيئة الخاصة بـ toolkit. بل يجب الإبقاء على ghcr.io كخيار وحيد.

يستخدم Ayakaleaf Pro ثلاثة متغيرات بيئة لتحديد صور TeX Live المستخدمة في الترجمة المعزولة:

• TEX_LIVE_DOCKER_IMAGE (مطلوب)، صورة TeX Live الافتراضية المستخدمة لترجمة المشاريع الجديدة. ويجب أن تكون هذه الصورة مُدرجة في ALL_TEX_LIVE_DOCKER_IMAGES.
• ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (مطلوب)، قائمة مفصولة بفواصل بأسماء ودية للصور، تُستخدم في خيارات الواجهة الأمامية.
• ALL_TEX_LIVE_DOCKER_IMAGES (مطلوب)، قائمة مفصولة بفواصل بصور TeX Live المراد استخدامها. وإذا استُخدمت Overleaf Toolkit للنشر، فستُنزَّل هذه الصور أو تُحدَّث. ولتخطي التنزيل، اضبط SIBLING_CONTAINERS_PULL=false في config/overleaf.rc.

عند بدء تشغيل مثيل Ayakaleaf Pro باستخدام الأمر bin/up، ستسحب Toolkit تلقائيًا جميع الصور المدرجة في ALL_TEX_LIVE_DOCKER_IMAGES.

إليك مثالًا نستخدم فيه TeX Live 2026 افتراضيًا للمشاريع الجديدة، ونُبقي على 2025 للمشاريع القديمة.

التثبيت الأدنى

تثبّت الإعدادات التالية جميع صور TeX Live Docker الكاملة من 2025 إلى 2026. نوصي بتوفر مساحة تخزين متاحة لا تقل عن 64 GB قبل استخدام هذه الإعدادات.

config/variables.env

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=Texlive 2026, Texlive 2025
TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2026.1

التثبيت الكامل

تثبّت الإعدادات التالية جميع صور TeX Live Docker الكاملة من 2020 إلى 2026. نوصي بتوفر مساحة تخزين متاحة لا تقل عن 150 GB قبل استخدام هذه الإعدادات.

config/variables.env

ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2026.1,ghcr.io/ayaka-notes/texlive-full:2025.1,ghcr.io/ayaka-notes/texlive-full:2024.1,ghcr.io/ayaka-notes/texlive-full:2023.1,ghcr.io/ayaka-notes/texlive-full:2022.1,ghcr.io/ayaka-notes/texlive-full:2021.1,ghcr.io/ayaka-notes/texlive-full:2020.1
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2026,Texlive 2025,Texlive 2024,Texlive 2023,Texlive 2022,Texlive 2021,Texlive 2020
TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2026.1

يُوصى بشدة بتعيين صورتين على الأقل من 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.1
• ghcr.io/ayaka-notes/texlive-full:2024.1
• ghcr.io/ayaka-notes/texlive-full:2023.1
• ghcr.io/ayaka-notes/texlive-full:2022.1
• ghcr.io/ayaka-notes/texlive-full:2021.1
• ghcr.io/ayaka-notes/texlive-full:2020.1

هناك مخطط صارم يحدد كيف يجب أن توسم الصور (يُطبَّق التعبير النمطي ^[0-9]+.[0-9]+، حيث يحدد الرقم الأول سنة TeX Live والثاني إصدار التصحيح).

​

هل يمكنني استخدام سجل صور آخر؟

قد يتساءل بعض الناس: هل يمكنني استبدال ghcr.io بموقع مرآة آخر، أو التبديل إلى صورة texlive أخرى من Docker Hub؟

لا، لا نوصي بذلك لأن الإعداد معقد نسبيًا. فإذا كنت تنزّل من موقع مرآة، فيمكنك إعادة تسمية صورتك إلى ghcr.io/ayaka-notes/texlive-full.

لكن إذا كنت تريد حقًا استخدام سجل الصور (Image Registry) الخاص بك، فيُرجى إضافة:

config/variables.env

IMAGE_ROOT=hub.your.com/your-repo

بعد ذلك، عليك التأكد من أن جميع صور texlive موجودة في your-repo، مثل

• hub.your.com/your-repo/texlive-full:2025.1
• hub.your.com/your-repo/texlive-full:2024.1

للاطلاع على معلومات مفصلة، اقرأ الشيفرة المصدرية أدناه لفهم كيفية تحليلنا لمتغيرات البيئة الخاصة بك:

sandboxed-compiles/index.mjs

if (process.env.SANDBOXED_COMPILES === 'true') {
  // Set default image root if not provided
  let imageRootPath = process.env.IMAGE_ROOT || "ghcr.io/ayaka-notes";
  // Export imageRoot to Settings
  Settings.imageRoot = imageRootPath

  // allowedImageNames should be:
  // [
  //  { imageName: "texlive-2023:latest", imageDesc: "TeX Live 2023" },
  //  { imageName: "texlive-2022:latest", imageDesc: "TeX Live 2022" },
  // ]
  Settings.allowedImageNames = parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGES)
    .map((texImage, index) => ({
      imageName: texImage.split("/")[texImage.split("/").length - 1],
      imageDesc: parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGE_NAMES)[index]
        || texImage.split(':')[1],
    }))
  
  // In the end, imageName will be put together with imageRoot to form the full image path
  // The full name will be like: ghcr.io/ayaka-notes/texlive-2023:latest

  // Set default image name if not provided
  if(!process.env.TEX_LIVE_DOCKER_IMAGE) {
    process.env.TEX_LIVE_DOCKER_IMAGE = imageRootPath + "/" + Settings.allowedImageNames[0].imageName
  }

  // Export currentImageName to Settings
  // This is the new created projects' image name
  Settings.currentImageName = process.env.TEX_LIVE_DOCKER_IMAGE
}

​

المزامنة التلقائية لصور TeX Live

لتجنّب التحديث اليدوي للمثيل باستخدام bin/up في كل مرة، يمكنك أتمتة تحديثات صورة TeX Live. راجع updating-tex-live-full-images-automatically.md.

​

المشكلات المعروفة

هذه حالة حقيقية من مجتمع Overleaf:

أستخدم 6.0.1-ext-v3.3، ولدي هذه الإعدادات في variables.env:

TEX_LIVE_DOCKER_IMAGE=texlive/texlive:latest-full
ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full

يعمل هذا بشكل جيد مع texlive/texlive:latest-full. لكنني سحبت صورة texlive أخرى danteev/texlive:2025-10-15 وغيّرت كلا المتغيرين إلى اسم الصورة الجديدة، إلا أن ذلك لم ينجح:

TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15
ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15

وفي السجلات، أرى ما يلي:

{"name":"clsi","level":50,"err":{"message":"(HTTP code 404) no such container - No such image: texlive/texlive:latest-full ","name":"Error","stack":"Error: (HTTP code 404) no such container - No such image: texlive/texlive:latest-full ... 

يبدو أن الإعدادات المحدّثة في variables.env لا تسري. فلا تزال عملية الترجمة تحاول تشغيل الصورة texlive/texlive:latest-full، لا الصورة الجديدة.

جرّبت إعادة التشغيل، وحذف الحاويات وإعادة تشغيلها، لكن المشكلة نفسها ما زالت قائمة.

هل من حلول؟

بسبب بعض القيود التقنية، إذا أعددت صورة Docker واحدة فقط لـ TeXLive، مثل texlive-fullA:latest

ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA
TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full

ثم بعد تشغيل مثيل Overleaf لفترة، قد ترغب في تعديل صورة TeXLive إلى texlive-fullB:latest. عندها سترى أن مستخدميك عاجزون عن ترجمة جميع المشاريع.

ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA
TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full

ويرجع ذلك إلى أن اسم صورة TeXLive-Full (المستخدمة في الترجمة المعزولة) لكل مشروع محفوظ في قاعدة البيانات. ولا يتغير اسم الصورة في قاعدة البيانات إلا عندما يبدّل المستخدم إصدار TeXLive لمشروعه، مثلًا من 2024 إلى 2025.

عندما يترجم CLSI مشروعًا، فإنه يستخدم اسم صورة الحاوية الموجود في قاعدة البيانات لترجمة المشروع مباشرةً.

إذا وفّرت صورة Docker واحدة فقط، فلن يتمكن المستخدمون من تعديل الصورة المستخدمة لترجمة المشروع. وفي هذه الحالة، عليك كتابة سكربت لتعديل صورة TeXLive يدويًا لجميع مشاريع المستخدمين في mongoDB.

​

التصحيح والإبلاغ

شغّل الأمر التالي للتحقق من سجل clsi عبر toolkit:

bin/logs clsi

إذا واجهت أي مشكلات في الترجمة باستخدام صور TeX Live، فيُرجى إرسال مشكلة (issue) هنا:

https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml

ولمساعدتنا على إعادة إنتاج المشكلة واستكشافها وإصلاحها، قد يُطلب منك رفع مشروعك إلى Overleaf. وسنقوم بعد ذلك بسحب المشروع وإجراء اختبارات الترجمة باستخدام GitHub Action.