دليل إعداد خدمة عكس بروكسي Ngrok في ServBay

يُعد Ngrok أداة قوية لإنشاء أنفاق آمنة، حيث يعتمد على تقنية العكس البروكسي لتمكين تحويل الخدمات المحلية إلى نطاقات عامة عبر الإنترنت، متجاوزًا الجدران النارية وNAT. يقدم هذا الدليل شرحًا مفصلًا لكيفية دمج وتكوين خدمة Ngrok ضمن بيئة تطوير ServBay المحلية، مما يسمح لك بإتاحة خدمة الويب المحلية أو واجهات برمجة التطبيقات (API) أو أي خدمة أخرى عبر الإنترنت، ليسهل عليك العرض عن بُعد، والتعاون مع الفرق، واختبار نداءات الخدمات الخارجية.

المبدأ التقني

تعتمد فكرة Ngrok الأساسية على إنشاء نفق مشفر بين جهازك المحلي وخوادم Ngrok. عند محاولة مستخدم خارجي الوصول عبر النطاق العام الذي تخصصه لك Ngrok، تصل الطلبات أولًا إلى خوادم Ngrok، ثم تُحول بأمان إلى خدمة ServBay المحلية عبر هذا النفق. هذا يعني أنك تستطيع نشر خدماتك حتى من دون عنوان IP عام أو عند وجود جدار ناري. بالنسبة لمستخدمي ServBay، يمكن مشاركة المواقع المحلية أو الخدمات الخلفية أو أي خدمة HTTP/HTTPS بسهولة مع أطراف خارجية للتجربة والعرض الفوري.

تجهيز البيئة

قبل البدء في إعداد Ngrok، تأكد من إتمام الخطوات التالية:

1. تم تثبيت ServBay ويعمل: تأكد من تثبيت تطبيق ServBay بنجاح وأن خدمة الويب التي تريد مشاركتها عبر Ngrok (مثل موقع ويب) تم تكوينها وتعمل محليًا. يمكنك إدارة المواقع من خلال لوحة المواقع في ServBay.
2. تثبيت عميل Ngrok: ثبّت أداة سطر الأوامر لـ Ngrok عبر الخطوات التالية:
   1. انتقل إلى صفحة تحميل Ngrok الرسمية وحمّل الحزمة المناسبة لنظامك.
   2. بعد فك الضغط، انقل ملف ngrok التنفيذي إلى مجلد موجود في مسار النظام (مثل /usr/local/bin في macOS) لتتمكن من تشغيل الأمر ngrok من أي نافذة طرفية.

      # مثال على معمارية macOS ARM64
      sudo unzip ~/Downloads/ngrok-v3-stable-darwin-arm64.zip -d /usr/local/bin

   3. تحقق من اكتمال التثبيت بتشغيل الأمر التالي للتأكد من ظهور رقم الإصدار:

      ngrok version
      # مثال على المخرجات: ngrok version 3.5.0

3. حساب Ngrok (اختياري لكن مستحسن): وجود حساب Ngrok (مجاني أو مدفوع) يمكن أن يسهل إدارة الأنفاق ويسمح باستخدام ميزات متقدمة كالنطاقات الثابتة. قم بالتسجيل في موقع Ngrok واحصل على رمز المصادقة الخاص بك (ngrok config add-authtoken <YOUR_AUTH_TOKEN>) لرفع قيود مدة الاتصال والوصول لمزايا إضافية.
4. تكوين موقع محلي: يجب أن يحتوي ServBay على موقع محلي واحد على الأقل ترغب في مشاركته عبر Ngrok، مثل servbay.local أو yourproject.servbay.demo.

إعداد النفق عمليًا

شرح المعلمات الأساسية

بنية الأمر القياسي لربط الخدمة المحلية بالنطاق العام كالتالي:

ngrok http --domain=<NGROK_DOMAIN> <LOCAL_ENDPOINT> \
  --request-header-add='host: <VIRTUAL_HOST>'

عنصر المعلمة	الشرح
http	فتح نفق عبر بروتوكول HTTP، حيث يتولى Ngrok التعامل مع طلبات HTTP/HTTPS الواردة.
--domain <NGROK_DOMAIN>	تعيين نطاق ثابت مخصص لك من خلال لوحة Ngrok (الدومين). لا يتطلب الأمر عادة للمجانين حيث يتم تخصيص نطاق فرعي عشوائي تلقائيًا.
<LOCAL_ENDPOINT>	عنوان خدمة ServBay المحلية (غالباً دومين محلي كـ https://servbay.local أو منفذ معين).
--request-header-add='host: <VIRTUAL_HOST>'	مهم جدًا تعديل ترويسة الـ Host للطلب الوارد. ServBay يحدد المواقع عبر ترويسة الـ Host، لذا يجب ضبطها على الدومين المحلي الصحيح لضمان تحويل الطلب للموقع المناسب.

أمثلة التكوين

لنفترض أن لديك موقعًا محليًا في ServBay بعنوان servbay.local وتريد مشاركته عبر Ngrok. مع الخطة المجانية يمكنك مباشرة ربط العنوان المحلي:

# ربط موقع ServBay المحلي servbay.local عبر نطاق Ngrok العشوائي
ngrok http https://servbay.local --request-header-add='host: servbay.local'

أما إذا كان لديك نطاق ثابت من خلال لوحة تحكم Ngrok (مثل your-servbay-demo.ngrok-free.app)، استخدم معامل --domain:

# ربط موقع ServBay المحلي servbay.local بنطاق Ngrok محدد
ngrok http --domain=your-servbay-demo.ngrok-free.app https://servbay.local --request-header-add='host: servbay.local'

بعد تنفيذ الأمر بنجاح، يعرض عميل Ngrok في الطرفية حالة النفق والعنوان العام المعين، بالإضافة إلى رابط لوحة المراقبة الفورية (عادة: http://127.0.0.1:4040).

التحقق من الخدمة

بعد الانتهاء من الإعداد وتشغيل نفق Ngrok بنجاح، تحقق باتباع الخطوات التالية:

1. الحصول على العنوان العام: اعثر على سطر “Forwarding” في نافذة Ngrok وسجل رابط الـ HTTPS الظاهر أمامك.
2. الوصول عبر المتصفح: من أي جهاز متصل بالإنترنت، افتح متصفحك وادخل على الرابط (مثل https://cunning-lacewing-fresh.ngrok-free.app أو نطاقك الثابت).
3. التحقق من النتيجة:
   • تحقق من تحميل محتوى موقعك المحلي المُستضاف على ServBay.
   • افحص ما إذا كان المتصفح يعرض علامة اتصال آمن (HTTPS)؛ يوفر Ngrok شهادة SSL سليمة تلقائيا.
   • يعرض عميل Ngrok أو واجهته المحلية (http://127.0.0.1:4040) سجلات الطلبات وتحليل المرور لتأكيد وصول الطلبات لServBay وتعاملها معها.

رسم توضيحي: الوصول الناجح للنفق من المتصفح عبر Ngrok

نصائح متقدمة وتنبيهات مهمة

1. إدارة النطاقات:
   • مع الخطة المجانية، تحصل غالبًا على نطاق فرعي عشوائي من .ngrok-free.app مع حد زمني للاتصال.
   • عبر حساب Ngrok ولوحة التحكم الخاصة به (Ngrok Dashboard) يمكنك تعيين نطاق ثابت لضمان عدم تغيير الرابط في كل مرة.
   • في الخطط المدفوعة يمكنك ربط نطاقاتك الخاصة مع مزايا من حيث السرعة، والاتصال المتعدد، والخصائص الإضافية.
2. ربط خدمات متعددة: إذا أردت مشاركة أكثر من خدمة أو منفذ من ServBay عبر الإنترنت، يمكنك تشغيل أكثر من عملية Ngrok أو تعريف ذلك في ملف إعدادات Ngrok (~/.config/ngrok/ngrok.yml). مثال:

   # ربط موقع servbay.local (بافتراض أنه يعمل عبر HTTPS 443 ووصول بالHost)
   ngrok http --domain=servbay-website.ngrok-free.app https://servbay.local --request-header-add='host: servbay.local'
   
   # في نافذة أخرى أو عبر الملف ذاته، ربط تطبيق Node.js يعمل على المنفذ 3000
   ngrok http --domain=nodejs-api.ngrok-free.app http://localhost:3000

   تنبيه: من الأفضل استخدام https://[الدومين المحلي] مع --request-header-add بدلاً من توجيه الأنفاق لمنفذ ServBay (80/443) بشكل مباشر بسبب إدارة ServBay لعدة مواقع عبر تلك المنافذ.
3. أوامر التشخيص:
   • ngrok config check: تحقق من صحة صيغة ملف إعدادات Ngrok (~/.config/ngrok/ngrok.yml).
   • ngrok logs: راقب السجلات التفصيلية مباشرة عبر الطرفية لتشخيص مشكلات الاتصال أو توجيه الطلبات.
4. الأمان: يجب التشغيل بحذر عند مشاركة الخدمات محليًا عبر الإنترنت. تأكد من أمان الخدمة المكشوفة وشغل النفق مؤقتًا فقط عند الحاجة. تقدم الخطط المدفوعة أدوات إضافية كقوائم السماح بالـ IP وحدود الوصول لمستوى أعلى من الحماية.

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

الظاهرة	الحلول المحتملة
انتهاء المهلة أو عدم تحميل الصفحة	تحقق من تشغيل موقع ServBay المحلي وإمكانية الوصول إليه عبر نطاقه المحلي (مثلاً https://servbay.local من المتصفح). افحص سيرفر الويب (Caddy أو Nginx) وتأكد من عدم حجب الاتصال عبر جدار الحماية.
خطأ في شهادة HTTPS (تحذير المتصفح)	يحصل Ngrok تلقائيًا على شهادة صالحة لنطاقك. أي خطأ متعلق غالبًا بإعداد النفق أو الشبكة وليس مشكلة في ServBay. تأكد من استخدام عنوان Ngrok يبدأ بـ https://. أما ظهور الخطأ عند الدخول على الدومين المحلي فيستلزم مراجعة إعدادات SSL في ServBay.
انقطاع متكرر أو بطء الاتصال	افحص استقرار اتصال الإنترنت المحلي لديك. التقلبات قد تؤدي لانقطاع النفق. يفضل ربط الجهاز بشبكة سلكية لمزيد من الثبات. للمهام الحساسة، يوصى بخطة Ngrok المدفوعة.
الوصول للصفحة الافتراضية لـ ServBay بدل الموقع الحقيقي	تحقق من دقة عنوان <LOCAL_ENDPOINT> في أمر ngrok http وكذلك صحة قيمة <VIRTUAL_HOST> في --request-header-add='host: <VIRTUAL_HOST>'. هذا مهم لتوجيه الطلب للموقع الصحيح ضمن ServBay.

الأسئلة الشائعة (FAQ)

• س: هل يمكن ربط خدمات قواعد البيانات الخاصة بـ ServBay عبر Ngrok؟

  ج: يدعم Ngrok في الأساس بروتوكولات HTTP/HTTPS للأنفاق، ويدعم TCP للخدمات مثل قواعد البيانات، لكنه خارج نطاق هذا الدليل، ولا يُنصح عمومًا بفتح قواعد البيانات مباشرة للإنترنت لدواعي الأمان. استخدم نفق SSH أو حلول أكثر أمانًا إن كنت بحاجة لذلك.

• س: هل يتغير اسم النطاق العلني مع كل تشغيل لـ Ngrok؟

  ج: في الخطة المجانية، يتم تخصيص نطاق فرعي عشوائي من ngrok-free.app في كل مرة. للدومينات الثابتة، اشترك في حساب Ngrok وقم بإعداد نطاق خاص أو الترقية للخطة المدفوعة.

• س: هل يؤثر Ngrok على أداء ServBay المحلي؟

  ج: هناك زيادة طفيفة في زمن الاستجابة بسبب تمرير الطلبات عبر خوادم Ngrok، لكنها مقبولة لمهام التطوير والاختبار والعرض. الأداء المحلي يعتمد بشكل رئيسي على عتاد جهازك وكفاءة الموقع/التطبيق.

الخلاصة

من خلال دمج Ngrok، يمكن لمطوري ServBay مشاركة مواقعهم وخدماتهم المحلية بأمان وكفاءة عبر الإنترنت دون التعامل مع إعدادات الشبكة المعقدة. هذه الحلول مثالية للتعاون عن بعد، العروض لعملاء خارجيين، أو اختبار التكامل مع أنظمة خارجية. يمنحك Ngrok أدوات لمراقبة حركة المرور وتأمينها (بعضها عبر الخطط المدفوعة). أما بالنسبة للتطبيقات المهنية أو متطلبات النطاق الثابت، فيُنصح بالترقية إلى الخطط المدفوعة للاستمتاع بمزيد من الاستقرار والميزات المتقدمة.