الانتقال إلى المحتوى الرئيسي
يدعم Ayakaleaf Pro التوسّع الأفقي. لقد اختبرنا وتحققنا من أنه يعمل بشكل صحيح مع نسخ متماثلة متعددة.
يسرد هذا المستند المتطلبات التقنية ويقدّم إرشادات لتشغيل Ayakaleaf Pro على أكثر من عقدة واحدة. يتطلب إعداد التوسّع الأفقي قدرًا كبيرًا من الجهد. ننصح بالتفكير في التوسّع الأفقي فقط عند الوصول إلى حجم معيّن. على سبيل المثال، أفاد Overleaf بأن تثبيتًا محليًا لـ 1,000 مستخدم إجمالًا يعمل بنجاح على خادم واحد مزوّد بمعالجين رباعيي النوى و32GB من ذاكرة النظام. راجع توثيق متطلبات العتاد للاطلاع على التوصيات. يتضمن نشر Ayakaleaf Pro مع التوسّع الأفقي مجموعة من المكوّنات الخارجية، مثل موازن الأحمال (Load Balancer) وواجهة تخزين خلفية متوافقة مع S3.

المتطلبات

تخزين بيانات مركزي خارجي

يمكن تقسيم تخزين البيانات في Ayakaleaf Pro إلى أربعة مخازن بيانات:
  • MongoDB
    • تُحفظ معظم البيانات في MongoDB.
    • ندعم إما نسخة محلية أو نسخة خارجية، مثل MongoDB Atlas (خدمة MongoDB مُدارة بالكامل تعمل ضمن البنية التحتية لـ AWS).
    ملاحظة: للأسف، لا يوجد دعم رسمي حاليًا لقواعد البيانات المتوافقة مع MongoDB مثل CosmoDB/DocumentDB، لأننا لم نختبر Ayakaleaf Pro معها. ومع أن نشر Ayakaleaf Pro مع قواعد بيانات متوافقة قد يكون ممكنًا، فإننا ندعم رسميًا فقط عمليات النشر التي تستخدم MongoDB.
  • Redis
    • يخزّن Redis البيانات المؤقتة، مثل تحديثات المستندات المعلّقة قبل تفريغها إلى MongoDB.
    • يُستخدم Redis لنقل تحديثات المستندات بين الخدمات المختلفة وإشعار المحرر بتغييرات الحالة في مشروع معيّن.
    • يُستخدم Redis لتخزين جلسات المستخدمين.
    • ندعم إما نسخة محلية أو نسخة خارجية.
    ملاحظة: للأسف، لا يوجد دعم رسمي حاليًا لمخازن المفاتيح/القيم المتوافقة مع Redis مثل KeyDB/Valkey، لأننا لم نختبر Ayakaleaf Pro معها. ومع أن نشر Ayakaleaf Pro مع مخازن متوافقة قد يكون ممكنًا، فإننا ندعم رسميًا فقط عمليات النشر التي تستخدم Redis.
  • ملفات المشاريع وملفات السجل
    • تُخزَّن ملفات المشاريع غير القابلة للتحرير خارج MongoDB. كما يخزّن نظام سجل المشاريع السجل خارج MongoDB أيضًا.
    • بالنسبة للنسخ المفردة الصغيرة، ندعم إما نظام ملفات محليًا (يمكن أن يعتمد على SSD محلي أو NFS أو EBS) أو نظام تخزين بيانات متوافقًا مع S3.
    • بالنسبة للتوسّع الأفقي، ندعم فقط أنظمة تخزين البيانات المتوافقة مع S3.
    مهم: أنظمة NFS/Amazon EFS/Amazon EBS غير مدعومة للتوسّع الأفقي. يرجى مراجعة قسم متطلبات تخزين العتاد حول توسيع التخزين في Ayakaleaf Pro لمزيد من التفاصيل.
  • الملفات المؤقتة
    • يجب أن تعمل عمليات ترجمة LaTeX على أقراص محلية سريعة للحصول على أفضل أداء. ولا يلزم حفظ ناتج الترجمة أو نسخه احتياطيًا.
    • كما يستفيد التخزين المؤقت لعمليات رفع الملفات الجديدة وإنشاء ملفات zip للمشاريع من استخدام قرص محلي.
ننصح بشدة باستخدام قرص محلي. قد يؤدي استخدام أي نوع من الأقراص الشبكية (مثل NFS أو EBS) إلى أخطاء ترجمة غير متوقعة ومشكلات أداء أخرى.

Git-bridge

تُخزَّن مستودعات git محليًا على القرص. ولا تتوفر خيارات للنسخ المتماثل. يجب تشغيل Git-bridge كنسخة مفردة (singleton). للحصول على أفضل أداء، ننصح باستخدام قرص محلي لبيانات git-bridge. ويجب نسخ قرص بيانات git-bridge احتياطيًا بانتظام. لتخزين البيانات مع التوسّع الأفقي، تحتاج إلى:
  • نسخة MongoDB مركزية يمكن الوصول إليها من جميع نسخ Ayakaleaf Pro
  • نسخة Redis مركزية يمكن الوصول إليها من جميع نسخ Ayakaleaf Pro
  • واجهة تخزين خلفية مركزية متوافقة مع S3 لملفات المشاريع والسجل
  • قرص محلي في كل نسخة للملفات المؤقتة
  • قرص محلي في النسخة التي تستضيف حاوية git-bridge لبيانات git-bridge

متطلبات موازن الأحمال

  • توجيه ثابت (Persistent routing)، مثلًا باستخدام ملف تعريف ارتباط (cookie) ينبع هذا المتطلب من المكوّنات التالية:
    • تستخدم إمكانية التحرير في الوقت الحقيقي في Ayakaleaf Pro تقنية WebSockets مع الرجوع إلى XHR polling كبديل. لكل جلسة تحرير حالة محلية على جانب الخادم، ويجب دائمًا توجيه طلبات جلسة تحرير معيّنة إلى نسخة Ayakaleaf Pro نفسها. وتستخدم ميزة التعاون آلية Pub/Sub في Redis لمشاركة التحديثات بين نسخ Ayakaleaf Pro المتعددة.
    • تحتفظ ترجمة LaTeX بالناتج وذاكرة الترجمة المؤقتة محليًا لتحسين الأداء. فعند إرسال طلب ترجمة إلى إحدى نسخ Ayakaleaf Pro، يجب توجيه طلبات تنزيل PDF/السجل اللاحقة إلى نسخة Ayakaleaf Pro نفسها.
  • مهلات طلبات طويلة لدعم ترجمة مستندات LaTeX الكبيرة
  • دعم WebSocket للحصول على أفضل أداء
  • حجم حمولة POST يبلغ 50MB
  • يجب أن تكون مهلة keep-alive أقل من مهلة keep-alive في Ayakaleaf Pro يمكن تهيئة مهلة keep-alive في Ayakaleaf Pro باستخدام متغير البيئة NGINX_KEEPALIVE_TIMEOUT. والقيمة الافتراضية هي 65s. مع القيمة الافتراضية، تعمل مهلة keep-alive بمقدار 60s في موازن الأحمال. مع NGINX_KEEPALIVE_TIMEOUT=120، يمكن لموازن الأحمال اختيار 115s.
  • عناوين IP للعملاء عيّن ترويسة الطلب X-Forwarded-For إلى عنوان IP الخاص بالعميل.
  • عند إنهاء SSL يجب على موازن الأحمال إضافة ترويسة الطلب X-Forwarded-Proto: https.

إعداد Ayakaleaf Pro

الأسرار يجب أن تتفق نسخ Ayakaleaf Pro على أسرار مشتركة:
  • WEB_API_PASSWORD (مصادقة web api)
  • STAGING_PASSWORD وV1_HISTORY_PASSWORD بالقيمة نفسها (مصادقة السجل)
  • CRYPTO_RANDOM (لملف تعريف ارتباط الجلسة)
  • OT_JWT_AUTH_KEY (مصادقة السجل)
  • OVERLEAF_INVITE_TOKEN_SECRET (رموز مشاركة الروابط، إلزامي: بدونه يرفض Ayakaleaf Pro بدء التشغيل)
يجب تهيئة كل من هذه الأسرار بقيمة فريدة خاصة بها، ومشاركتها بين النسخ. إذا لم تتم تهيئتها ووُجّهت طلبات المستخدمين إلى نسخ Ayakaleaf Pro مختلفة، فستفشل طلباتهم في فحوصات المصادقة، وإما أن تتم إعادة توجيههم إلى صفحة تسجيل الدخول بشكل متكرر أو تفشل إجراءاتهم في واجهة المستخدم بطرق غير متوقعة. إذا لم تتم تهيئتها، يستخدم Ayakaleaf Pro قيمة عشوائية جديدة لكل سر بناءً على 32 بايت عشوائيًا من /dev/urandom (256 بت عشوائيًا).
MongoDB وجّه OVERLEAF_MONGO_URL إلى نسخة MongoDB المركزية. Redis وجّه OVERLEAF_REDIS_HOST وREDIS_HOST إلى نسخة Redis المركزية. التخزين المتوافق مع S3 لملفات المشاريع والسجل يرجى مراجعة التوثيق الخاص بـ التخزين المتوافق مع S3 لمعرفة التفاصيل. الملفات المؤقتة سيكون الربط الافتراضي (bind-mount) لقرص SSD محلي إلى /var/lib/overleaf كافيًا. تأكد من توجيه SANDBOXED_COMPILES_HOST_DIR إلى نقطة الربط على المضيف.
ننصح بشدة باستخدام قرص محلي. قد يؤدي استخدام أي نوع من الأقراص الشبكية (مثل NFS أو EBS) إلى أخطاء ترجمة غير متوقعة ومشكلات أداء أخرى.
إعداد الوكيل (Proxy)
  • عيّن OVERLEAF_TRUSTED_PROXY_IPS إلى loopback مع عناوين IP الخاصة بموازنات الأحمال، مثل loopback,198.18.0.1، للحصول على عناوين IP دقيقة للعملاء. يمكن تحديد عدة عناوين IP أو نطاقات CIDR مفصولة بفاصلة.
تكامل Git-bridge تحتاج حاوية git-bridge إلى حاوية Ayakaleaf Pro شقيقة لمعالجة طلبات git الواردة. ويمكن لهذه الحاوية الشقيقة أن تخدم حركة مرور المستخدمين العادية أيضًا. في نموذج الإعداد، تعمل النسخة الأولى كحاوية شقيقة لـ git-bridge، لكن يمكن لأي نسخة أن تؤدي هذا الدور في الواقع. لماذا نحتاج إلى تخصيص حاوية Ayakaleaf Pro واحدة كحاوية شقيقة لـ git-bridge؟ يقدّم Ayakaleaf Pro إلى git-bridge روابط URL لتنزيل البيانات من خدمة السجل. ونحتاج إلى تهيئة روابط السجل هذه بحيث يمكن الوصول إليها من حاوية git-bridge. إعداد حاوية Ayakaleaf Pro:
  • عيّن GIT_BRIDGE_ENABLED إلى 'true'
  • عيّن GIT_BRIDGE_HOST إلى <git-bridge container name>، مثل git-bridge
  • عيّن GIT_BRIDGE_PORT إلى 8000
  • عيّن V1_HISTORY_URL إلى http://<server-pro sibling container name>:3100/api. ملاحظة: هذا ضروري فقط في الحاوية الشقيقة لحاوية git-bridge. ويمكن للنسخ الأخرى استخدام رابط localhost، وهو الافتراضي.
إعداد حاوية git-bridge:
  • عيّن GIT_BRIDGE_API_BASE_URL إلى http://<server-pro sibling container name>/api/v0، مثل http://server-pro-ha-1/api/v0
  • عيّن GIT_BRIDGE_OAUTH2_SERVER إلى http://<server-pro sibling container name>، مثل http://server-pro-ha-1
  • عيّن GIT_BRIDGE_POSTBACK_BASE_URL إلى http://<git-bridge container name>:8000، مثل http://git-bridge:8000
  • عيّن GIT_BRIDGE_ROOT_DIR إلى قرص بيانات git-bridge المربوط (bind-mounted)، مثل /data/git-bridge
يعرض الإعداد التالي بيئة قائمة بذاتها. لكي يعمل العرض التوضيحي، تحتاج إلى توفير مفتاح/شهادة SSL صالحة وتعديل OVERLEAF_SITE_URL. في الإعداد الفعلي، يجب استبدال الأسرار الوهمية بأسرار حقيقية كما هو موضح ضمن الشيفرة. وفي الإعداد الفعلي أيضًا، تحتاج إلى نقل الحاويات الفردية إلى عقد مخصصة وتعديل عناوين IP بما يتناسب مع إعداد شبكتك المحلية.تعمل عمليات الترجمة في حاويات TeX Live بجانب كل نسخة من Ayakaleaf Pro. اسحب صورة TeX Live على كل مضيف لـ Ayakaleaf Pro أولًا، على سبيل المثال docker pull ghcr.io/ayaka-notes/texlive-full:2026.1.

العتاد

نوصي باستخدام مواصفات العتاد نفسها لجميع نسخ Ayakaleaf Pro المشاركة في التوسّع الأفقي. تنطبق التوصيات العامة بشأن مواصفات العتاد على نسخ Ayakaleaf Pro.

ترقية Ayakaleaf Pro

كجزء من عملية الترقية، يشغّل Ayakaleaf Pro عمليات ترحيل قاعدة البيانات تلقائيًا. وهذه العمليات غير مصممة لتُشغَّل من نسخ متعددة بالتوازي. يجب أن تنتهي عمليات الترحيل قبل بدء تطبيق الويب الفعلي. يمكنك إما التحقق من السجلات بحثًا عن إدخال Finished migrations أو الانتظار حتى يبدأ التطبيق في قبول حركة المرور. تبدو إجراءات الترقية كما يلي:
  1. جدولة نافذة صيانة
  2. إيقاف جميع نسخ Ayakaleaf Pro
  3. أخذ نسخة احتياطية متسقة كما هو موضح في التوثيق
  4. تشغيل نسخة واحدة من Ayakaleaf Pro بالإصدار الجديد
  5. التحقق من أن النسخة الجديدة تعمل كما هو متوقع
  6. تشغيل النسخ الأخرى بالإصدار الجديد
آخر تعديل في ٢ نوفمبر ٢٠٢٦