> ## 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.

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

> شخّص تكامل Docker Desktop وبدء تشغيل MongoDB والوصول إلى localhost من Windows وSandboxed Compiles على WSL 2.

شغّل أوامر Toolkit وDocker في **Ubuntu** ما لم تكن مميزة بـ **PowerShell**. احتفظ بالإعدادات والبيانات أثناء تشخيص الأعطال.

### يُبلغ WSL أو Docker بأن المحاكاة الافتراضية غير متاحة

تحتاج الواجهة الخلفية WSL 2 إلى المحاكاة الافتراضية للعتاد وإلى **Virtual Machine Platform**، وليس إلى ميزة Hyper-V الكاملة التي تستخدمها الواجهة الخلفية البديلة Hyper-V في Docker. ابدأ بعمليات التحقق هذه:

1. في Windows، ضمن **Task Manager → Performance → CPU**، تحقّق من **Virtualization: Enabled**. إذا كانت معطّلة، ففعّل Intel VT-x/VMX أو AMD-V/SVM في BIOS/UEFI باتباع تعليمات الشركة المصنّعة لجهازك.
2. في **PowerShell كمسؤول**، تحقّق من ميزات Windows:

```powershell theme={null}
Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
```

إذا كانت الميزات المطلوبة معطّلة، ففعّلها وأعد تشغيل Windows قبل إعادة محاولة WSL:

```powershell theme={null}
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
```

3. إذا كانت الميزات وإعداد BIOS مفعّلة لكن الخطأ `0x80370102` ما زال قائمًا، فتحقّق في **PowerShell كمسؤول**:

```powershell theme={null}
bcdedit /enum | findstr -i hypervisorlaunchtype
```

إذا أبلغ صراحةً عن `Off`، فاستعد تشغيل hypervisor عند الإقلاع وأعد تشغيل Windows:

```powershell theme={null}
bcdedit /set hypervisorlaunchtype auto
```

4. إذا كان Windows نفسه يعمل داخل آلة افتراضية، فيجب أن يوفّر الـ hypervisor الخارجي **المحاكاة الافتراضية المتداخلة (nested virtualization)**. لا يمكن لتفعيل خانة اختيار في Windows وحده أن يوفّر ميزات المعالج الافتراضي المفقودة.

اتبع [دليل Microsoft لإصلاح خطأ WSL ‏0x80370102](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting#error-0x80370102-the-virtual-machine-could-not-be-started-because-a-required-feature-is-not-installed) و[دليل Docker لاستكشاف أخطاء المحاكاة الافتراضية](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/#docker-desktop-fails-due-to-virtualization-not-working) للخطأ المطابق. تغيّر هذه الإصلاحات ميزات Windows أو إعدادات الإقلاع؛ فلا تشغّل منها إلا ما يتعلق بتشخيصك.

### يحتاج Docker Desktop إلى تحديث أو لا يستطيع سحب الصور

بالنسبة إلى **WSL update required**، شغّل `wsl --update` في PowerShell، وأعد تشغيل Windows إذا طُلب ذلك، ثم أعد فتح Docker Desktop وUbuntu. إذا ظل صف Ubuntu يعرض WSL 1، فحوّل التوزيعة كما هو موضح في الخطوة 0.

بالنسبة إلى مهلات السجل (registry) أو أخطاء DNS أو الوكيل أو الشهادات، تحقّق من السجل الفاشل بالضبط في مخرجات السحب. اضبط الوكيل والثقة بالشهادات في Windows/Docker Desktop إذا كانت شبكتك تحتاج إليها؛ ولا تعطّل التحقق من TLS. إن نجاح استنساخ GitHub لا يثبت أن Docker يستطيع الوصول إلى `ghcr.io` أو Docker Hub. راجع [إعدادات الوكيل في Docker Desktop](https://docs.docker.com/desktop/settings-and-maintenance/settings/#proxies). بمجرد أن يعمل الاتصال، أعد تشغيل `bin/up -d`؛ ويجب أن تبقى أسماء الصور المضبوطة متسقة.

### Docker غير متاح في Ubuntu

إذا لم يُعثر على `docker`، فافتح Docker Desktop في Windows، وفعّل Ubuntu ضمن **Settings → Resources → WSL Integration**، وطبّق التغيير وأعد فتح Ubuntu. تحقّق من اسم التوزيعة ووضع WSL باستخدام `wsl --list --verbose` في **PowerShell**. يجب أن تستخدم WSL 2.

إذا كان العميل موجودًا لكنه لا يستطيع الوصول إلى الـ daemon، فتحقّق من أن المحرك انتهى من بدء التشغيل. افحص `docker context ls` وأي إعدادات مخصصة لـ `DOCKER_HOST`/`DOCKER_CONTEXT`؛ فالمحرك البعيد أو socket قديم لـ Engine في Ubuntu ليس إعداد Desktop المحلي الذي يتناوله هذا الدليل. لا تُصلح هذا بتثبيت daemon آخر أو بجعل الـ socket قابلًا للكتابة من الجميع.

### يفشل MongoDB في البدء

يهيّئ `bin/up` مجموعة النسخ المتماثلة في MongoDB قبل تشغيل التطبيق. إذا توقف عند `Waiting for Mongo...`، فافحص قاعدة البيانات في طرفية **Ubuntu** ثانية:

```bash theme={null}
cd "$HOME/ayakaleaf-toolkit"
bin/docker-compose ps -a
bin/docker-compose logs --tail=150 mongo
docker inspect mongo --format 'Exit={{.State.ExitCode}} OOM={{.State.OOMKilled}} Error={{.State.Error}}'
docker info --format '{{.KernelVersion}}'
```

إذا كانت `mongo` غير موجودة وتعرض المخرجات خطأ في سحب الصورة، فعالج الوصول إلى السجل أو مساحة القرص أولًا؛ إذ لم تصل بعد إلى بدء تشغيل قاعدة البيانات. بمجرد إصلاح السبب، أعد تشغيل `bin/up -d`.

| الدليل | ما يجب التحقق منه |
| - | - |
| `OOMKilled=true` | زِد الذاكرة المتاحة لـ WSL/Docker أو قلّل الأحمال الأخرى، ثم أعد المحاولة |
| `No space left on device` | تحقّق من مساحة التخزين على مضيف Windows، ومن `df -h` في Ubuntu، ومن استخدام Docker للقرص؛ حرّر مساحة دون حذف بيانات قاعدة البيانات الحية |
| أخطاء أذونات أو تخزين ضمن `/data/db` | أبقِ `MONGO_DATA_PATH` على نظام ملفات Linux الخاص بـ Ubuntu. تحقّق من ربط التركيب الفعلي ومن الملكية؛ ولا تطبّق `chmod -R 777` |
| أخطاء Illegal instruction / ميزات المعالج | تحقّق من أن المعالج والمحاكاة الافتراضية يوفّران الميزات التي يتطلبها إصدار MongoDB لديك؛ تغيير المنفذ لن يصلح هذا |
| أخطاء تنسيق قاعدة البيانات / الترقية مع بيانات موجودة | اتبع [إجراء الترقية](https://ayakaleaf-pro.mintlify.site/ar/on-premises/maintenance/upgrading-your-deployment.md) المدعوم؛ ولا توجّه صورة MongoDB قديمة عشوائية إلى بيانات أحدث |

عندما يعمل MongoDB، تحقّق من مجموعة النسخ المتماثلة:

```bash theme={null}
bin/docker-compose exec -T mongo mongosh --quiet --eval 'rs.status().ok'
```

يجب أن تكون النتيجة `1`. يجري `bin/up -d` الإعداد الأولي لمجموعة النسخ المتماثلة؛ أما تشغيل خدمات Compose مباشرةً في نشر جديد فيتخطى خطوة Toolkit هذه.

لا تطبّق حلًا بديلًا لنواة MongoDB إلا إذا كان محرك Docker لديك يستخدم نواة متأثرة. إذا أشارت سجلات MongoDB إلى مشكلة في النواة، فقارن النواة الفعلية للمحرك بـ[ملاحظات الإنتاج في MongoDB](https://www.mongodb.com/docs/manual/administration/production-notes/) وحدّث WSL/Docker حسب الاقتضاء. لا تمحُ `data/mongo` أبدًا كحل عام لمشكلات بدء التشغيل.

### لا يستطيع Windows فتح localhost

اختبر أولًا في Ubuntu:

```bash theme={null}
bin/docker-compose ps
bin/docker-compose port sharelatex 80
curl -I http://localhost:8080/launchpad
```

ثم اختبر في **PowerShell**:

```powershell theme={null}
curl.exe -I http://localhost:8080/launchpad
```

إذا فشل كلاهما، فتحقّق من سجلات التطبيق وإعدادات المنفذ. إذا فشل Windows فقط، فتحقّق من وجود عملية أخرى في Windows تستخدم المنفذ 8080، أو إعدادات شبكة WSL مخصصة، أو قواعد VPN/وكيل، أو برامج أمان. لا تعطّل جدار الحماية بالكامل. يحتاج المنفذ المُغيَّر إلى قيم مطابقة لـ `OVERLEAF_PORT` و`OVERLEAF_SITE_URL` وعنوان URL في المتصفح، يليها `bin/up -d`.

### تفشل Sandboxed Compiles

تحقّق من الأجزاء الثلاثة كلها: أن الصورة موجودة في محرك Docker هذا، وأن التطبيق يستطيع استخدام socket المحرك، وأن الحاوية الشقيقة تستطيع تركيب مجلد الترجمة:

```bash theme={null}
docker image inspect ghcr.io/ayaka-notes/texlive-basic:2026.1 --format '{{.Architecture}} {{.Id}}'
docker inspect sharelatex --format '{{json .Mounts}}'
bin/logs -f clsi
```

استخدم الصورة المضبوطة في `config/variables.env`. تنتمي `SERVER_PRO=true` و`SIBLING_CONTAINERS_ENABLED=true` و`DOCKER_SOCKET_PATH=/var/run/docker.sock` إلى `config/overleaf.rc`. بعد التعديلات، شغّل `bin/up -d`؛ فـ `bin/start` وحده لا يحدّث بيئة الحاوية.

يعني الخطأ `No such image` أن Docker لا يستطيع العثور على الصورة الدقيقة التي يطلبها ذلك المشروع. أبقِ `TEX_LIVE_DOCKER_IMAGE` و`ALL_TEX_LIVE_DOCKER_IMAGES` متسقين، واسحب الصورة في المحرك نفسه، وتحقّق من اختيار TeX Live في المشروع. قد تحتفظ المشاريع الموجودة باختيار صورة أقدم.

في حال خطأ في التركيب أو مجلد `/compile` فارغ، تأكّد من أن Toolkit موجود ضمن المجلد الرئيسي لـ Ubuntu وأن تكامل Docker Desktop مفعّل لتلك التوزيعة نفسها. لا تستبدل مسار مضيف WSL بمسار Windows من نوع `C:\...`. يحسب Toolkit مسار الحاوية الشقيقة من `OVERLEAF_DATA_PATH`.

إن غياب `ctexart.cls` أو خط ما مع الصورة **basic** قيد في الحزم/الصورة. تحقّق أولًا من المقالة البسيطة من [الخطوة 6](https://ayakaleaf-pro.mintlify.site/ar/on-premises/installation/using-docker-compose/windows/6.-post-installation-tasks.md)؛ واستخدم صورة أكمل للمشاريع التي تحتاج إلى حزم إضافية. لا تعطّل البيئة المعزولة لإصلاح حزمة TeX مفقودة.

### تُبلغ سكربتات الصدفة عن أخطاء CRLF

شغّل السكربتات في Ubuntu Bash. حرّر الإعدادات بنهايات أسطر LF. تعني الأخطاء التي تذكر `bash\r` أو `$'\r'` عادةً أن الملفات حُوّلت إلى CRLF الخاص بـ Windows. استعد السكربت المتأثر من المستودع أو حوّل نهايات أسطره، مع الحفاظ على تغييرات الإعدادات المحلية.

### تختفي الحاويات بعد إعادة التشغيل

تحقّق من أن Docker Desktop قيد التشغيل وأن تكامل Ubuntu مفعّل. يعرض `docker ps` الحاويات قيد التشغيل فقط؛ افحص `docker ps -a` أيضًا. إذا كان المحرك مختلفًا عن الذي استُخدم أثناء الإعداد، فعد إلى السياق الصحيح بدلًا من تهيئة تثبيت فارغ آخر.

بالنسبة إلى الحاويات الموجودة لكنها متوقفة، شغّل `bin/start` وافحص السجلات. اتبع [إبقاء النسخة متاحة](https://ayakaleaf-pro.mintlify.site/ar/on-premises/installation/using-docker-compose/windows/6.-post-installation-tasks.md#keep-the-instance-available) لبدء التشغيل عند تسجيل الدخول وسياسات إعادة التشغيل وإعدادات سكون Windows.


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