> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/on-premises/ar/aldam/support-guides/v5.5.7-migration-binary-files-migration.md). # (ترحيل v5.5.7) ترحيل الملفات الثنائية ## ترحيل الملفات الثنائية الإصدار الرئيسي القادم `6.0` سيؤدي إصدار Server Pro وCommunity Edition القادم إلى تقليل استخدام التخزين للملفات الثنائية إلى النصف. ويتضمن ترحيلًا عبر الإنترنت في الإصدار `5.5.7` ، مما يتيح أقل قدر ممكن من التوقف كجزء من الترقية. منذ أن Server Pro `4.x`، يتم تخزين الملفات الثنائية مرتين: في مخزن الملفات النشطة في "filestore" وفي نظام سجلّ المشروع الكامل. ومن الآن فصاعدًا، سيتم تخزين نسخة واحدة من كل ملف في نظام سجلّ المشروع الكامل. يتكوّن الترحيل إلى نظام التخزين الموحّد من جزأين: علامة جديدة للتحكم في مرحلة الترحيل، وبرنامج نصي يعالج جميع المشاريع النشطة والمشاريع المحذوفة حذفًا طريًا. المراحل: * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (الافتراضي)، تتم قراءة الملفات وكتابتها إلى filestore. تُكتب الملفات إلى history بشكل غير متزامن. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` ، تتم قراءة الملفات من history مع الرجوع الاحتياطي إلى filestore، وتُكتب إلى كلٍّ من filestore وhistory. يمكن الرجوع إلى `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` ممكن. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` تُقرأ الملفات وتُكتب إلى history فقط. يمكن الرجوع إلى `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` غير ممكن، إلا إذا تم ذلك "دون اتصال". عند تخزين البيانات في [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) وعند استخدام حسابات خدمة منفصلة لـ filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) وhistory (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`):\nيرجى منح مستخدم filestore صلاحية القراءة إلى حاوية history الخاصة بالـ blobs `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . ستتولى خدمة filestore تقديم القراءات من خدمة المُصرِّف من الآن فصاعدًا. {% hint style="warning" %} يوصى بشدة بإجراء ترحيل الملفات الثنائية أولًا في بيئة غير إنتاجية/بيئة تجريبية. {% endhint %} {% hint style="success" %} تتيح لك رخصة Server Pro القياسية تشغيل التطبيق في بيئة إنتاج وكذلك في بيئة غير إنتاجية/بيئة تجريبية؛ ويوصى بشدة بتوفير بيئة غير إنتاجية للاختبار. {% endhint %} {% hint style="info" %} إذا قمت بالترقية إلى إصدار Server Pro/CE `6.0` ثم قررت لاحقًا أنك تريد الرجوع إلى إصدار أقدم، فيجب عليك الاستعادة من نسخة احتياطية كاملة للنظام. {% endhint %} ### إجراء الترحيل {% stepper %} {% step %} #### أنشئ نسخة احتياطية أنشئ نسخة احتياطية كاملة [احتياطية](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) لمثيلك مع لقطة متسقة من **mongo**, **redis** و **sharelatex** الأدلة. {% endstep %} {% step %} #### حدّث **Toolkit:** استخدم `$ bin/upgrade` برنامج نصي لترقية ال **Toolkit** إلى أحدث إصدار. عند سؤالك، لا **لا** تؤكد المطالبة **الترقية** صورة؟ — بدلاً من ذلك، عدّل يدويًا **config/version** الملف واضبط القيمة على `5.5.7`. **docker-compose.yml القديم:** حدّث إصدار `sharelatex` الخدمة إلى `5.5.7`. {% endstep %} {% step %} #### قدّر عدد المشاريع المتأثرة {% code overflow="wrap" %} ```bash # مستخدمو Overleaf Toolkit: $ 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" # مستخدمو docker-compose.yml القديم: $ 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" ``` {% endcode %} مثال على المخرجات: {% code fullWidth="false" %} ``` الحالة الحالية: - إجمالي عدد المشاريع: 10 - إجمالي عدد المشاريع المحذوفة: 5 يتم أخذ عينة من 1000 مشروع لتقدير التقدم... إحصاءات المشاريع في العينة: - المشاريع المأخوذة في العينة: 9 (90% من جميع المشاريع) - المشاريع في العينة التي تحتوي على جميع التجزئات: 5 - النسبة المئوية للمشاريع التي تحتاج إلى استكمال التجزئات: 44% (تقديريًا) - تحتوي المشاريع في العينة على 11 ملفًا يجب التحقق منها مقابل نظام سجلّ المشروع الكامل. - تحتوي المشاريع في العينة على 3 ملفات يجب رفعها إلى نظام سجلّ المشروع الكامل (تقدير 27% من جميع الملفات). إحصاءات المشاريع المحذوفة في العينة: - المشاريع المحذوفة في العينة: 4 (80% من جميع المشاريع المحذوفة) - المشاريع المحذوفة في العينة التي تحتوي على جميع التجزئات: 3 - النسبة المئوية للمشاريع المحذوفة التي تحتاج إلى استكمال التجزئات: 25% (تقديريًا) - تحتوي المشاريع المحذوفة في العينة على ملفين يجب التحقق منهما مقابل نظام سجلّ المشروع الكامل. - تحتوي المشاريع المحذوفة في العينة على ملف واحد يجب رفعه إلى نظام سجلّ المشروع الكامل (تقدير 50% من جميع الملفات). ``` {% endcode %} {% endstep %} {% step %} #### إفراغ قوائم انتظار سجلّ المشروع {% code overflow="wrap" %} ```bash # مستخدمو Overleaf Toolkit: $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues # مستخدمو docker-compose.yml القديم: $ docker compose exec sharelatex /overleaf/bin/flush-history-queues ``` {% endcode %} كرر الإفراغ حتى يتم إفراغ جميع المشاريع (`"project_ids":0`). ``` تم العثور على مشاريع {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"} الإجمالي {"succeededProjects":0,"failedProjects":0} ``` {% hint style="danger" %} في حال لم تكن قيمة "failedProjects" صفرًا، يُرجى التواصل مع الدعم وعدم مواصلة ترحيل الملفات الثنائية. {% endhint %} {% endstep %} {% step %} #### انتقل بمرحلة الترحيل إلى 1 Toolkit: اضبط `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` في `config/variables.env`. docker-compose.yml القديم: اضبط `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` في `البيئة` قسم `sharelatex` الخدمة. {% endstep %} {% step %} #### طبّق تغيير الإعدادات وابدأ المثيل Toolkit: `bin/up -d` docker-compose.yml القديم: `docker compose up -d` {% endstep %} {% step %} #### تحقق من الوصول إلى الملفات الثنائية افتح مشروعًا في محرر Overleaf في المتصفح وحدد ملفًا ثنائيًا، مثل صورة. {% endstep %} {% step %} #### شغّل برنامج الترحيل النصي {% code overflow="wrap" %} ```bash # مستخدمو Overleaf Toolkit: $ 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" # مستخدمو docker-compose.yml القديم: $ 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" ``` {% endcode %} {% hint style="danger" %} إذا كنت [تحتفظ بسجلات](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) الملفات خارج **sharelatex** الحاوية، فتأكد من أن مالك دليل السجلات مضبوط على `www-data` المستخدم (uid=33) حتى يمكن كتابة ملف السجل الناتج. {% endhint %} يجب أن يبدو الناتج هكذا: ```bash Set UV_THREADPOOL_SIZE=16 {"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"تحميل الواجهة الخلفية","time":"2025-07-25T15:00:58.166Z","v":0} جارٍ كتابة السجلات إلى /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log بدء النسخ الاحتياطي لملفات المشروع... تم تحميل الكتل العامة: 0 جارٍ معالجة المشاريع غير المحذوفة... تمت معالجة مشروع واحد، الزمن المنقضي 0 ث اكتمل تحديث المشاريع الحية جارٍ معالجة المشاريع المحذوفة... تبدو المجموعة deletedProjects فارغة. اكتمل تحديث المشاريع المحذوفة تم. ``` إذا نجح الترحيل، فستحصل على رمز خروج `0`، وستكون الأسطر الأخيرة تشير إلى عدم وجود إخفاقات: ```bash تم. ``` سيبدو ملف السجل بهذا الشكل (استخدم المسار كما يطبعه البرنامج النصي): {% code overflow="wrap" %} ```bash $ 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":"اكتملت الدفعة فعليًا","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":"إحصاءات ترحيل الملفات","v":0} ``` {% endcode %} {% endstep %} {% step %} #### أوقف المثيل Toolkit: `bin/stop sharelatex` docker-compose.yml القديم: `docker compose stop sharelatex` {% endstep %} {% step %} #### اجعل الملفات القديمة غير قابلة للوصول للتطبيق يمكنك الآن نقل الملفات القديمة إلى التخزين الثانوي. نوصي بالاحتفاظ بالملفات لبعض الوقت في حال ظهرت مشكلات لاحقًا. {% code overflow="wrap" %} ```bash # مستخدمو Toolkit: $ bin/docker-compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files # مستخدمو docker-compose.yml القديم: # نفترض أنك تستخدم الربط الافتراضي في /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 # إذا كنت تستخدم عمليات ربط انتقائية، فيمكنك ببساطة إزالة ربط /var/lib/overleaf/data/user_files داخل الحاوية. ``` {% endcode %} {% endstep %} {% step %} #### انتقل بمرحلة الترحيل إلى 2 Toolkit: اضبط `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` في `config/variables.env`. docker-compose.yml القديم: اضبط `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` في `البيئة` قسم `sharelatex` الخدمة. {% endstep %} {% step %} #### طبّق تغيير الإعدادات وابدأ المثيل Toolkit: `bin/up -d` docker-compose.yml القديم: `docker compose up -d` {% endstep %} {% step %} #### تحقق من الوصول إلى الملفات الثنائية افتح مشروعًا في محرر Overleaf في المتصفح وحدد ملفًا ثنائيًا، مثل صورة. {% endstep %} {% endstepper %} #### الترحيل دون اتصال إذا أردت منع المستخدمين من تسجيل الدخول أثناء تشغيل برنامج ترحيل الملفات الثنائية النصي، فيُرجى اتباع الخطوات التالية: * سجّل الدخول إلى مثيل Overleaf الخاص بك باستخدام حساب مدير * انقر على **الإدارة** الزر واختر **إدارة الموقع** * انقر على زر **فتح/إغلاق المحرر** علامة التبويب * انقر على **إغلاق المحرر** الزر * انقر على **فصل جميع المستخدمين** الزر بمجرد القيام بذلك، إذا كان أي مستخدمين مسجلين الدخول فسيُعاد توجيههم إلى صفحة الصيانة، وأي مستخدمين جدد يزورون صفحة تسجيل الدخول سيرون صفحة الصيانة و **لن** سيكونون قادرين على تسجيل الدخول. ستحتاج إلى تكرار هذه الخطوات عند إعادة تشغيل المثيل. لإعادة فتح الموقع، ما عليك سوى إعادة تشغيل المثيل. #### الترحيل عبر الإنترنت يمكن تشغيل برامج الترحيل النصية بينما لا يزال التطبيق يعمل. هناك بعض الاعتبارات التي يجب أخذها في الحسبان: * عملية الترحيل كثيفة الإدخال/الإخراج، لذا يجب مراقبة استخدام الموارد أثناء تشغيل البرنامج النصي. * مع ارتفاع التوازي في المعالجة، قد تواجه حلقة الأحداث في `filestore` الخدمة بعض الحجب، مما قد يؤدي إلى تجربة مستخدم متدهورة. نوصي بالبدء بالقيم الافتراضية لـ `--concurrency=10` و `--concurrent-batches=1` . * يمكنك إيقاف البرنامج النصي في أي وقت. سيؤدي تشغيله مرة أخرى إلى التحقق من المشاريع السابقة وتخطي الملفات التي تمت معالجتها بالفعل. وهذا مفيد إذا كنت تفضل تشغيل الترحيل في الأوقات الأقل ازدحامًا (مثلًا في الليل). توصيتنا هي إغلاق الموقع وتشغيل الترحيل دون اتصال خلال نافذة صيانة عندما يكون عدد مشاريعك أقل من 1000 مشروع (انظر مخرجات برنامج الترحيل النصي عند التشغيل مع `--report`). إذا كان عدد المشاريع كبيرًا، يمكنك تشغيل البرنامج النصي ومراقبة تقدمه، ثم تقرر ما إذا كنت ستتابع تشغيله عبر الإنترنت أم دون اتصال بحسب حالتك الخاصة. #### تنظيف بيانات الملفات الثنائية القديمة عندما تنتهي من الترحيل وتتأكد من أن المشاريع لا تزال قادرة على الوصول إلى جميع ملفاتها، يمكنك إزالة مخزن الملفات القديم في `/var/lib/overleaf/data/user_files`. نوصي بشدة بالاحتفاظ بهذه الملفات لبعض الوقت - يمكنك جعلها غير قابلة للوصول للتطبيق عن طريق إعادة تسمية المجلد أولًا. ### استكشاف الأخطاء وإصلاحها سنضيف هنا نصائح لاستكشاف الأخطاء وإصلاحها. يُرجى ملاحظة أنه بينما نقدم عادةً الدعم فقط لعملاء Server Pro، فإننا، نظرًا لطبيعة هذا الترحيل، سنبذل أيضًا قصارى جهدنا لدعم عملاء CE الذين يواجهون مشكلات خاصة بترحيل الملفات الثنائية. إذا فشل برنامج ترحيل الملفات الثنائية النصي (أي خرج مع خطأ أو طبع عددًا غير صفري من المشاريع الفاشلة)، فيُرجى إرسال التفاصيل التالية إلى فريق الدعم لدينا عبر البريد الإلكتروني [support+filestoremigration@overleaf.com](mailto:support+filestoremigration@overleaf.com?subject=Binary%20file%20migration%20problem\&body=Instance%20Type%3A%20CE%20or%20Server%20Pro%20%28delete%20as%20appropriate%29%0A%0AInstallation%20Type%3A%20Overleaf%20toolkit%20or%20docker-compose.yml%20or%20other%20%28delete%20as%20appropriate%29%0A%0AScript%20output%3A%0A%0Abin%2Fdoctor%20output%20%28if%20using%20toolkit%29%3A%0A)، موضحًا ما يلي: الموضوع: مشكلة ترحيل الملفات الثنائية المحتوى: * نوع المثيل: 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` الحاوية وتصديرها هكذا: ```bash $ docker cp sharelatex:/var/log/overleaf/filestore.log . # استبدل بالطابع الزمني كما يطبعه البرنامج النصي $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` يرجى حجب أي معلومات حساسة من ملفات السجل قبل إرفاقها. #### الملفات المفقودة كانت الإصدارات الأقدم من Server Pro/CE تُنشئ إدخالات شجرة الملفات قبل اكتمال رفع المستخدم، مما قد يتسبب في ظهور الملفات كأنها مفقودة عند فشل الرفع. قد تجد بعض هذه الحالات مُبلّغًا عنها كأخطاء عند معالجة جميع أشجار الملفات. إذا كان عدد الملفات المفقودة منخفضًا، ففكّر في مراجعة هذه الحالات يدويًا وحذفها من المحرر في المتصفح. إذا كان عدد الملفات المفقودة مرتفعًا، ففكّر في التواصل مع الدعم، راجع قالب البريد الإلكتروني أعلاه. #### العثور على أشجار الملفات المعطوبة قد يفشل الترحيل في المشاريع التي تحتوي على شجرة ملفات غير سليمة (على سبيل المثال، حيث تكون أسماء الملفات فارغة). يمكنك العثور على قائمة بهذه المشكلات باستخدام `find_malformed_filetrees` البرنامج النصي الذي يتحقق من جميع المشاريع في قاعدة البيانات: {% code overflow="wrap" %} ```bash $ 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" ``` {% endcode %} لإصلاح المسارات غير الصالحة، استخدم `fix_malformed_filetree` البرنامج النصي، مع تشغيل الأمر مرة واحدة لكل مسار سيئ: {% code overflow="wrap" %} ```bash $ 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" ``` {% endcode %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://overleaf-pro.ayaka.space/on-premises/ar/aldam/support-guides/v5.5.7-migration-binary-files-migration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.