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

شخّص تكامل 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:

Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

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

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 كمسؤول:

bcdedit /enum | findstr -i hypervisorlaunchtype

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

bcdedit /set hypervisorlaunchtype auto

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

اتبع دليل Microsoft لإصلاح خطأ WSL ‏0x80370102 ودليل Docker لاستكشاف أخطاء المحاكاة الافتراضية للخطأ المطابق. تغيّر هذه الإصلاحات ميزات 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. بمجرد أن يعمل الاتصال، أعد تشغيل 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 ثانية:

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 لديك؛ تغيير المنفذ لن يصلح هذا
أخطاء تنسيق قاعدة البيانات / الترقية مع بيانات موجودة	اتبع إجراء الترقية المدعوم؛ ولا توجّه صورة MongoDB قديمة عشوائية إلى بيانات أحدث

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

bin/docker-compose exec -T mongo mongosh --quiet --eval 'rs.status().ok'

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

لا تطبّق حلًا بديلًا لنواة MongoDB إلا إذا كان محرك Docker لديك يستخدم نواة متأثرة. إذا أشارت سجلات MongoDB إلى مشكلة في النواة، فقارن النواة الفعلية للمحرك بـملاحظات الإنتاج في MongoDB وحدّث WSL/Docker حسب الاقتضاء. لا تمحُ data/mongo أبدًا كحل عام لمشكلات بدء التشغيل.

​

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

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

bin/docker-compose ps
bin/docker-compose port sharelatex 80
curl -I http://localhost:8080/launchpad

ثم اختبر في PowerShell:

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 المحرك، وأن الحاوية الشقيقة تستطيع تركيب مجلد الترجمة:

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؛ واستخدم صورة أكمل للمشاريع التي تحتاج إلى حزم إضافية. لا تعطّل البيئة المعزولة لإصلاح حزمة TeX مفقودة.

​

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

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

​

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

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

بالنسبة إلى الحاويات الموجودة لكنها متوقفة، شغّل bin/start وافحص السجلات. اتبع إبقاء النسخة متاحة لبدء التشغيل عند تسجيل الدخول وسياسات إعادة التشغيل وإعدادات سكون Windows.