إنتقل إلى المحتوى الرئيسي

الأسئلة الشائعة واستكشاف الأخطاء

مشاكل التثبيت​

الصفحة فارغة بعد التثبيت​

الصفحة البيضاء الفارغة تعني في الغالب خطأ PHP يتم إخفاؤه بصمت.

  1. افتح الملف storage/logs/laravel.log في مدير الملفات (مدير ملفات لوحة تحكم الاستضافة أو FTP). انظر إلى الأسطر الأخيرة — ستجد رسالة خطأ تشرح ما حدث.
  2. الأسباب الشائعة:
    • امتدادات PHP مفقودة (راجع صفحة المتطلبات)
    • أذونات ملفات خاطئة (راجع قسم الأذونات أدناه)
    • بيانات اعتماد قاعدة بيانات خاطئة في ملف الإعداد

خطأ 500 Internal Server Error​

يعني هذا أن الخادم واجه خطأً لم يستطع التعافي منه.

  1. تحقق من storage/logs/laravel.log للاطلاع على رسالة الخطأ الفعلية.
  2. تحقق من سجل أخطاء خادم الويب — في cPanel يوجد ضمن السجلات ← سجل الأخطاء.
  3. الأسباب الأكثر شيوعاً:
    • بيانات اعتماد قاعدة بيانات خاطئة
    • قيمة APP_KEY مفقودة أو قصيرة جداً في ملف الإعداد
    • امتداد PHP مطلوب غير مفعّل

المُثبِّت يعيد توجيهي إلى البداية باستمرار​

يعني هذا عادةً أن المُثبِّت لا يستطيع الكتابة على القرص. تقوم عملية التثبيت بإنشاء ملف باسم storage/installed.lock عند الانتهاء. إذا لم تستطع إنشاء هذا الملف، تعتقد أن التثبيت لم يكتمل قط.

الحل: تأكد من أن مجلد storage/ وكل ما بداخله قابل للكتابة. في مدير ملفات استضافتك، انقر بزر الماوس الأيمن على مجلد storage وعيّن الأذونات على 755 أو 775.

فشل الاتصال بقاعدة البيانات​

ستقول رسالة الخطأ في المُثبِّت "Connection refused" أو "Access denied".

  • تحقق مرة أخرى من اسم مضيف قاعدة البيانات واسم قاعدة البيانات واسم المستخدم وكلمة المرور. يتم تعيين هذه عند إنشاء قاعدة بيانات في cPanel.
  • اسم مضيف قاعدة البيانات لاستضافة cPanel هو دائماً localhost تقريباً.
  • تأكد من أن مستخدم قاعدة البيانات لديه صلاحيات كاملة على قاعدة البيانات.

أخطاء الأذونات (لا يمكن الكتابة في storage أو cache)​

يحتاج LeadHub إلى الكتابة في مجلدات معينة. إذا رأيت أخطاء بشأن عدم القدرة على كتابة الملفات:

في مدير ملفات استضافتك، تأكد من أن هذه المجلدات مضبوطة على الإذن 755 (بعض المضيفين يحتاج 775):

  • storage/
  • storage/logs/
  • storage/framework/
  • storage/app/
  • bootstrap/cache/

مشاكل البريد الإلكتروني​

البريد الإلكتروني لا يُرسَل​

  1. انتقل إلى الإعدادات ← البريد الإلكتروني وتحقق من صحة جميع الحقول.
  2. انقر على إرسال بريد إلكتروني تجريبي وأدخل عنوان بريدك الإلكتروني.
  3. إذا لم يصل البريد التجريبي، تحقق من الملف storage/logs/laravel.log بحثاً عن أي خطأ SMTP.
  4. تأكد من أن cron job يعمل — تمر رسائل البريد الإلكتروني عبر قائمة انتظار المهام التي تحتاج إلى cron job للمعالجة. انظر قسم Cron Job أدناه.

رسائل البريد الإلكتروني تذهب إلى البريد المزعج​

  • السبب الأكثر شيوعاً هو أن عنوان "From Email" لا يتطابق مع نطاق معتمد من قِبل مزود SMTP الخاص بك.
  • أضف سجلات SPF و DKIM إلى إعدادات DNS لنطاقك. سيخبرك مزود البريد الإلكتروني (SendGrid أو Mailgun وغيرهم) بالضبط بما يجب إضافته.
  • تجنب استخدام Gmail الشخصي أو عناوين البريد الإلكتروني المجانية كعنوان مُرسِل للبريد المعاملاتي. استخدم خدمة إرسال احترافية.

البريد التجريبي يفشل​

  • تحقق من بيانات اعتماد SMTP — حرف واحد خاطئ يسبب الفشل.
  • بالنسبة لـ Gmail، يجب استخدام كلمة مرور التطبيق، وليس كلمة المرور العادية.
  • قد يكون المنفذ 587 محجوباً في الاستضافة المشتركة. جرّب المنفذ 465 مع SSL عوضاً عن ذلك.
  • اسأل مزود الاستضافة إذا كان SMTP الصادر مسموحاً به على المنفذ الذي تستخدمه.

مشاكل Cron Job​

الأتمتة لا تعمل / التقارير لا تُسلَّم​

يستخدم LeadHub cron job واحداً لمعالجة جميع الأعمال في الخلفية: الأتمتة وإرسال البريد الإلكتروني وتسليم التقارير والمهام المجدولة.

أمر cron job هو:

php /path/to/your/leadhub/cron.php

استبدل /path/to/your/leadhub/ بالمسار الفعلي على خادمك.

لإعداده في cPanel:

  1. سجّل الدخول إلى cPanel.
  2. انتقل إلى Cron Jobs.
  3. اضبط التكرار على كل دقيقة (ضع * في جميع الحقول الخمسة).
  4. الأمر: php /home/yourusername/public_html/cron.php
  5. انقر على إضافة Cron Job جديد.

إذا لم تكن متأكداً من المسار، تحقق مع مزود الاستضافة، أو انظر المسار الكامل الظاهر في مدير ملفات cPanel عند التنقل إلى مجلد الجذر للموقع.

لا توجد أوامر أخرى للتشغيل. لا تحاول تشغيل أوامر artisan من cron — استخدم cron.php فقط.

كيفية التحقق من أن cron job يعمل​

في cPanel، انتقل إلى Cron Jobs وانظر إلى cron job الذي أنشأته. إذا كان مدرجاً هناك فهو مجدول. للتحقق من أنه يُنفَّذ فعلاً، يمكنك إضافة >> /tmp/crontest.log 2>&1 مؤقتاً في نهاية الأمر، والانتظار دقيقة ثم فحص الملف للاطلاع على المخرجات.

مشاكل مصادر العملاء المحتملين​

Webhook لا يستقبل العملاء المحتملين​

  1. تحقق من أن عنوان URL لـ webhook الذي قمت بتكوينه في الخدمة الخارجية (Facebook أو Typeform وغيرها) صحيح تماماً، بما في ذلك الرمز المميز في النهاية.
  2. في LeadHub، انتقل إلى إعدادات التكامل أو مصدر العملاء المحتملين وابحث عن زر "Test" أو "Ping" — استخدمه للتحقق من الاتصال.
  3. تحقق من storage/logs/laravel.log بحثاً عن أي أخطاء webhook واردة.
  4. تأكد من أن خادمك متاح من الإنترنت (وليس خلف جدار حماية يحجب الاتصالات الواردة).

صندوق بريد IMAP لا يُستطلع​

استطلاع IMAP (فحص صندوق بريد إلكتروني بحثاً عن عملاء محتملين) يتطلب تشغيل cron job. راجع قسم Cron Job أعلاه. إذا كان cron job يعمل ولكن IMAP لا يزال لا يُستطلع:

  1. تحقق من إعدادات اتصال IMAP في تكوين التكامل.
  2. تأكد من تثبيت امتداد PHP php-imap على خادمك.
  3. تحقق من storage/logs/laravel.log بحثاً عن أخطاء اتصال IMAP.

مشاكل الأداء في الاستضافة المشتركة​

التطبيق بطيء أو تنتهي مهلته​

الاستضافة المشتركة لها موارد محدودة. بعض الأشياء التي يمكنك فعلها:

زيادة حد ذاكرة PHP: أضف هذا السطر إلى ملف .htaccess في مجلد الجذر لموقعك:

php_value memory_limit 256M

أو اطلب من مزود الاستضافة زيادته في إعدادات PHP الخاصة بك.

تفعيل التخزين المؤقت: تأكد من أن ملف الإعداد يحتوي على CACHE_DRIVER=file أو CACHE_DRIVER=database. هذه تعمل على الاستضافة المشتركة دون إعداد إضافي.

تقليل أحجام دُفعات قائمة الانتظار: إذا كان خادمك يعاني مع الاستيرادات الكبيرة أو العمليات الجماعية، قم بمعالجة دُفعات أصغر.

كيفية فحص السجلات​

ملف السجل الرئيسي موجود في:

storage/logs/laravel.log

يمكنك عرضه في مدير ملفات استضافتك بالانتقال إليه والنقر لفتحه. انظر إلى أسفل الملف — هناك تظهر أحدث الأخطاء.

قد يكبر ملف السجل مع مرور الوقت. يمكنك حذفه بأمان (التطبيق يُنشئ ملفاً جديداً تلقائياً).

كيفية مسح ذاكرة التخزين المؤقت​

إذا رأيت بيانات قديمة أو صفحات لا تعكس التغييرات الأخيرة، فقد تساعد عملية مسح ذاكرة التخزين المؤقت.

قم بذلك عبر مدير ملفات استضافتك:

  1. انتقل إلى bootstrap/cache/
  2. احذف جميع الملفات داخل هذا المجلد (ولكن ليس المجلد نفسه)
  3. انتقل إلى storage/framework/cache/data/
  4. احذف جميع الملفات والمجلدات الفرعية داخل هذا المجلد

تُعاد بناء ذاكرة التخزين المؤقت تلقائياً عند تحميل الصفحة التالي.

لا تحذف المجلدات نفسها — فقط محتوياتها.

كيفية إعادة تشغيل المُثبِّت​

إذا احتجت إلى المرور بمعالج التثبيت مرة أخرى (على سبيل المثال بعد الانتقال إلى قاعدة بيانات جديدة):

  1. في مدير ملفات استضافتك، انتقل إلى مجلد storage/.
  2. احذف الملف المسمى installed.lock.
  3. قم بزيارة موقعك في متصفح — سيبدأ المُثبِّت تلقائياً.

هذا لا يحذف بياناتك. يسمح فقط للمُثبِّت بالتشغيل مرة أخرى. تبقى قاعدة بياناتك وملفاتك سليمة.

أخطاء شائعة في ملف الإعداد​

ملف الإعداد (.env) في مجلد الجذر لموقعك يتحكم في إعدادات كثيرة. أخطاء شائعة:

  • APP_KEY مفقود — يجب أن يكون سلسلة عشوائية من 32 حرفاً. إذا كان مفقوداً أو خاطئاً، لن يبدأ التطبيق.
  • DB_HOST خاطئ — للاستضافة المشتركة، هذا دائماً localhost تقريباً. لا تستخدم اسم نطاقك.
  • مسافات حول = — الصيغة هي KEY=value بدون مسافات. KEY = value لا يعمل.
  • قيم تحتوي على أحرف خاصة دون علامات اقتباس — إذا كانت كلمة مرور قاعدة البيانات تحتوي على # أو &، ضع القيمة كاملة بين علامتي اقتباس مزدوجتين: DB_PASSWORD="my#p@ss&word"

الحصول على مساعدة​

إذا لم تستطع حل مشكلة باستخدام هذه الوثائق:

  1. تحقق أولاً من ملف السجل في storage/logs/laravel.log. رسالة الخطأ هناك غالباً تخبرك بالضبط بما هو خاطئ.
  2. ابحث في تعليقات CodeCanyon في صفحة منتج LeadHub — تمت الإجابة على كثير من المشاكل الشائعة هناك.
  3. افتح تذكرة دعم في CodeCanyon بالانتقال إلى صفحة منتج LeadHub والنقر على الدعم. أرفق القسم ذي الصلة من ملف السجل عند القيام بذلك.

عند التواصل مع الدعم، أدرج دائماً:

  • بيئة الاستضافة الخاصة بك (استضافة مشتركة / VPS، أي مزود)
  • إصدار PHP الذي يعمل به خادمك
  • الأسطر الأخيرة من storage/logs/laravel.log