حل المشكلات

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
Bind for 0.0.0.0:3030 failed: port is already allocated
Error: listen EADDRINUSE: address already in use :::3030

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

1. 01

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

   على macOS أو Linux، مع المنفذ الوارد في الرسالة:

   الطرفيةنسخ

   lsof -i :3030

   على Windows، في PowerShell:

   الطرفيةنسخ

   netstat -ano | findstr :3030
2. 02

   أوقفه

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

   أو شغّل لوحة التحكم على منفذين آخرين

   مع الحزمة الكاملة في Docker، أنشئ ملفًا باسم .env في المجلد dashboard-2-full-stack بجوار docker-compose.yml، وضع فيه المنفذ الذي تريده. يغيّر DASHBOARD_PORT منفذ لوحة التحكم وAPI_PORT منفذ واجهة API؛ أما العناوين التي تستخدمها التطبيقات، ومنها CORS_ORIGIN، فتتبعهما تلقائيًا.

   dashboard-2-full-stack/.envنسخ

   DASHBOARD_PORT=3040

   ثم شغّل الأمر نفسه مرة أخرى. التشغيل الذي فشل يكمل من حيث توقف:

   الطرفيةفي dashboard-2-full-stackنسخ

   docker compose up --build

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

• حزمة لوحة الإدارة في Docker: غيّر الرقم الذي على يسار -p، مثل docker run -p 3040:3030 dashboard-2، وافتح localhost:3040محلي. يستمع التطبيق داخل الحاوية دائمًا على 3030.
• من دون Docker: اضبط PORT=3040 في ملف .env الخاص بلوحة التحكم (أنشئ الملف بهذا السطر وحده إن لم يكن لديك ملف)، أو شغّل PORT=3040 yarn dev على macOS وLinux. ومع وجود واجهة API، أضف العنوان الجديد إلى CORS_ORIGIN وFRONTEND_URL في واجهة API أيضًا.
• واجهة API من دون Docker: غيّر PORT في back-end/.env، وغيّر معه NEXT_PUBLIC_API_BASE_URL وNEXT_PUBLIC_WEBSOCKET_BASE_URL في ملف .env الخاص بلوحة التحكم.

فشل بناء Docker

ينزّل البناء الأول الصور الأساسية وكل اعتمادية وخط لوحة التحكم العربي من Google Fonts، ثم يبني الصور. ويتوقف برسالة "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.8.1…". However the current global version of Yarn is 1.22…

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

corepack enable

ثم نفّذ yarn install مرة أخرى. وإذا لم يكن مع Node.js الخاص بك Corepack (Node.js 25 وما بعده)، فثبّته أولًا بالأمر npm install -g corepack.

لا تبدأ لوحة التحكم على Node.js أقدم

node: bad option: --env-file-if-exists=.env

يقرأ yarn dev وyarn start في لوحة التحكم ملف .env بخيار أضافه Node.js في الإصدار 22.9. تحقق من إصدارك:

node -v

إذا طبع إصدارًا أقل من 22.9، فثبّت Node.js 22.9 أو أحدث، ونفّذ corepack enable مرة أخرى، واحذف مجلد node_modules الخاص بالتطبيق ونفّذ yarn install مرة أخرى. مع Docker لا ينطبق شيء من هذا: فالصور تحمل Node.js الخاص بها.

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

The API cannot start: JWT_SECRET is not set. Set it in back-end/.env to the output of: …
The API cannot start: JWT_SECRET is still the example value from .env.example, so anyone can sign a token for any account. …
The API cannot start: CORS_ORIGIN is not set. List the dashboard origin (comma separated if there are several), …

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

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

ولّد سرًا بالأمر:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

مع Docker لا تحتاج إلى ذلك: الحاوية التي ليس لها JWT_SECRET خاص بها، أو التي تستخدم قيمة المثال، تولّد سرًا وتحفظه في وحدة تخزين البيانات.

• إعدادات واجهة API

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

• تحقق من الحساب. حساب Super Admin هو admin@example.com بكلمة المرور Admin@123؛ أما بقية المشرفين النموذجيين فكلمة مرورهم admin123.
• «البريد الإلكتروني أو كلمة المرور غير صحيحة. يرجى المحاولة مرة أخرى.» تظهر عند كلمة مرور خاطئة وعند بريد غير معروف على السواء، وعند قاعدة بيانات لا حسابات فيها. من دون Docker، نفّذ yarn seed في back-end: فـ yarn dev ينشئ الجداول بنفسه، لكن الـ seed وحده يضيف الحسابات.
• «محاولات تسجيل دخول فاشلة كثيرة. انتظر 15 دقيقة ثم حاول مرة أخرى.» فشل عنوان واحد في RATE_LIMIT_LOGIN محاولة تسجيل دخول (10 افتراضيًا) خلال 15 دقيقة. انتظر، أو أعد تشغيل واجهة API: فالعدّاد محفوظ في ذاكرتها.
• صفحة تسجيل الدخول لا تستجيب أبدًا. لا تستطيع لوحة التحكم الوصول إلى واجهة API: راجع المشكلة التالية.
• غيّرت كلمة مرور Super Admin ولم تعد لديك: ابدأ من جديد ببيانات نموذجية جديدة، أدناه.

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

• على واجهة API التجريبية، سجّل الدخول بالبريد admin@example.com وكلمة المرور Admin@123، أو بحساب Viewer نموذجي مثل john.smith@admin.com بكلمة المرور admin123. هذه الحسابات محفوظة في متصفحك: وكلمة المرور التي غيّرتها هناك تبقى كما غيّرتها حتى تمسح بيانات الموقع.
• على واجهة API الخاصة بك، يجب أن يكون الحساب موجودًا فيها. وعلى واجهة API الخاصة بهذا القالب، يضيف الـ seed الحسابات نفسها. وإذا لم ينجح أي حساب، فربما لا تصل لوحة التحكم إلى واجهة API: راجع المشكلة التالية.

تبقى الصفحات فارغة ويُبلغ المتصفح عن CORS

Access to XMLHttpRequest at 'http://localhost:8000/api/auth/login' from origin 'http://localhost:3040' has been blocked by CORS policy

تعرض وحدة تحكم المتصفح هذا السطر عندما تعمل لوحة التحكم على عنوان لا تقبله واجهة API. فهي لا تجيب المتصفحات إلا من العناوين الواردة في CORS_ORIGIN، وقيمته الافتراضية http://localhost:3030.

CORS_ORIGIN=http://localhost:3040
FRONTEND_URL=http://localhost:3040

• اكتب كل عنوان تمامًا كما يعرضه المتصفح، مع البروتوكول والمنفذ ومن دون شرطة مائلة في النهاية، وافصل بينها بفاصلة إذا كانت عدة عناوين. ثم أعد تشغيل واجهة API.
• FRONTEND_URL هو العنوان الوحيد الذي يقبله التحديث الفوري للصلاحيات. غيّره مع لوحة التحكم.
• مع الحزمة الكاملة في Docker لا تعدّل هذه القيم: فهي تُضبط بـ DASHBOARD_PORT وDASHBOARD_URL في ملف .env بجوار docker-compose.yml.
• لوحة التحكم التي لا تصل إلى واجهة API إطلاقًا، لأنها متوقفة أو على عنوان آخر، تفشل بالطريقة نفسها من دون سطر CORS. تحقق من أن localhost:8000/api/healthمحلي يجيب، ومن أن NEXT_PUBLIC_API_BASE_URL في لوحة التحكم يشير إلى تلك الواجهة.

تعرض لوحة التحكم بيانات نموذجية بدلًا من بيانات واجهة API الخاصة بي

Sample data
No API is connected (NEXT_PUBLIC_API_BASE_URL is empty), so the dashboard runs on built-in sample data. …

بُنيت لوحة التحكم من دون عنوان لواجهة API، فتعمل على واجهة API التجريبية المدمجة. يحدث ذلك من دون ملف .env، أو مع NEXT_PUBLIC_API_BASE_URL= فارغًا، أو مع صورة Docker بُنيت من دون --build-arg.

• من دون Docker: نفّذ cp .env.example .env في مجلد لوحة التحكم، وتحقق من NEXT_PUBLIC_API_BASE_URL، ثم أعد تشغيل yarn dev، أو نفّذ yarn build مرة أخرى لبناء الإنتاج.
• Docker، حزمة لوحة الإدارة: ابنِ الصورة مرة أخرى مع --build-arg NEXT_PUBLIC_API_BASE_URL=…، كما في دليل التثبيت.
• Docker Compose: يبني ملف compose لوحة التحكم دائمًا بعنوان واجهة API، لذلك لا يظهر هذا الإشعار هناك.

• واجهة API التجريبية المدمجة

تغيير ملف .env الخاص بلوحة التحكم لا يُحدث أي أثر

كل قيمة NEXT_PUBLIC_* تُضمَّن في كود JavaScript الذي يحمّله المتصفح عند بناء التطبيق. تغيير الملف لا يغيّر شيئًا حتى يُبنى التطبيق من جديد.

تغيير الدور لا يصل إلى لوحة التحكم إلا بعد إعادة التحميل

عندما تتغير صلاحيات دور، تُبلغ واجهة API لوحة تحكم كل مشرف مسجّل الدخول عبر WebSocket، فتتبعها القوائم والأزرار من دون إعادة تحميل. تتصل لوحة التحكم بـ NEXT_PUBLIC_WEBSOCKET_BASE_URL، وهو عنوان واجهة API من دون /api، ولا تقبل واجهة API الاتصال إلا من FRONTEND_URL، وهو عنوان لوحة التحكم نفسها.

• اضبط الاثنين على المكان الذي تعمل فيه التطبيقات فعلًا، ثم أعد تشغيل واجهة API وأعد بناء لوحة التحكم.
• FRONTEND_URL غير المضبوط لا يقبل إلا http://localhost:3030.
• تقرأ لوحة التحكم الصلاحيات أيضًا من جديد عند كل صفحة تفتحها، فلا يبقى شيء قديمًا طويلًا.

يطلب المساعد الذكي مفتاح API

The server has no key for this model's provider. Add your own API key to keep going.

ليس لدى واجهة API مفتاح لمزوّد النموذج الذي اخترته. إما أن تلصق مفتاحك الخاص في النافذة، فيبقى في متصفحك، أو تضيف مفتاح المزوّد إلى back-end/.env وتعيد تشغيل واجهة API (ومع Docker Compose، نفّذ docker compose up مرة أخرى).

gemini-3.6-flash has no requests left on this API key right now. Pick a different model from the list above the chat, or try again in a few minutes.

رفض المزوّد الطلب لأن حصة المفتاح استُنفدت، وهذا شائع مع المفاتيح المجانية. اختر نموذجًا آخر من القائمة، أو حاول لاحقًا.

• المساعد الذكي

تعذّر رفع صورة

Image uploads are not set up on this server yet. Add the Cloudflare R2 settings to the API environment to turn them on.

تُخزَّن الصور الشخصية ومرفقات الصور في المساعد في حاوية Cloudflare R2. اضبط متغيرات R2_* الخمسة في back-end/.env وأعد تشغيل واجهة API. ويعمل كل شيء آخر من دونها.

• رفع الصور

لا تعرض التحية الطقس

يحتاج الطقس في تحية النظرة العامة إلى مفتاح WeatherAPI.com في WEATHER_API_KEY، يقرؤه خادم لوحة التحكم نفسه. ومن دونه تظهر التحية من دون الطقس ولا يتغير شيء آخر.

• من دون Docker، في ملف .env الخاص بلوحة التحكم، ثم أعد التشغيل.
• مع Docker Compose، في ملف .env بجوار docker-compose.yml، ثم نفّذ docker compose up مرة أخرى.
• مع صورة لوحة التحكم، في docker run: -e WEATHER_API_KEY=....

MySQL يرفض البدء أو ملء البيانات

تنشئ واجهة API جداولها في قاعدة بيانات موجودة؛ ولا تنشئ القاعدة نفسها. أنشئ قاعدة بيانات فارغة أولًا، وضع اسمها في DB_DATABASE في back-end/.env، ثم نفّذ yarn seed.

• تحقق من قيم الاتصال الخمس DB_*، ومن أن DB_TYPE=mysql.
• مع NODE_ENV=production لا تنشئ واجهة API العاملة أي جداول أبدًا، لذلك يجب تنفيذ yarn seed:prod مرة واحدة بعد yarn build، قبل التشغيل الأول.
• تنشئ صورة Docker قاعدة البيانات بنفسها على SQLite فقط. وعلى MySQL، نفّذ node dist/database/seeder.js مرة واحدة داخل الحاوية بنفسك.

• استخدم MySQL بدلًا من SQLite

حاوية واجهة API لا تجد نقطة الدخول الخاصة بها

exec /usr/local/bin/docker-entrypoint.sh: no such file or directory

في السكربت نهايات أسطر بنمط Windows، وقد يضيفها محرر نصوص أو Git على Windows. يزيلها ملف Dockerfile المرفق مع واجهة API أثناء البناء، لذلك لا تظهر هذه المشكلة إلا مع صورة مبنية من Dockerfile معدَّل. أبقِ السطر sed -i 's/\r$//'، أو احفظ السكربت بنهايات أسطر LF، ثم أعد البناء من دون ذاكرة التخزين المؤقت.

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

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

ابدأ من جديد ببيانات نموذجية جديدة

مع الحزمة الكاملة في Docker، من المجلد dashboard-2-full-stack:

docker compose down -v
docker compose up

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

rm -f database.sqlite* && yarn seed

في PowerShell:

Remove-Item database.sqlite*; yarn seed

أعد ضبط البيانات النموذجية على واجهة API التجريبية

على واجهة API التجريبية المدمجة، تبقى البيانات النموذجية وكل ما غيّرته في متصفحك. امسح بيانات الموقع لعنوان لوحة التحكم من إعدادات متصفحك وأعد التحميل: فتعود البيانات النموذجية كما وصلت.