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

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

يساعد هذا الدليل مسؤولي WHMCS على تشخيص المشكلات الشائعة في Extendy GeoShield باستخدام الإعدادات الحالية، وسجل أحداث تسجيل الدخول، ونتائج اختبار المزود، وملخصات WHMCS Activity Log الآمنة.

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

ابدأ بهذه الفحوصات​

قبل التحقيق في عرض محدد، تأكد مما يلي:

  1. Extendy GeoShield مفعّل في WHMCS.
  2. تم ضبط Addon Enabled على Yes في صفحة إعدادات Extendy GeoShield.
  3. حدث تسجيل الدخول المعني بعد تفعيل الإضافة.
  4. يحتوي سجل أحداث تسجيل الدخول على صف لذلك الدخول.
  5. حقول الحدث Decision وAlert Sent وAlert Error وIP Address وCountry وProvider وIP Source Used وIP Source Verified تطابق توقعاتك.

لمرجع الإعدادات، راجع دليل الإعداد.

لحقول الأحداث، راجع سجل أحداث تسجيل الدخول.

لا يظهر حدث تسجيل دخول​

أسباب محتملة ومتحقق منها:

  • Addon Enabled مضبوط على No.
  • حدث تسجيل الدخول قبل تفعيل Extendy GeoShield.
  • الإجراء لم يكن حدث تسجيل دخول عادي إلى منطقة العملاء تعالجه الإضافة.
  • لم تتمكن الإضافة من تسجيل الحدث بأمان وكتبت فقط ملخصاً آمناً في WHMCS Activity Log.

الفحوصات:

  • تأكد أن Addon Enabled هو Yes.
  • تأكد أنك تراجع النطاق الزمني الصحيح في سجل أحداث تسجيل الدخول.
  • تحقق مما إذا كان تنظيف الاحتفاظ قد أزال صفوف أحداث أقدم.
  • تحقق من WHMCS Activity Log بحثاً عن ملخص آمن مثل عدم تمكن الإضافة من تسجيل حدث دخول عميل.

الإجراء التصحيحي:

  • فعّل الإضافة واختبر باستخدام تسجيل دخول مضبوط إلى منطقة العملاء.
  • إذا كانت الصفوف القديمة مفقودة، راجع الاحتفاظ بالبيانات.

يوجد حدث تسجيل دخول لكن لم يتم إرسال بريد تنبيه​

تسجيل حدث دخول لا يعني بالضرورة وجوب إرسال بريد.

أسباب محتملة ومتحقق منها:

  • تم تثبيط قرار الحدث بسبب منطق الدولة الموثوقة.
  • وجد Smart Mode أن الدولة معروفة بالفعل للسياق الحالي.
  • تم تثبيط الحدث بسبب فترة تهدئة التنبيه.
  • فشل اكتشاف الدولة وAlert When Country Detection Fails مضبوط على No.
  • لم يكن هناك سياق Client Account آمن متاح للحدث.
  • البريد الأساسي في Client Profile مفقود أو غير صالح.
  • قالب بريد Extendy GeoShield المحدد يحتوي على مستلمين منسوخين مكوّنين.
  • فشل WHMCS SendEmail أو تم إيقافه قبل التسليم.

الفحوصات:

  • راجع Decision وDecision Reason وAlert Sent وAlert Template وAlert Error في سجل أحداث تسجيل الدخول.
  • تأكد أن الحدث يحتوي على decision_result = alert_required عندما تتوقع إرسال بريد.
  • تأكد أن الحدث يحتوي على سياق client_id آمن.
  • تأكد أن البريد الأساسي في WHMCS Client Profile موجود وصالح.
  • تأكد أن قالب بريد Extendy GeoShield ذي الصلة لا يحتوي على مستلمين منسوخين مكوّنين.
  • تأكد أن تسليم البريد في WHMCS يعمل في بيئة WHMCS لديك.

الإجراء التصحيحي:

  • عدّل الدول الموثوقة، أو وضع التنبيه، أو فترة التهدئة، أو إعدادات فشل اكتشاف الدولة حسب الحاجة.
  • عالج مشكلات سياق العميل المفقود أو بريد Client Profile.
  • أزل المستلمين المنسوخين من قوالب تنبيه Extendy GeoShield.
  • استخدم استكشاف أخطاء بريد WHMCS لمشكلات التسليم النهائية.

توثيق ذو صلة:

تم تثبيط بريد التنبيه​

الأحداث المثبطة لا تزال مفيدة. فهي تُظهر أن الإضافة قيّمت تسجيل الدخول وقررت أن البريد غير مطلوب.

تشمل فئات قرارات التثبيط الشائعة:

  • دولة موثوقة;
  • دولة معروفة في Smart Mode;
  • فشل اكتشاف الدولة عندما تكون تنبيهات فشل الاكتشاف معطلة;
  • فترة التهدئة.

الفحوصات:

  • راجع Decision وDecision Reason في سجل أحداث تسجيل الدخول.
  • راجع إعدادات Alert Mode وAlert Cooldown.
  • راجع الدول الموثوقة وSmart Mode.

الإجراء التصحيحي:

  • إذا كان التثبيط متوقعاً، فلا يلزم اتخاذ إجراء.
  • إذا لم يكن التثبيط متوقعاً، راجع نموذج الثقة بالدول وإعداد فترة التهدئة.

مستلم البريد ليس بريد WHMCS User​

هذا متوقع في نموذج المستلم الحالي للـ MVP.

يرسل Extendy GeoShield رسائل التنبيه إلى البريد الأساسي في WHMCS Client Profile لسياق Client Account المحدد بأمان.

يبقى بريد WHMCS User هو ممثل تسجيل الدخول ويُدرج في محتوى البريد كـ user_email.

إذا لم يتوفر سياق Client Account آمن، فلا يتم إرسال بريد في MVP الحالي.

توثيق ذو صلة:

تبدو قوالب البريد مفقودة​

يستخدم Extendy GeoShield قوالب WHMCS General التالية:

Extendy GeoShield - Login Alert
Extendy GeoShield - Smart New Country Alert

تضمن الإضافة هذه القوالب أثناء التفعيل وعند تحميل صفحة إدارة الإضافة.

ينشئ منطق ضمان القوالب صفوف اللغة الرئيسية/الافتراضية المفقودة، ولا يكرر القوالب الموجودة عمداً ولا يستبدل محتوى القوالب الموجودة.

الفحوصات:

  • افتح صفحة إضافة Extendy GeoShield في WHMCS Admin.
  • تحقق من قوالب بريد WHMCS بحثاً عن أسماء القوالب الدقيقة أعلاه.
  • تأكد أن نوع القالب متوافق مع إرسال بريد WHMCS General.

الإجراء التصحيحي:

  • إذا كان قالب مفقوداً، افتح صفحة إدارة الإضافة أو أعد تفعيل الإضافة من WHMCS Admin لتشغيل منطق ضمان القوالب الآمن.
  • لا تنشئ قوالب مكررة بأسماء مختلفة قليلاً.

الدولة Unknown أو يفشل بحث GeoIP​

أسباب محتملة ومتحقق منها:

  • لم يتم اختيار مزود GeoIP.
  • بيانات اعتماد المزود مفقودة، أو غير صالحة، أو تم مسحها.
  • عنوان IP المحدد للعميل فارغ أو ليس عنوان IP عاماً صالحاً.
  • فشل طلب المزود، أو انتهت مهلته، أو رُفض، أو لم يُرجع بيانات دولة قابلة للاستخدام.
  • تم تغيير إعداد المزود المحدد في النموذج لكن لم يتم حفظه قبل الاختبار.

الفحوصات:

  • تأكد أن GeoIP Provider مضبوط على IPinfo أو MaxMind.
  • تأكد أن بيانات اعتماد المزود ذات الصلة محفوظة.
  • استخدم GeoIP Provider Test Connection مع عنوان IP عام وحقيقي للاختبار.
  • راجع IP Address وProvider وCountry وCountry Code في سجل أحداث تسجيل الدخول.
  • راجع Alert When Country Detection Fails.

الإجراء التصحيحي:

  • احفظ إعداد المزود المطلوب قبل استخدام Test Connection.
  • أعد إدخال بيانات الاعتماد أو امسحها وأعد إدخالها حسب الحاجة.
  • أصلح إعداد مصدر IP إذا لم يكن هناك عنوان IP عام للعميل.
  • إذا كنت تريد تنبيهات عند فشل اكتشاف الدولة، اضبط Alert When Country Detection Fails على Yes.

توثيق ذو صلة:

يفشل اختبار اتصال IPinfo​

الفحوصات:

  • تأكد أن GeoIP Provider محفوظ كـ IPinfo.
  • تأكد أن IPinfo API token مخزن.
  • تأكد أن عنوان IP الاختباري عنوان IP عام صالح.
  • تذكر أن الرمز يُرسل باستخدام رأس HTTP باسم Authorization: Bearer، وليس في عنوان URL.

الإجراء التصحيحي:

  • احفظ إعداد مزود IPinfo.
  • أعد إدخال الرمز إذا لزم الأمر.
  • اختبر مرة أخرى باستخدام عنوان IP عام.

لا يوثق Extendy GeoShield ولا يتحكم بحدود حساب IPinfo، أو الفوترة، أو الاحتفاظ، أو التسجيل من جانب المزود.

يفشل اختبار اتصال MaxMind​

الفحوصات:

  • تأكد أن GeoIP Provider محفوظ كـ MaxMind.
  • تأكد أن كلاً من MaxMind Account ID وMaxMind License Key مخزنان.
  • تأكد أن عنوان IP الاختباري عنوان IP عام صالح.
  • تذكر أن التنفيذ الحالي يستخدم MaxMind GeoIP2 Country web service، وليس قاعدة بيانات MMDB محلية.

الإجراء التصحيحي:

  • احفظ إعداد مزود MaxMind.
  • أعد إدخال Account ID أو License Key إذا لزم الأمر.
  • اختبر مرة أخرى باستخدام عنوان IP عام.

لا يدعم Extendy GeoShield حالياً استكشاف أخطاء ملفات قاعدة بيانات MaxMind المحلية.

تم اكتشاف عنوان IP غير صحيح للعميل​

أسباب محتملة ومتحقق منها:

  • Client IP Source المحدد لا يطابق طبولوجيا شبكتك.
  • يتم استخدام وضع REMOTE_ADDR خلف وكيل، لذلك يرى WHMCS عنوان الوكيل.
  • يتم تجاهل X-Forwarded-For لأن الطرف المباشر ليس وكيلاً موثوقاً مكوّناً.
  • يتم تجاهل CF-Connecting-IP لأن الطرف المباشر غير معروف كـ Cloudflare.
  • تستخدم البيئة عناوين شبكة خاصة أو محلية ولا يتوفر عنوان IP عام صالح للعميل.

الفحوصات:

  • راجع IP Source Used وIP Source Verified في سجل أحداث تسجيل الدخول.
  • تأكد من Client IP Source في الإعدادات.
  • لإعدادات الوكيل، راجع Trusted Proxy IPs / CIDRs.

الإجراء التصحيحي:

  • استخدم REMOTE_ADDR ما لم يتطلب إعداد وكيل أو Cloudflare متحققاً رأساً معيناً.
  • استخدم X-Forwarded-For فقط مع نطاقات وكلاء موثوقين محددة بعناية.
  • استخدم CF-Connecting-IP فقط عندما يكون WHMCS فعلياً خلف Cloudflare.

توثيق ذو صلة:

يتم تجاهل X-Forwarded-For​

السلوك المتحقق منه:

  • يتم النظر في X-Forwarded-For فقط عندما يطابق REMOTE_ADDR نطاق وكيل موثوق مكوّن.
  • يتم تقييم السلسلة من اليمين إلى اليسار.
  • تتم إزالة قفزات الوكيل الموثوق من الجهة اليمنى.
  • يتم اختيار أول عنوان IP عام صالح ليس وكيلاً.
  • السلاسل المفقودة، أو المشوهة، أو الطويلة جداً، أو التي تحتوي فقط على وكلاء، أو الخاصة، أو المحجوزة، أو غير القابلة للاستخدام بأي شكل آخر ترجع بأمان.

الفحوصات:

  • تأكد أن Client IP Source هو X-Forwarded-For.
  • تأكد أن Trusted Proxy IPs / CIDRs يحتوي على عنوان أو نطاق الوكيل المباشر.
  • تأكد أن سلسلة الرأس تحتوي على عنوان IP عام صالح للعميل.

لا تصلح هذا عبر الوثوق بنطاقات CIDR عريضة وعشوائية.

يتم تجاهل CF-Connecting-IP​

السلوك المتحقق منه:

  • يتم قبول CF-Connecting-IP فقط عندما ينتمي REMOTE_ADDR إلى نطاقات CIDR المضمنة الخاصة بـ Cloudflare.
  • وجود الرأس وحده لا يكفي.
  • إذا لم يصل الطلب عبر نطاق Cloudflare متحقق منه، يرجع Extendy GeoShield بأمان.

الفحوصات:

  • تأكد أن Client IP Source هو CF-Connecting-IP.
  • تأكد أن اسم مضيف WHMCS ممرر فعلياً عبر Cloudflare.
  • تأكد أن الوصول المباشر إلى الخادم الأصلي مقيد حيثما أمكن.

قائمة نطاقات Cloudflare مضمنة كلقطة تمت مراجعتها ولا يتم تحديثها تلقائياً أثناء تسجيل الدخول.

عنوان IP فارغ​

يمكن أن يحدث هذا عندما لا يتوفر عنوان IP عام صالح للعميل.

تشمل الحالات الشائعة:

  • التطوير المحلي;
  • الشبكات الخاصة;
  • الحاويات أو طبولوجيا الوكلاء الداخلية;
  • الرجوع إلى REMOTE_ADDR عندما يكون REMOTE_ADDR خاصاً/محلياً/محجوزاً.

يمكن أن يبقى حدث تسجيل الدخول مسجلاً. وقد يفشل اكتشاف دولة GeoIP.

رابط الثقة يطلب من المستخدم تسجيل الدخول​

هذا متوقع.

تتطلب روابط الثقة مصادقة WHMCS. فتح رابط ثقة أثناء عدم تسجيل الدخول يجب ألا يثق بدولة.

بعد تسجيل الدخول، يجب إعادة التحقق من إجراء الثقة مقابل الرمز وWHMCS User وسياق Client Account.

رابط الثقة غير صالح، أو منتهي الصلاحية، أو مستخدم سابقاً، أو مرفوض​

تشمل الأسباب المتحقق منها:

  • الرمز مفقود أو غير صالح;
  • انتهت صلاحية الرمز;
  • تم استخدام الرمز سابقاً;
  • WHMCS User المسجل دخوله لا يطابق الرمز;
  • سياق Client Account المحدد لا يطابق الرمز;
  • تمت محاولة إجراء الثقة من جلسة admin masquerading.

تنتهي صلاحية روابط الثقة بعد 48 ساعة ويمكن استخدامها مرة واحدة فقط.

الإجراء التصحيحي:

  • استخدم أحدث بريد تنبيه أمني.
  • سجل الدخول بنفس WHMCS User الذي تلقى التنبيه الأمني.
  • اختر سياق Client Account المطابق عندما يكون الرمز مربوطاً بعميل.

لا تتوقع أن استلام البريد أو فتحه بحد ذاته يثق بدولة.

Smart Mode لم يثق تلقائياً بدولة​

هذا متوقع.

يسجل Smart Mode الدول المعروفة ويقيّمها، لكن الدولة الجديدة لا تصبح موثوقة تلقائياً لمجرد حدوث تسجيل دخول.

بالنسبة إلى تنبيهات Smart New Country المؤهلة، قد يتضمن البريد رابط ثقة. يتطلب إجراء الثقة تسجيل دخول WHMCS وتحققاً صارماً من الرمز/المستخدم/العميل.

الدولة دون سياق عميل لا تصبح تلقائياً موثوقة لكل Client Accounts المرتبطة.

توثيق ذو صلة:

لا يتم تنظيف الأحداث القديمة​

أسباب محتملة ومتحقق منها:

  • Retention مضبوط على Disabled (Automatic Cleanup Off).
  • WHMCS cron لا يعمل.
  • الصف ليس أقدم من حد القطع المحسوب لمدة 180 يوماً.
  • لم يعمل التنظيف بعد أن أصبح الصف مؤهلاً.

الفحوصات:

  • تأكد أن Retention مضبوط على 180 Days.
  • تأكد أن WHMCS cron يعمل بشكل طبيعي.
  • تحقق من WHMCS Activity Log بحثاً عن ملخصات تنظيف الاحتفاظ الآمنة.

يزيل تنظيف الاحتفاظ فقط الصفوف القديمة من mod_extendy_geoshield_events. ولا ينظف الدول المعروفة، أو رموز الثقة، أو الإعدادات، أو قوالب البريد، أو إدخالات WHMCS Activity Log، أو النسخ الاحتياطية.

تعطيل Retention لم يحذف الأحداث الموجودة​

هذا متوقع.

Disabled (Automatic Cleanup Off) يعني أن التنظيف التلقائي معطل. وهو لا يحذف صفوف أحداث تسجيل الدخول الموجودة ولا يمنع الصفوف الجديدة من التراكم.

للتفاصيل، راجع الاحتفاظ بالبيانات.

تظهر بيانات اعتماد المزودين مخفية​

هذا متوقع.

تُخزن بيانات اعتماد المزودين باستخدام آلية WHMCS Local API الموثقة EncryptPassword / DecryptPassword وتُعرض كقيم مخفية في واجهة الإدارة.

ترك حقل بيانات الاعتماد فارغاً أثناء الحفظ يبقي القيمة المخزنة الحالية. استخدم إجراء المسح/الإزالة الصريح لإزالة بيانات اعتماد مخزنة.

لا تحاول استرجاع أو عرض أسرار المزودين المخزنة من واجهة الإدارة.

إلغاء التفعيل لم يزل البيانات المخزنة​

هذا متوقع.

إلغاء التفعيل يحافظ على بيانات الإضافة. وهو ليس عملية إزالة كاملة.

لا يضيف Extendy GeoShield منطق إسقاط الجداول إلى إلغاء التفعيل ولا يعتمد على callback منفصل وموثق لإلغاء تثبيت إضافة WHMCS.

إجراء Manual Full Removal / Uninstall Procedure الكامل موضوع توثيق منفصل.