> For the complete documentation index, see [llms.txt](https://ayakaleaf-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://ayakaleaf-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. تُكتب الملفات إلى السجل بشكل غير متزامن. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` ، تُقرأ الملفات من السجل مع الرجوع الاحتياطي إلى filestore وتُكتب إلى كلٍّ من filestore والسجل. يمكن الرجوع إلى `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` . * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` تُقرأ الملفات وتُكتب إلى السجل فقط. الرجوع إلى `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` غير ممكن، إلا إذا تم ذلك "دون اتصال". عند تخزين البيانات في [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) واستخدام حسابات خدمة منفصلة لـ filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) والسجل (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): يرجى منح مستخدم filestore إذن الوصول للقراءة إلى حاوية السجل للكائنات الثنائية الكبيرة `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** إلى أحدث إصدار. عندما يُطلب منك ذلك، لا **لا** تؤكّد المطالبة **الترقية** image? — بدلًا من ذلك، عدّل يدويًا **config/version** الملف واضبط القيمة على `5.5.7`. **Legacy 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" # مستخدمو Legacy 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% (تقديريًا) - المشاريع المحذوفة التي جرى أخذ عينات منها لديها ملفان يحتاجان إلى التحقق منهما مقابل نظام سجل المشروع الكامل. - المشاريع المحذوفة التي جرى أخذ عينات منها لديها 1 ملف يحتاج إلى رفعه إلى نظام سجل المشروع الكامل (مع تقدير 50% من جميع الملفات). ``` {% endcode %} {% endstep %} {% step %} #### إفراغ قوائم انتظار سجل المشروع {% code overflow="wrap" %} ```bash # مستخدمو Overleaf Toolkit: $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues # مستخدمو Legacy 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`. Legacy docker-compose.yml: اضبط `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` في `البيئة` قسم `sharelatex` الخدمة. {% endstep %} {% step %} #### طبّق تغيير الإعدادات وابدأ المثيل Toolkit: `bin/up -d` Legacy 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" # مستخدمو Legacy 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 اضبط 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} جاري كتابة السجلات إلى /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log بدء نسخ احتياطي لملفات المشروع... تم تحميل الكتل العامة: 0 جاري معالجة المشاريع غير المحذوفة... تمت معالجة 1 من المشاريع، الزمن المنقضي 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":"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} ``` {% endcode %} {% endstep %} {% step %} #### أوقف المثيل Toolkit: `bin/stop sharelatex` Legacy 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 # مستخدمو Legacy 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`. Legacy docker-compose.yml: اضبط `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` في `البيئة` قسم `sharelatex` الخدمة. {% endstep %} {% step %} #### طبّق تغيير الإعدادات وابدأ المثيل Toolkit: `bin/up -d` Legacy 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://ayakaleaf-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.