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

إن فتح الصفحة محليًا لا يثبت أن مسار واجهة برمجة التطبيقات (API) يعمل؛ فقد تستخدم واجهة المتصفح والطلب الخلفي مضيفين أو منافذ أو بروتوكولات أو بيانات اعتماد مختلفة.

على الخادم المنزلي، قد تُحمَّل HTML والأصول الثابتة من وكيل عكسي أو ذاكرة التخزين المؤقت للمتصفح أو حاوية ويب محلية، بينما تنتقل طلبات API إلى خدمة أخرى أو مسار فرعي أو نقطة نهاية WebSocket أو عنوان أساسي مُكوَّن خارجيًا. ابدأ بالتقاط طلب فاشل واحد في المتصفح، ثم أعد تشغيله من حدود الشبكة ذات الصلة، وافصل بين التوجيه وTLS والمصادقة وسياسة المتصفح وإعدادات التطبيق بدل اعتبار الصفحة الظاهرة دليلًا على إمكانية الوصول إلى المكدس بأكمله.

أثبت ما إذا كانت الصفحة وواجهة API تستخدمان مسار الشبكة نفسه

افتح أدوات المطور في المتصفح وأعد تحميل الإجراء الفاشل. سجّل عنوان URL للطلب، والطريقة، والحالة، ونص الاستجابة، والعنوان البعيد، ومصدر الطلب، وما إذا كان الفشل في طلب HTTP عادي أو WebSocket أو حدث مُرسل من الخادم أو عملية جلب في الخلفية.

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

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

أعد تشغيل الطلب نفسه من كل حدّ شبكي ذي صلة

انسخ أحد الطلبات الفاشلة كأمر، وأعد تشغيله من العميل، ومن مضيف الوكيل العكسي، ومن حاوية مؤقتة متصلة بشبكة التطبيق. حافظ على طريقته ورأس التفويض ونوع المحتوى والجسم واسم المضيف المتوقع.

قد تكون واجهة API قابلة للوصول على مستويي TCP وHTTP، لكنها ترفض الطلب الحقيقي بسبب غياب رمز أو رأس. وقد ضيّق نقاش حول FreshRSS API سبب فشل خارجي إلى غياب سياق التفويض بدلًا من عدم إمكانية الوصول العامة إلى الحاوية.

فسّر أول حدّ يفشل. يشير فشل DNS إلى حل الأسماء؛ ويشير رفض الاتصال إلى المستمع أو المنفذ أو الشبكة؛ ويشير خطأ TLS إلى الهوية أو الثقة؛ وتشير حالتا 401 أو 403 إلى المصادقة أو السياسة؛ وغالبًا ما تشير 404 إلى التوجيه أو إعادة كتابة المسار الفرعي؛ أما نجاح الاستدعاء المباشر مع فشل استدعاء المتصفح فيوجّه التشخيص نحو قواعد الوكيل أو المتصفح.

تحقق من عنوان API الأساسي والمنفذ والمسار الفرعي

افحص عنوان URL العام للتطبيق، وعنوان API، وعنوان WebSocket، والمسار الأساسي، ومتغيرات الواجهة الأمامية وقت البناء. قد تحتوي واجهة مقدمة محليًا على عنوان API مطلق يشير إلى نطاق قديم أو عنوان IP خاص أو منفذ خاطئ أو مسار جذري لا يوجد إلا على الخادم.

تكون عمليات النشر ضمن مسار فرعي حساسة خصوصًا لطريقة التعامل مع الشرطات المائلة وقواعد إعادة الكتابة. وقد عزت حالة Frigate مع وكيل عكسي الموارد الفاشلة إلى سلوك إعادة كتابة المسار الفرعي رغم إمكانية الوصول إلى الواجهة الرئيسية.

اختبر نقطة نهاية API مع البادئة المُكوَّنة وبدونها فقط لتحديد المسار الصحيح، ثم أصلح التطبيق والوكيل ليتفقا على مسار أساسي واحد. لا تُبقِ استثناءات إعادة كتابة مكررة تجعل بعض الطرق تعمل بينما تستمر عمليات الرفع أو الاستدعاءات الراجعة أو نقاط النهاية المتدفقة في تجاوز الواجهة الخلفية المقصودة.

Featured

ZimaCube 2 سحابة شخصية منزلية NAS

ZimaCube2

$799.00 - $2,499.00

Buy Now

تحقق من رؤوس الوكيل العكسي وTLS ودعم البث

قارن مسار الوكيل للصفحات العادية بمساره لطلبات API وWebSocket والبث. تأكد من اسم خدمة الواجهة الخلفية، والمنفذ الداخلي، وإصدار HTTP، وسلوك ترقية الاتصال، والمهلة الزمنية للقراءة، وسياسة التخزين المؤقت، ورؤوس المضيف والبروتوكول المُمرَّرة.

أفاد مستخدمو Open WebUI بظهور واجهة تبدو سليمة بينما يتوقف إخراج API المُمرَّر عبر الوكيل بسبب اختلاف سلوك التخزين المؤقت أو البث عن الوصول المباشر. وينبغي أن يركّز التشخيص على مسار البث عبر الوكيل، لا على الصفحة الثابتة.

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

افصل بين سياسة المتصفح وإمكانية الوصول إلى الخادم

عندما ينجح أمر مباشر بينما يفشل المتصفح، افحص وحدة تحكم المتصفح بحثًا عن أخطاء CORS والمحتوى المختلط والشهادات وملفات تعريف الارتباط والطلبات التمهيدية. قد يستجيب الخادم بشكل صحيح بينما يرفض المتصفح إرسال الطلب أو إتاحة الاستجابة.

يربط نقاش حول Open WebUI خلف وكيل عكسي بين أعطال WebSocket وAPI ومعالجة المصدر والبروتوكول المُمرَّر، موضحًا سبب ضرورة بقاء هوية المصدر والبروتوكول متسقة عبر الوكيل.

تأكد من أن صفحة HTTPS لا تستدعي واجهة API عبر HTTP، وأن API تسمح بالمصدر المطلوب فقط، وأن الطلبات التمهيدية تصل إلى المسار نفسه، وأن ملفات تعريف ارتباط الجلسة تستخدم النطاق والمسار وسمتَي Secure وSameSite الصحيحة. تجنب تعطيل حماية المتصفح عالميًا؛ وأصلح هوية الخادم العامة وسياسته بدلًا من ذلك.

تحقق من سير عمل API الكامل من كل شبكة مطلوبة

بعد نجاح الطلب الفاشل الأول، اختبر تسجيل الدخول، والقائمة أو البحث، والإنشاء أو التحديث، والرفع، والتنزيل، وأحداث الخلفية، وتجديد رمز واحد من الشبكة المحلية ومن كل مسار بعيد مدعوم. لا يثبت نجاح طلب GET واحد إصلاح عمليات الكتابة الموثَّقة أو الاتصالات طويلة الأمد.

يُعد سير عمل ZimaSpace الخاص بـ الفصل بين إمكانية الوصول عبر IP وتوجيه النطاق الخطوة التالية عندما تعمل استدعاءات API المباشرة عبر العنوان لكنها تفشل عبر اسم المضيف العام.

لا تُحل المشكلة إلا عندما يستخدم العميل المتصفحي وغير المتصفحي نقطة النهاية الأساسية المقصودة، ويصل الوكيل إلى الواجهة الخلفية الصحيحة، وتستمر المصادقة عبر عمليات إعادة التوجيه، وتقبل سياسة المتصفح الاستجابة، وتبقى جلسات البث أو WebSocket مستقرة. احتفظ بالطلب الفاشل الذي التقطته كاختبار تراجعي للترقيات المستقبلية.