> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# (ترحيل 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](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) واستخدام حسابات خدمة منفصلة لـ filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) وللسجل (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): يُرجى منح مستخدم filestore صلاحية القراءة على حاوية (bucket) السجل الخاصة بـ blobs `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET`. إذ ستتولى خدمة filestore من الآن فصاعدًا تلبية طلبات القراءة الواردة من خدمة الترجمة.

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

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

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

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

<Steps>
  <Step title="إنشاء نسخة احتياطية">
    أنشئ [نسخة احتياطية](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) كاملة من نسختك مع لقطة متسقة لمجلدات **mongo** و **redis** و **sharelatex**.
  </Step>

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

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

  <Step title="تقدير عدد المشاريع المتأثرة">
    ```bash wrap theme={null}
    # 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"
    ```

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

    ```text theme={null}
    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).
    ```
  </Step>

  <Step title="تفريغ قوائم انتظار سجل المشاريع">
    ```bash wrap theme={null}
    # 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`).

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

    <Danger>
      إذا لم تكن قيمة "failedProjects" صفرًا، فيُرجى التواصل مع الدعم وعدم متابعة ترحيل الملفات الثنائية.
    </Danger>
  </Step>

  <Step title="تقديم مرحلة الترحيل إلى 1">
    Toolkit: اضبط `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` في `config/variables.env`.

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

  <Step title="تطبيق تغيير الإعداد وتشغيل النسخة">
    Toolkit: `bin/up -d`

    ملف docker-compose.yml القديم: `docker compose up -d`
  </Step>

  <Step title="التحقق من الوصول إلى الملفات الثنائية">
    افتح مشروعًا في محرر Overleaf في المتصفح واختر ملفًا ثنائيًا، مثل صورة.
  </Step>

  <Step title="تشغيل سكربت الترحيل">
    ```bash wrap theme={null}
    # 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"
    ```

    <Danger>
      إذا كنت [تحتفظ بملفات السجلات](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) خارج الحاوية **sharelatex**، فتأكد من أن مالك مجلد السجلات هو المستخدم `www-data` (uid=33) حتى يمكن كتابة ملف السجل الناتج.
    </Danger>

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

    ```bash theme={null}
    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`، وستشير الأسطر الأخيرة إلى عدم وجود أي إخفاقات:

    ```bash theme={null}
    Done.
    ```

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

    ```bash wrap theme={null}
    $ 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}
    ```
  </Step>

  <Step title="إيقاف النسخة">
    Toolkit: `bin/stop sharelatex`

    ملف docker-compose.yml القديم: `docker compose stop sharelatex`
  </Step>

  <Step title="جعل الملفات القديمة غير قابلة للوصول من التطبيق">
    يمكنك الآن نقل الملفات القديمة إلى تخزين ثانوي. ونوصي بالاحتفاظ بالملفات لبعض الوقت تحسبًا لظهور مشكلات لاحقًا.

    ```bash wrap theme={null}
    # 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.
    ```
  </Step>

  <Step title="تقديم مرحلة الترحيل إلى 2">
    Toolkit: اضبط `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` في `config/variables.env`.

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

  <Step title="تطبيق تغيير الإعداد وتشغيل النسخة">
    Toolkit: `bin/up -d`

    ملف docker-compose.yml القديم: `docker compose up -d`
  </Step>

  <Step title="التحقق من الوصول إلى الملفات الثنائية">
    افتح مشروعًا في محرر Overleaf في المتصفح واختر ملفًا ثنائيًا، مثل صورة.
  </Step>
</Steps>

#### الترحيل دون اتصال (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 الذين يواجهون مشكلات خاصة بترحيل الملفات الثنائية.

إذا فشل سكربت ترحيل الملفات الثنائية (أي خرج بخطأ أو طبع عددًا غير صفري من المشاريع الفاشلة)، فيُرجى إرسال التفاصيل التالية إلى فريق الدعم لدينا عبر البريد الإلكتروني [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)، مع توضيح:

الموضوع: 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` وتصديرها على هذا النحو:

```bash theme={null}
$ 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` الذي يفحص جميع المشاريع في قاعدة البيانات:

```bash wrap theme={null}
$ 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`، مع تشغيل الأمر مرة واحدة لكل مسار تالف:

```bash wrap theme={null}
$ 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"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.