حل المشكلات

Docker لا يعمل

failed to connect to the docker API at unix:///…/docker.sock; check if the path is correct and if the daemon is running

تعرض إصدارات Docker الأقدم الرسالة "Cannot connect to the Docker daemon" بدلًا من ذلك. وفي الحالتين، محرك Docker غير مُشغَّل.

1. 01

   افتح Docker Desktop

   شغّل Docker Desktop وانتظر حتى يُظهر أن المحرك يعمل. على Linux، شغّل الخدمة: sudo systemctl start docker.
2. 02

   تحقق من أن Docker يستجيب

   الطرفيةنسخ

   docker info

   النتيجة المتوقعة: يطبع قسم Server بدلًا من رسالة خطأ.
3. 03

   شغّل أمر التشغيل مرة أخرى

   docker compose up --build للحزمة الكاملة، أو أمرَي docker build وdocker run الخاصين بك لتطبيق واحد.

المنفذ مستخدم بالفعل

ports are not available: exposing port TCP 0.0.0.0:3030 … bind: address already in use
Error: listen EADDRINUSE: address already in use :::3030

السطر الأول من Docker، والثاني من yarn dev. هناك برنامج آخر يستمع بالفعل على 3030 أو 3031 أو 8000: غالبًا تشغيل سابق لـ Learnio، أو خادم تطوير لمشروع آخر.

1. 01

   اعرف ما الذي يشغل المنفذ

   على macOS أو Linux:

   الطرفيةنسخ

   lsof -i :3030

   على Windows، في PowerShell:

   الطرفيةنسخ

   netstat -ano | findstr :3030
2. 02

   أوقفه

   أغلق ذلك البرنامج، أو أوقف التشغيل السابق: Ctrl+C في طرفيته، أو docker compose down في مجلده، أو docker stop لحاوية شغّلتها بالأمر docker run. ثم شغّل Learnio من جديد.
3. 03

   أو شغّل Learnio على منافذ أخرى

   مع الحزمة الكاملة في Docker، أنشئ ملفًا باسم .env داخل المجلد learnio-lms بجوار docker-compose.yml يحدد المنفذ الذي تحتاجه. SITE_PORT ينقل موقع الطلاب، وADMIN_PORT لوحة الإدارة، وAPI_PORT واجهة API، وتتبعها العناوين التي تستخدمها التطبيقات تلقائيًا.

   learnio-lms/.envنسخ

   ADMIN_PORT=3041

   ثم شغّل الأمر نفسه من جديد. بعد تشغيل فاشل يكمل من حيث توقف:

   الطرفيةفي learnio-lmsنسخ

   docker compose up --build

   النتيجة المتوقعة: يجيب التطبيق على منفذه الجديد، هنا localhost:3041محلي.

فشل بناء Docker

ينزّل البناء الأول الصور الأساسية وكل الاعتماديات، ثم يبني الصور. وعندما يعترضه شيء، يتوقف بالرسالة "failed to solve" مع الخطوة التي فشلت.

• لا اتصال أو انتهت المهلة: يحتاج البناء إلى الإنترنت. شغّل الأمر مرة أخرى بعد عودة الاتصال؛ الخطوات المكتملة محفوظة في ذاكرة التخزين المؤقت.
• لا توجد مساحة كافية على الجهاز (No space left on device): حرّر مساحة في Docker Desktop، أو تحقق مما يستخدمه Docker بالأمر docker system df.
• يفشل عند الخطوة نفسها في كل مرة: أعد البناء من دون ذاكرة التخزين المؤقت، ثم شغّل التطبيقات.

docker compose build --no-cache
docker compose up

لحزمة التطبيق الواحد، أضف --no-cache إلى أمر docker build الخاص بك.

التشغيل الأول الذي يبدو عالقًا يكون غالبًا لا يزال يملأ البيانات التجريبية. لا يبدأ موقع الطلاب ولوحة الإدارة إلا بعد أن تعلن واجهة API أنها سليمة.

يقول Yarn إن إصداره 1.22

This project's package.json defines "packageManager": "yarn@4…". However the current global version of Yarn is 1.22…

يثبّت كل تطبيق Yarn 4 عبر Corepack. تعني هذه الرسالة أن Corepack لم يُفعَّل بعد.

corepack enable

على Node 26، الذي لم يعد يتضمن Corepack، ثبّته أولًا بالأمر npm install -g corepack. انتهاء yarn install بالرسالة "Done with warnings" أمر متوقع؛ أما الفشل الحقيقي فينتهي بالرسالة "Failed with errors".

تتوقف واجهة API قبل أن تبدأ

✖ The API cannot start. Fix these in back-end/.env:

تتحقق واجهة API من إعداداتها أولًا وتعرض قائمة بما يجب إصلاحه. الأسباب المعتادة:

• لا يوجد ملف `.env`. أنشئه في back-end/ بالأمر cp .env.example .env.
• `JWT_SECRET` فارغ، أو يحمل القيمة المثال مع `NODE_ENV=production`. ولّد مفتاحًا سريًا خاصًا بك.
• `CORS_ORIGIN` فارغ مع `NODE_ENV=production`. اذكر موقع الطلاب ولوحة الإدارة، مفصولين بفاصلة.
• `DB_TYPE` ليس `sqlite` ولا `mysql`.

• أساسيات واجهة API

فشل تسجيل الدخول

• تحقق من الحساب والتطبيق. تسجّل حسابات الطاقم الدخول إلى لوحة الإدارة على المنفذ 3031: admin@learnio.com بكلمة المرور Admin@123. ويسجّل الطالب التجريبي الدخول إلى موقع الطلاب على المنفذ 3030: demo@learnio.com بكلمة المرور Demo@123.
• راجع سجل واجهة API. الرسالة "The database has no accounts, so nobody can sign in" تعني أن البيانات التجريبية لم تُضَف قط. من دون Docker، شغّل yarn seed في back-end/. ومع Docker، فقد أُنشئت وحدة التخزين مع SEED_DEMO_DATA=false.
• الرسالة "The database has no tables yet" تعني أن مخطط قاعدة البيانات لم يُنشأ قط: شغّل yarn seed في back-end/ وأعد تشغيل واجهة API.
• غيّرت كلمة مرور المدير العام ولم تعد تعرفها: ابدأ من جديد ببيانات تجريبية جديدة، كما هو موضح أدناه.
• "That email and password combination didn't work" هي الإجابة نفسها لبريد غير مسجّل ولكلمة مرور خاطئة على حد سواء، فتحقّق من الاثنين.
• "Too many attempts" تعني أن عنوانًا واحدًا أجرى أكثر من 10 محاولات على نموذج تسجيل دخول أو كلمة مرور خلال دقيقة، وهو ما يرفضه الخادم الحي بالرمز 429. انتظر دقيقة ثم حاول مجددًا.

فشل تسجيل الدخول

• راجع سجل واجهة API. الرسالة "The database has no accounts, so nobody can sign in" تعني أن البيانات التجريبية لم تُضَف قط: شغّل yarn seed، أو شغّل حاوية Docker مع -e SEED_DEMO_DATA=true على وحدة تخزين جديدة.
• الرسالة "The database has no tables yet" تعني أن مخطط قاعدة البيانات لم يُنشأ قط: شغّل yarn seed وأعد تشغيل واجهة API.
• تحقّق من الحساب. المدير العام هو admin@learnio.com بكلمة المرور Admin@123، والطالب التجريبي demo@learnio.com بكلمة المرور Demo@123. تسجيل الدخول الفاشل يُجاب بالرمز 401 وبالرسالة نفسها سواء كان الخطأ في البريد أو في كلمة المرور.
• إجابة `429` تعني أن عنوانًا واحدًا أجرى أكثر من 10 محاولات على مسار تسجيل دخول أو إنشاء حساب أو كلمة مرور خلال دقيقة. ترويسة Retry-After تحدد عدد الثواني التي يجب انتظارها.

فشل تسجيل الدخول

مع المحاكاة داخل المتصفح، يسجّل أي بريد إلكتروني وأي كلمة مرور دخولك بصفة المدير العام. بعد ربط واجهة API، سجّل الدخول بحساب موجود فيها؛ حساب المدير العام التجريبي هو admin@learnio.com بكلمة المرور Admin@123.

يظهر إشعار "Sample data"

لم تتمكن الواجهة الأمامية من الوصول إلى واجهة API، لذا تعرض بياناتها النموذجية المرفقة بدلًا منها.

1. 01

   تحقق من أن واجهة API تستجيب

   افتح localhost:8000/api/healthمحلي. يجب أن يجيب بحالة ok.
2. 02

   تحقق من عنوان واجهة API في الواجهة الأمامية

   يجب أن تكون قيمة NEXT_PUBLIC_API_BASE_URL في ملف .env الخاص بالواجهة الأمامية عنوانَ واجهة API متضمنًا /api، مثل http://localhost:8000/api.
3. 03

   أعد تشغيل الواجهة الأمامية

   العنوان مُضمَّن أثناء البناء. أعد تشغيل yarn dev بعد تغييره؛ ومع Docker، شغّل docker compose up --build مرة أخرى.

صور الدورات لا تظهر بعد ربط R2

مع وجود مفاتيح R2_* في back-end/.env تقدّم واجهة API الوسائط من مخزنك، ولا تعرض الواجهتان الأماميتان إلا الصور القادمة من مضيفين بُنيتا للوثوق بهم. ومن دون ذلك المضيف تظهر الصورة المصغّرة لكل دورة نصًا بديلًا بدل الصورة.

1. 01

   حدّد المضيف العام لمخزنك

   مع Docker، ضع MEDIA_HOSTNAME=your-bucket.r2.dev في ملف .env بجانب docker-compose.yml. ومن دون Docker، اضبط NEXT_PUBLIC_MEDIA_HOSTNAME في ملف .env لكل واجهة أمامية. اكتب اسم المضيف فقط، من دون https://.
2. 02

   أعد بناء الواجهتين الأماميتين

   المضيف مُضمَّن أثناء البناء. شغّل docker compose up --build مرة أخرى، أو أعد تشغيل yarn dev وأعد البناء للإنتاج.

   النتيجة المتوقعة: تظهر صور الدورات المصغّرة من مخزنك.

المجلد يبدو مختلفًا

شغّل الأوامر داخل المجلد الذي يُستخرج إليه ملف ZIP. إذا لم يكن الأمر unzip متوفرًا، فاستخرجه بمدير الملفات بدلًا من ذلك؛ تضيف بعض الأدوات مجلدًا إضافيًا يحمل اسم ملف ZIP، فانتقل إلى المجلد الداخلي.

ابدأ من جديد ببيانات تجريبية جديدة

مع Docker، من المجلد learnio-lms:

docker compose down -v
docker compose up

من دون Docker، أوقف واجهة API، ثم:

rm -f database.sqlite && yarn seed

في PowerShell:

Remove-Item database.sqlite; yarn seed

تشغيل yarn seed مجددًا على قاعدة بيانات تحتفظ بها ليس إعادة ضبط: تحتفظ الأدوار بالصلاحيات التي منحتها لها، وتحتفظ الإعدادات بالقيم التي حفظتها. وحدها قاعدة بيانات جديدة تعيد القيم الأصلية.