(ترحيل v5.5.7) ترحيل الملفات الثنائية

​

ترحيل الملفات الثنائية

سيُخفّض الإصدار الرئيسي القادم 6.0 من Server Pro و Community Edition مساحة التخزين التي تستهلكها الملفات الثنائية إلى النصف. ويتضمن الإصدار 5.5.7 ترحيلًا عبر الإنترنت (online)، مما يتيح تقليل وقت التوقف إلى الحد الأدنى كجزء من الترقية.

منذ Server Pro 4.x، تُخزَّن الملفات الثنائية مرتين: في تخزين الملفات النشطة في “filestore” وفي نظام السجل الكامل للمشاريع. ومن الآن فصاعدًا، ستُخزَّن نسخة واحدة من كل ملف في نظام السجل الكامل للمشاريع.

يتكوّن الترحيل إلى نظام التخزين الموحّد من جزأين: علامة جديدة للتحكم في مرحلة الترحيل، وسكربت يعالج جميع المشاريع النشطة والمحذوفة حذفًا مؤقتًا.

المراحل:

• OVERLEAF_FILESTORE_MIGRATION_LEVEL=0 (الافتراضي)، تُقرأ الملفات من filestore وتُكتب إليه. وتُكتب الملفات إلى السجل بشكل غير متزامن.
• OVERLEAF_FILESTORE_MIGRATION_LEVEL=1، تُقرأ الملفات من السجل مع الرجوع إلى filestore عند الحاجة، وتُكتب إلى كل من filestore والسجل. ويمكن الرجوع إلى OVERLEAF_FILESTORE_MIGRATION_LEVEL=0.
• OVERLEAF_FILESTORE_MIGRATION_LEVEL=2، تُقرأ الملفات من السجل وتُكتب إليه فقط. ولا يمكن الرجوع إلى OVERLEAF_FILESTORE_MIGRATION_LEVEL=1 إلا إذا أُجري الترحيل “دون اتصال” (offline).

عند تخزين البيانات في S3 واستخدام حسابات خدمة منفصلة لـ filestore (OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID) وللسجل (OVERLEAF_HISTORY_S3_ACCESS_KEY_ID): يُرجى منح مستخدم filestore صلاحية القراءة على حاوية (bucket) السجل الخاصة بـ blobs OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET. إذ ستتولى خدمة filestore من الآن فصاعدًا تلبية طلبات القراءة الواردة من خدمة الترجمة.

يوصى بشدة بإجراء ترحيل الملفات الثنائية في بيئة غير إنتاجية/بيئة اختبار أولًا.

يتيح لك ترخيص Server Pro القياسي تشغيل التطبيق في بيئة إنتاجية وكذلك في بيئة غير إنتاجية/بيئة اختبار؛ ويوصى بشدة بتجهيز بيئة غير إنتاجية للاختبار.

إذا قمت بالترقية إلى Server Pro/CE الإصدار 6.0 ثم قررت لاحقًا الرجوع إلى إصدار أقدم، فيجب عليك الاستعادة من نسخة احتياطية كاملة للنظام.

​

إجراءات الترحيل

1. إنشاء نسخة احتياطية

   أنشئ نسخة احتياطية كاملة من نسختك مع لقطة متسقة لمجلدات mongo و redis و sharelatex.

2. التحديث

   Toolkit: استخدم السكربت $ bin/upgrade لترقية toolkit إلى أحدث إصدار. وعندما يُطلب منك ذلك، لا تؤكد المطالبة Upgrade image? — بل عدّل الملف config/version يدويًا واضبط قيمته على 5.5.7.

   ملف docker-compose.yml القديم: حدّث إصدار الخدمة sharelatex إلى 5.5.7.

3. تقدير عدد المشاريع المتأثرة

   # Overleaf Toolkit users:
   $ bin/docker-compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --report"
   
   # Legacy docker-compose.yml users:
   $ docker compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --report"
   

   مثال على المخرجات:

   Current status:
   - Total number of projects: 10
   - Total number of deleted projects: 5
   Sampling 1000 projects to estimate progress...
   Sampled stats for projects:
   - Sampled projects: 9 (90% of all projects)
   - Sampled projects with all hashes present: 5
   - Percentage of projects that need back-filling hashes: 44% (estimated)
   - Sampled projects have 11 files that need to be checked against the full project history system.
   - Sampled projects have 3 files that need to be uploaded to the full project history system (estimating 27% of all files).
   Sampled stats for deleted projects:
   - Sampled deleted projects: 4 (80% of all deleted projects)
   - Sampled deleted projects with all hashes present: 3
   - Percentage of deleted projects that need back-filling hashes: 25% (estimated)
   - Sampled deleted projects have 2 files that need to be checked against the full project history system.
   - Sampled deleted projects have 1 files that need to be uploaded to the full project history system (estimating 50% of all files).
   
4. تفريغ قوائم انتظار سجل المشاريع

   # Overleaf Toolkit users:
   $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues
   
   # Legacy docker-compose.yml users:
   $ docker compose exec sharelatex /overleaf/bin/flush-history-queues
   

   كرّر التفريغ حتى يتم تفريغ جميع المشاريع ("project_ids":0).

   found projects {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"}
   total {"succeededProjects":0,"failedProjects":0}
   

   إذا لم تكن قيمة “failedProjects” صفرًا، فيُرجى التواصل مع الدعم وعدم متابعة ترحيل الملفات الثنائية.

5. تقديم مرحلة الترحيل إلى 1

   Toolkit: اضبط OVERLEAF_FILESTORE_MIGRATION_LEVEL=1 في config/variables.env.

   ملف docker-compose.yml القديم: اضبط OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1' في قسم environment الخاص بالخدمة sharelatex.

6. تطبيق تغيير الإعداد وتشغيل النسخة

   Toolkit: bin/up -d

   ملف docker-compose.yml القديم: docker compose up -d

7. التحقق من الوصول إلى الملفات الثنائية

   افتح مشروعًا في محرر Overleaf في المتصفح واختر ملفًا ثنائيًا، مثل صورة.

8. تشغيل سكربت الترحيل

   # Overleaf Toolkit users:
   $ bin/docker-compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --all"
   
   # Legacy docker-compose.yml users:
   $ docker compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --all"
   

   إذا كنت تحتفظ بملفات السجلات خارج الحاوية sharelatex، فتأكد من أن مالك مجلد السجلات هو المستخدم www-data (uid=33) حتى يمكن كتابة ملف السجل الناتج.

   يُفترض أن تبدو المخرجات على هذا النحو:

   Set UV_THREADPOOL_SIZE=16
   {"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"Loading backend","time":"2025-07-25T15:00:58.166Z","v":0}
   Writing logs into /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log
   Starting project file backup...
   Loaded global blobs: 0
   Processing non-deleted projects...
   Processed 1 projects, elapsed time 0s
   Done updating live projects
   Processing deleted projects...
   The collection deletedProjects appears to be empty.
   
   Done updating deleted projects
   Done.
   
   

   إذا نجح الترحيل، فستحصل على رمز خروج 0، وستشير الأسطر الأخيرة إلى عدم وجود أي إخفاقات:

   Done.
   

   سيبدو ملف السجل على هذا النحو (استخدم المسار كما يطبعه السكربت):

   $ docker cp sharelatex:/var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log .
   $ cat file-migration-2025-07-25T15_00_58_199Z.log
   {"name":"file-migration","hostname":"c25e9faaeb53","pid":971,"level":30,"end":"68839a8f577b9f009d947b27 (2025-07-25T14:54:07.000Z)","msg":"actually completed batch","time":"2025-07-25T15:00:58.379Z","v":0}
   {"name":"file-migration","hostname":"c25e9faaeb53","pid":971,"level":30,"time":"2025-07-25T15:00:58.383Z","LOGGING_IDENTIFIER":"4effa2000000000000000000","projects":1,"blobs":6,"filesWithHash":5,"filesWithoutHash":2,"filesDuplicated":0,"filesRetries":0,"filesFailed":0,"fileTreeUpdated":0,"badFileTrees":0,"globalBlobsCount":0,"globalBlobsEgress":0,"projectDeleted":0,"projectHardDeleted":0,"fileHardDeleted":0,"mongoUpdates":1,"readFromGCSCount":7,"readFromGCSIngress":28532,"writeToGCSCount":5,"writeToGCSEgress":300,"readFromGCSThroughputMiBPerSecond":0.14925639825786063,"eventLoop":{"idle":48.277844,"active":381.53244699971054,"utilization":0.8876763888372498},"diff":{"eventLoop":{"idle":48.223536,"active":134.04030200059555,"utilization":0.7354190687027976},"projects":1,"blobs":6,"filesWithHash":5,"filesWithoutHash":2,"filesDuplicated":0,"filesRetries":0,"filesFailed":0,"fileTreeUpdated":0,"badFileTrees":0,"globalBlobsCount":0,"globalBlobsEgress":0,"projectDeleted":0,"projectHardDeleted":0,"fileHardDeleted":0,"mongoUpdates":1,"readFromGCSCount":7,"readFromGCSIngress":28532,"writeToGCSCount":5,"writeToGCSEgress":300,"readFromGCSThroughputMiBPerSecond":0.14925639825786063},"deferredBatches":[],"msg":"file-migration stats","v":0}
   
9. إيقاف النسخة

   Toolkit: bin/stop sharelatex

   ملف docker-compose.yml القديم: docker compose stop sharelatex

10. جعل الملفات القديمة غير قابلة للوصول من التطبيق

    يمكنك الآن نقل الملفات القديمة إلى تخزين ثانوي. ونوصي بالاحتفاظ بالملفات لبعض الوقت تحسبًا لظهور مشكلات لاحقًا.

    # Toolkit users:
    $ bin/docker-compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files
    
    # Legacy docker-compose.yml users:
    # We are assuming that you are using the default bind-mount in /var/lib/overleaf
    $ docker compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files
    # In case you are using selective bind-mounts, you can simply remove the bind-mount for /var/lib/overleaf/data/user_files inside the container.
    
11. تقديم مرحلة الترحيل إلى 2

    Toolkit: اضبط OVERLEAF_FILESTORE_MIGRATION_LEVEL=2 في config/variables.env.

    ملف docker-compose.yml القديم: اضبط OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2' في قسم environment الخاص بالخدمة sharelatex.

12. تطبيق تغيير الإعداد وتشغيل النسخة

    Toolkit: bin/up -d

    ملف docker-compose.yml القديم: docker compose up -d

13. التحقق من الوصول إلى الملفات الثنائية

    افتح مشروعًا في محرر Overleaf في المتصفح واختر ملفًا ثنائيًا، مثل صورة.

​

الترحيل دون اتصال (Offline)

إذا كنت تريد منع المستخدمين من تسجيل الدخول أثناء تشغيل سكربت ترحيل الملفات الثنائية، فيُرجى اتباع الخطوات التالية:

• سجّل الدخول إلى نسخة Overleaf بحساب مسؤول
• انقر على زر Admin واختر Manage Site
• انقر على علامة التبويب Open/Close Editor
• انقر على زر Close Editor
• انقر على زر Disconnect all users

بعد القيام بذلك، سيُعاد توجيه أي مستخدمين مسجلين دخولهم إلى صفحة الصيانة، وسيرى أي مستخدمين جدد يزورون صفحة تسجيل الدخول صفحة الصيانة ولن يتمكنوا من تسجيل الدخول.

عليك تكرار هذه الخطوات عند إعادة تشغيل النسخة. ولإعادة فتح الموقع، ما عليك سوى إعادة تشغيل النسخة.

​

الترحيل عبر الإنترنت (Online)

من الممكن تشغيل سكربتات الترحيل بينما لا يزال التطبيق قيد التشغيل. وهناك بعض الاعتبارات التي يجب مراعاتها:

• عملية الترحيل كثيفة الاستخدام لعمليات الإدخال/الإخراج (IO)، لذا يجب مراقبة استخدام الموارد أثناء تشغيل السكربت.
• مع درجة عالية من التزامن في المعالجة، قد تتعرض حلقة الأحداث (event loop) في خدمة filestore لبعض الحجب، مما قد يؤدي إلى تدهور تجربة المستخدم. ونوصي بالبدء بالقيم الافتراضية --concurrency=10 و --concurrent-batches=1.
• يمكنك إيقاف السكربت في أي وقت. وعند تشغيله مرة أخرى، سيتحقق من المشاريع السابقة ويتخطى الملفات التي عولجت بالفعل. وهذا مفيد إذا كنت تفضّل تشغيل الترحيل في ساعات أقل ازدحامًا (مثل الليل).

توصيتنا هي إغلاق الموقع وتشغيل الترحيل دون اتصال خلال نافذة صيانة عندما يكون عدد مشاريعك أقل من 1000 مشروع (راجع مخرجات سكربت الترحيل عند تشغيله مع --report). وإذا كان عدد المشاريع كبيرًا، فيمكنك تشغيل السكربت ومراقبة تقدمه، ثم تقرير ما إذا كنت ستواصل تشغيله عبر الإنترنت أو دون اتصال بناءً على حالتك الخاصة.

​

تنظيف بيانات الملفات الثنائية القديمة

عند الانتهاء من الترحيل والتحقق من أن المشاريع لا تزال قادرة على الوصول إلى جميع ملفاتها، يمكنك إزالة تخزين الملفات القديم في /var/lib/overleaf/data/user_files. ونوصي بشدة بالاحتفاظ بهذه الملفات لبعض الوقت — ويمكنك جعلها غير قابلة للوصول من التطبيق بإعادة تسمية المجلد أولًا.

​

استكشاف الأخطاء وإصلاحها

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

إذا فشل سكربت ترحيل الملفات الثنائية (أي خرج بخطأ أو طبع عددًا غير صفري من المشاريع الفاشلة)، فيُرجى إرسال التفاصيل التالية إلى فريق الدعم لدينا عبر البريد الإلكتروني [e-mail]، مع توضيح:

الموضوع: Binary file migration problem

نص الرسالة:

• نوع النسخة: CE أو Server Pro (احذف ما لا ينطبق)
• نوع التثبيت: Overleaf toolkit أو docker-compose.yml أو غير ذلك (احذف ما لا ينطبق)
• الإصدار: 5.5.x (في toolkit: $ cat config/version)
• مخرجات سكربت الترحيل (والتي يُفترض أن تكون موجودة في الحاوية ضمن /var/log/overleaf)
• التقرير: (شغّل سكربت الترحيل مع --report)
• المشاريع المعالجة: (وفقًا لآخر تشغيل للسكربت)
• مدة الترحيل:
• مخرجات bin/doctor (عند استخدام toolkit)
• إصدار Toolkit: $ git rev-parse HEAD (عند استخدام Toolkit)

يُستحسن إرفاق ملفات السجلات الخاصة بخدمة filestore بالرسالة. يمكنك العثور عليها في /var/log/overleaf/filestore.log داخل الحاوية sharelatex وتصديرها على هذا النحو:

$ docker cp sharelatex:/var/log/overleaf/filestore.log .
# replace <timestamp> with the timestamp as printed by the script
$ docker cp sharelatex:/var/log/overleaf/file-migration-<timestamp>.log .

يُرجى حجب أي معلومات حساسة من ملفات السجلات قبل إرفاقها.

​

الملفات المفقودة

كانت الإصدارات الأقدم من Server Pro/CE تنشئ إدخالات شجرة الملفات قبل انتهاء رفع المستخدم للملفات، مما قد يؤدي إلى ظهور الملفات كأنها مفقودة عند فشل الرفع. وقد تجد بعض هذه الحالات مُبلغًا عنها كأخطاء عند معالجة جميع أشجار الملفات.

إذا كان عدد الملفات المفقودة قليلًا، فيُستحسن مراجعة هذه الحالات يدويًا وحذفها من المحرر في المتصفح.

إذا كان عدد الملفات المفقودة كبيرًا، فيُستحسن التواصل مع الدعم، راجع قالب البريد الإلكتروني أعلاه.

​

العثور على أشجار الملفات التالفة

قد يفشل الترحيل للمشاريع التي تحتوي على شجرة ملفات مشوّهة (على سبيل المثال، حيث تكون أسماء الملفات فارغة). يمكنك العثور على قائمة بهذه المشكلات باستخدام السكربت find_malformed_filetrees الذي يفحص جميع المشاريع في قاعدة البيانات:

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web && /sbin/setuser www-data node scripts/find_malformed_filetrees.mjs > /tmp/malformed-file-trees.json"

لإصلاح المسارات غير الصالحة، استخدم السكربت fix_malformed_filetree، مع تشغيل الأمر مرة واحدة لكل مسار تالف:

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web && /sbin/setuser www-data node scripts/fix_malformed_filetree.mjs --logs=/tmp/malformed-file-trees.json"