حل المشكلات

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

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

1. 01

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

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

   الطرفيةنسخ

   lsof -i :3031

   على Windows، في PowerShell:

   الطرفيةنسخ

   netstat -ano | findstr :3031
2. 02

   أوقفه

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

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

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

   velra-real-estate-full-stack/.envنسخ

   ADMIN_PORT=3041

   ثم شغّل الأمر نفسه مرة أخرى. يكمل التشغيل الفاشل من حيث توقف. يذكر Docker منفذًا مشغولًا واحدًا في كل مرة: إذا توقف عند منفذ آخر فأضفه إلى .env أيضًا.

   الطرفيةفي velra-real-estate-full-stackنسخ

   docker compose up --build

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

فشل بناء Docker

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

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

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 غير مفعّل بعد، فأجاب Yarn القديم المثبّت عامًّا بدلًا منه.

corepack enable

ثم شغّل yarn install مرة أخرى. إذا لم يكن في Node.js لديك Corepack (Node.js 25 وما بعده لا تضمه)، فثبّته أولًا بالأمر npm install -g corepack. لا يُستخدم npm ولا pnpm: كل تطبيق يأتي بملف yarn.lock خاص به.

يفشل التثبيت أو التشغيل على إصدار أقدم من Node.js

يعلن كل تطبيق أنه يحتاج Node.js 22 أو أحدث، وتعمل صور Docker على Node.js 24. يظهر إصدار Node.js الأقدم كتثبيت يفشل في بناء حزمة، أو كتطبيق يتوقف عند التشغيل.

node -v

إذا طبع إصدارًا أقل من 22، فثبّت Node.js 22 أو أحدث، وشغّل corepack enable مرة أخرى (على Node.js 25 وما بعده شغّل npm install -g corepack أولًا)، ثم احذف مجلد 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 website and agency dashboard origins, comma separated, …

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

• لا يوجد ملف `.env`، أو `JWT_SECRET` فارغ. أنشئ الملف في مجلد واجهة API بالأمر 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

الموقع بلا عقارات ولا يستطيع أحد تسجيل الدخول

→ No database at /data/database.sqlite. Creating the tables, no data (set SEED_DEMO_DATA=true for the demo).

أُنشئت قاعدة البيانات بالجداول فقط. يحدث هذا عندما تبدأ حاوية واجهة API على وحدة تخزين جديدة بدون SEED_DEMO_DATA=true، أو عندما تعمل الحزمة الكاملة مع SEED_DEMO_DATA=false في .env بجانب docker-compose.yml، أو بدون Docker عندما شُغّل yarn db:sync بدلًا من yarn seed. فلا توجد عقارات ولا حساب لتسجيل الدخول.

• بدون Docker: شغّل yarn seed في مجلد واجهة API. يضيف الوكالة التجريبية وحساباتها إلى الجداول الموجودة لديك.
• الحزمة الكاملة في Docker: احذف SEED_DEMO_DATA=false من .env، ثم docker compose down -v وdocker compose up. تُنشأ وحدة البيانات من جديد مع الوكالة التجريبية.
• حاوية واجهة API: احذف الحاوية، واحذف وحدة التخزين الخاصة بها، وشغّلها مرة أخرى مع -e SEED_DEMO_DATA=true، كما في «ابدأ من جديد» أدناه.

لا تعيد الحاوية تعبئة قاعدة بيانات موجودة أبدًا، أيًا كانت قيمة SEED_DEMO_DATA، لذلك لا يهم هذا المتغير إلا مع وحدة تخزين جديدة.

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

• تحقق من الحساب. تقبل لوحة التحكم على المنفذ 3031 الحساب admin@velra.example مع Admin@123، أو agent@velra.example مع Agent@123. ليس للموقع حسابات.
• «بريد إلكتروني أو كلمة مرور غير صحيحة» هي الرسالة نفسها لكلمة مرور خاطئة وبريد غير معروف وقاعدة بيانات بلا حسابات. افحص النقاط التالية بالترتيب.
• لا حسابات في قاعدة البيانات عندما تُنشأ مع SEED_DEMO_DATA=false. راجع «الموقع بلا عقارات ولا يستطيع أحد تسجيل الدخول» أعلاه.
• «محاولات تسجيل دخول كثيرة. حاول مرة أخرى بعد بضع دقائق.» عشر محاولات دخول فاشلة من عنوان واحد خلال 15 دقيقة تقفل النموذج لذلك العنوان حتى يمضي 15 دقيقة على أقدم محاولة فاشلة. انتظر، أو أعد تشغيل واجهة API: فالعدّاد محفوظ في ذاكرتها.
• «خطأ في الشبكة. يرجى فحص اتصالك والمحاولة مرة أخرى» تعني أن لوحة التحكم لا تصل إلى واجهة API: راجع مشكلة CORS أدناه.
• غيّرت بيانات الدخول ولم تعد تملكها: ابدأ من جديد ببيانات تجريبية جديدة، أدناه.

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

• تحقق من الحساب والمسار. يسجّل المسؤولون الدخول عبر POST /api/auth/login؛ والمدير العام الأولي هو admin@velra.example مع Admin@123. يعيد تسجيل الدخول الفاشل 401 بالرسالة نفسها سواء أكان البريد خاطئًا أم كلمة المرور.
• لا يعمل أي حساب إطلاقًا: أُنشئت قاعدة البيانات بدون الوكالة التجريبية. شغّل yarn seed، أو شغّل الحاوية مع -e SEED_DEMO_DATA=true على وحدة تخزين جديدة.
• الرد `429` يعني أن عنوانًا واحدًا فشل في 10 محاولات دخول خلال 15 دقيقة. يزول عندما يمضي 15 دقيقة على أقدم محاولة فاشلة، أو عند إعادة تشغيل واجهة API. يغيّر RATE_LIMIT_LOGIN هذا العدد.

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

تسجّل لوحة التحكم الدخول عبر واجهة Velra API، لذلك يجب أن يكون الحساب موجودًا فيها. على واجهة API مملوءة بالبيانات الأولية، سجّل الدخول بـ admin@velra.example وAdmin@123. إذا لم يعمل أي حساب، فإما أن واجهة API بدأت بدون بياناتها التجريبية (شغّل yarn seed في مجلدها، أو شغّل حاويتها على وحدة تخزين جديدة مع -e SEED_DEMO_DATA=true)، أو أن التطبيق لا يصل إلى واجهة API: راجع المشكلة التالية. ليس للموقع حسابات.

تظهر في الصفحات «تعذر تحميل هذا المحتوى الآن»

We could not load this right now
Access to XMLHttpRequest at 'http://localhost:8000/api/…' from origin 'http://localhost:3041' has been blocked by CORS policy

يعرض الموقع السطر الأول، وتقول لوحة التحكم «خطأ في الشبكة»، عندما لا يستطيع المتصفح استخدام واجهة API. وتعرض وحدة تحكم المتصفح السطر الثاني عندما تعمل واجهة أمامية على عنوان لا تقبله واجهة API. لا تردّ واجهة API على المتصفحات إلا من العناوين الموجودة في CORS_ORIGIN، وقيمته الافتراضية http://localhost:3030 وhttp://localhost:3031. يُرفض موقع أو لوحة تحكم نُقلا إلى منفذ آخر، أو قُدّما على نطاقك، حتى يُدرجا فيه.

CORS_ORIGIN=http://localhost:3030,http://localhost:3041
FRONTEND_URL=http://localhost:3041

• اكتب كل عنوان تمامًا كما يعرضه المتصفح، مع البروتوكول والمنفذ ومن دون شرطة مائلة في النهاية، مفصولة بفواصل. ثم أعد تشغيل واجهة API.
• FRONTEND_URL هو عنوان لوحة التحكم، وتتصل منه إشعاراتها المباشرة. انقله مع لوحة التحكم.
• لحاوية واجهة API، مرّر القيم نفسها باستخدام -e، مثل -e CORS_ORIGIN=http://localhost:3030,http://localhost:3041.
• مع الحزمة الكاملة في Docker لا تعدّل هذه القيم: تضبطها SITE_PORT وADMIN_PORT وSITE_URL وADMIN_URL في ملف .env بجوار docker-compose.yml.
• الواجهة الأمامية التي لا تصل إلى واجهة API إطلاقًا، لأنها متوقفة أو على عنوان آخر، تفشل بالطريقة نفسها من دون سطر CORS. تحقق من أن localhost:8000/api/healthمحلي يجيب، ومن أن NEXT_PUBLIC_API_BASE_URL في الواجهة الأمامية يشير إلى واجهة API تلك.

• انشرها

تبويب صفحة العقار يقول «تفاصيل العقار» في Docker

يقرأ خادم الموقع نفسه عنوان العقار لتبويب المتصفح، والعرض الأول للصفحة، وخريطة الموقع. داخل الحاوية يكون localhost هو الحاوية نفسها، لذلك لا يصل ذلك الخادم إلى واجهة API على حاسوبك عند http://localhost:8000. وتبقى الصفحة تُحمَّل في المتصفح الذي يصل إلى واجهة API مباشرة.

شغّل حاوية الموقع مع عنوان واجهة API كما يراه الخادم:

docker run -p 3030:3030 -e API_INTERNAL_URL=http://host.docker.internal:8000/api --add-host=host.docker.internal:host-gateway velra-website

تضبطه لك الحزمة الكاملة في Docker (http://api:8000/api). بدون Docker لا حاجة إليه.

لا تُحمَّل صور العقارات

تقدّم واجهة API الصور الأولية على /media/velra/…، ويُبنى عنوان كل صورة من PUBLIC_MEDIA_URL الذي قيمته الافتراضية http://localhost:8000/media. تنكسر الصورة عندما لا يصل ذلك العنوان إلى واجهة API من المتصفح.

• تعمل واجهة API على منفذ أو نطاق آخر. اضبط PUBLIC_MEDIA_URL على العنوان العام لواجهة API متبوعًا بـ /media، مثل -e PUBLIC_MEDIA_URL=http://localhost:8010/media مع docker run -p 8010:8000. مع الحزمة الكاملة في Docker، يضبطه API_PORT وAPI_URL نيابة عنك.
• انتقلت واجهة API بعد التشغيل الأول. أعد تشغيلها مع PUBLIC_MEDIA_URL الجديد: عند التشغيل توجّه كل صورة محفوظة إلى ذلك العنوان، ويقول سجلها «Pointed … stored media URLs at …».
• الملفات المرفوعة إلى مخزن لا تظهر. يجب أن يكون R2_PUBLIC_URL العنوان العام للمخزن، ويجب أن يسمح المخزن بالقراءة العامة.
• تُحمَّل الصور لكن بالحجم الكامل. لا تغيّر الواجهتان الأماميتان حجم إلا الصور القادمة من مضيفات https في NEXT_PUBLIC_MEDIA_HOSTNAME (مع Docker Compose هو MEDIA_HOSTNAME)، كل مضيف مكتوب وحده ومفصولة بفواصل، مثل api.your-agency.com,pub-1234.r2.dev. وتُحمَّل أي صورة أخرى، مثل صورة من واجهة API على localhost، كما هي. أعد بناء الواجهة الأمامية بعد تغييره.

• متغيرات البيئة

تغيير ملف .env للواجهة الأمامية لا يُحدث أي أثر

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

استوديو التأثيث أو المساعد يطلب مفتاحًا

Generation needs a Google Gemini key
The assistant needs an AI provider key

يجيب المساعد باستخدام Google Gemini أو OpenAI أو DeepSeek، ويعمل بمفتاح أي واحد منها في .env الخاص بواجهة API: GOOGLE_API_KEY أو OPENAI_API_KEY أو DEEPSEEK_API_KEY، وهي الثلاثة التي يذكرها تنبيهه. أما استوديو التأثيث فيولّد بـ Google فقط، لذلك يحتاج إلى GOOGLE_API_KEY مهما كان المضبوط غيره. في .env.example تكون الأسطر الثلاثة معلّقة، فيبدأ الملف المنسوخ نظيفًا وتبقى الميزتان معطلتين دون أي رسوم.

• احذف # الذي أمام سطر كل مفتاح لديك، والصق مفتاحك الحقيقي مكان المثال، وأعد تشغيل واجهة API.
• مع Docker Compose تقرأ واجهة API الملف back-end/.env أيضًا، لذلك يكفي docker compose up مرة أخرى؛ أما حاوية واجهة API المفردة فتحتاج --env-file .env -e NODE_ENV=production في docker run.
• أعد تحميل صفحة لوحة التحكم بعد إعادة التشغيل.
• النموذج الغائب من قائمة اختيار المساعد يتبع مزوّدًا لم يُضبط مفتاحه: فالقائمة تعرض فقط نماذج المزودين الذين لديهم مفتاح.

المساعد لا يستطيع الرد بالنموذج المختار

{provider} did not accept the API key, so {model} could not answer. Check that {variable} holds a valid {provider} key, then try again or pick a model from another provider.
The {provider} account behind this API key has no credit left, so {model} could not answer. Add credit or billing on that account, or pick a model from another provider.
{model} 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.
{provider} has no room for {model} right now. Try again in a minute, or pick another model from the list above the chat.

يعرض المساعد إحدى هذه الرسائل بدل الرد عندما يرفض المزوّد الذي يقف خلف النموذج المختار الطلب، مع Google أو OpenAI أو DeepSeek مكان المزوّد، واسم النموذج، ومتغير المفتاح. لا يشغّل إلا النموذج الذي اخترته: لا ينتقل إلى نموذج آخر من تلقاء نفسه ولا يعيد المحاولة بنفسه، فأصلح السبب أو اختر نموذجًا آخر من القائمة أعلى المحادثة، ثم اضغط «حاول مرة أخرى».

يُرفض طلب معاينة أو نموذج التواصل

Choose a date and time at least one hour from now, in Dubai time.
Too many requests were sent from this connection. Please wait a few minutes and try again.

• مبكر جدًا. يجب أن تبدأ المعاينة بعد ساعة على الأقل من الآن، بتوقيت المنطقة الزمنية للوكالة (Asia/Dubai)، مهما كانت ساعة الزائر نفسه.
• طلبات كثيرة جدًا. يمكن لكل عنوان إرسال خمسة نماذج تواصل وخمسة طلبات معاينة في عشر دقائق. أثناء الاختبار انتظر، أو أعد تشغيل واجهة API: فالعدّادات محفوظة في ذاكرتها.
• خلف وكيل عكسي قد يبدو كل زائر كأنه الوكيل ويتشاركون حدًا واحدًا: راجع المشكلة التالية.

يحصل كل زائر على «طلبات كثيرة» خلف وكيل

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

TRUST_PROXY=1

يغيّر RATE_LIMIT_LOGIN عدد محاولات الدخول الفاشلة المسموح بها. العدّادات محفوظة في ذاكرة واجهة API، لذلك يمسحها إعادة التشغيل.

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

تنشئ واجهة API جداولها في قاعدة بيانات موجودة مسبقًا؛ ولا تنشئ قاعدة البيانات نفسها. أنشئ أولًا قاعدة بيانات فارغة، وضع اسمها في DB_DATABASE في ملف .env الخاص بواجهة API، ثم شغّل yarn seed (أو yarn db:sync للجداول من دون بيانات تجريبية).

• تحقق من قيم الاتصال الخمس DB_*، ومن أن DB_TYPE=mysql.
• مع NODE_ENV=production لا تنشئ واجهة API العاملة أي جداول، لذلك يجب تشغيل أحد هذين الأمرين قبل التشغيل الأول (yarn seed:prod أو yarn db:sync:prod بعد yarn build).
• لا تنشئ صورة Docker قاعدة البيانات بنفسها إلا مع SQLite. مع MySQL، شغّل أمر تعبئة البيانات أو أمر إنشاء الجداول مرة واحدة بنفسك.

• استخدم 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، ثم أعد البناء من دون ذاكرة التخزين المؤقت.

يفشل أمر فك الضغط أو يبدو المجلد مختلفًا

caution: filename not matched:  velra-…zip

تعني تلك الرسالة أن في المجلد ملفَّي ZIP للحزمة نفسها، مثل تنزيل أقدم بجانب الجديد، وأن * في الأمر طابق الاثنين. احذف ملف ZIP الأقدم وشغّل الأمر مرة أخرى، أو اكتب اسم الملف كاملًا بدل *.

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

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

مع الحزمة الكاملة في Docker، من مجلد velra-real-estate-full-stack:

docker compose down -v
docker compose up

مع حاوية واجهة API المفردة، احذف الحاوية أولًا (يعرضها docker ps -a، ويحذفها docker rm -f مع معرّفها)، ثم احذف وحدة التخزين velra-api-data وشغّلها من جديد. تحفظ الحزمة الكاملة بياناتها في وحدة تخزين مختلفة هي velra-data، فلا يمسها هذا أبدًا.

docker volume rm velra-api-data
docker run -p 8000:8000 -v velra-api-data:/data -e SEED_DEMO_DATA=true velra-api

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

rm -f database.sqlite* && yarn seed

في PowerShell:

Remove-Item database.sqlite*; yarn seed

تشغيل yarn seed مرة أخرى على قاعدة بيانات تحتفظ بها ليس إعادة ضبط: فهو يضيف ما ينقص فقط ولا يعيد ضبط أي كلمة مرور. يحذف yarn db:reset كل جدول، على SQLite وMySQL معًا؛ شغّل yarn seed بعده.