🗺️ تثبيت GraphHopper — محرك توجيه واتجاهات ذاتي الاستضافة

انشر GraphHopper على Ubuntu بـ Docker — محرك توجيه ذاتي الاستضافة يوفر اتجاهات تفصيلية وواجهة برمجية للاتجاهات من بيانات OpenStreetMap، على المنفذ 8990.

⚠️ راجع أي سكريبت دائمًا قبل تشغيله على سيرفرك، واختبره في بيئة تجريبية أولاً.

📦 الملفات والأكواد المطلوبة

قبل البدء، يرجى التأكد من تحميل الأكواد المطلوبة من مستودعنا على GitHub لتتمكن من تطبيق الخطوات مع الفيديو بسهولة.

سكريبت تثبيت آلي — أمر واحد ينشر GraphHopper على المنفذ 8990 من منطقة OSM (موناكو افتراضياً). التشغيل الأول يبني رسماً بيانياً للتوجيه، وهذا يستغرق دقائق قليلة.
عرض على GitHub

التثبيت السريع:

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/maps/graphhopper/graphhopper-ubuntu.sh
chmod +x graphhopper-ubuntu.sh
./graphhopper-ubuntu.sh

خطوات التنفيذ

1 تحميل السكريبت

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/maps/graphhopper/graphhopper-ubuntu.sh

2 منحه صلاحية التنفيذ

chmod +x graphhopper-ubuntu.sh

3 تشغيل المثبّت

./graphhopper-ubuntu.sh

4 استخدام واجهة الويب وAPI التوجيه

http://your-server-ip:8990

المنافذ المستخدمة

المنفذالغرض
8990GraphHopper web UI and directions API (mapped from container port 8989)

نظرة عامة

GraphHopper محرك توجيه مفتوح المصدر مكتوب بلغة Java يحسب الاتجاهات بين نقطتين أو أكثر باستخدام بيانات OpenStreetMap. يعالج شبكة الطرق لمنطقة معينة إلى رسم بياني توجيه محسّن، ثم يجيب على استعلامات التوجيه — اتجاهات تفصيلية، والمسافة، والوقت المقدّر — عبر واجهة ويب لتوجيه نقطة لنقطة وواجهة برمجية JSON يمكن لتطبيقاتك استدعاءها مباشرة. يدعم ملفات تعريف سفر متعددة (سيارة، دراجة، مشي، وغيرها)، يطبّق كل منها القواعد المناسبة لوسيلة النقل تلك، ويمكنه التعامل مع أي شيء من مدينة واحدة إلى شبكة طرق دولة كاملة حسب العتاد الذي توفره له.

لماذا تستخدمه

واجهات التوجيه التجارية مثل Google Maps Directions أو Mapbox Directions تفرض رسوماً لكل طلب بمجرد تجاوز الفئة المجانية، وكل طلب يرسل نقطتي انطلاق ووجهة مستخدميك لطرف ثالث. يزيل GraphHopper كلا القلقين: تستضيف محرك التوجيه بنفسك على بيانات OpenStreetMap الخاصة بك، بحيث لا توجد فوترة لكل طلب ولا يرى أي طرف خارجي وجهة مستخدميك. مع سيرفر بلاطات (tile server) ذاتي الاستضافة (لعرض الخريطة) وNominatim (لبحث العناوين)، يكمل GraphHopper حزمة خرائط ذاتية الاستضافة بالكامل تستبدل عرض واستعلام واتجاهات Google Maps ببنيتك التحتية الخاصة.

متى تحتاجه

  • تبني حزمة خرائط ذاتية الاستضافة وتحتاج جزء الاتجاهات/التوجيه جنباً إلى جنب مع سيرفر بلاطات ومحدد جغرافي
  • تريد تجنب الفوترة لكل طلب من واجهات التوجيه التجارية مثل Google Maps Directions أو Mapbox
  • تحتاج اتجاهات توجيه لتطبيق إدارة أسطول أو لوجستيات أو توصيل دون كشف بيانات الرحلات لطرف ثالث
  • تريد اتجاهات تفصيلية لملفات تعريف السيارة والدراجة والمشي من بيانات OpenStreetMap الخاصة بك
  • تطوّر تطبيق خرائط وتحتاج واجهة برمجية اتجاهات يمكنك استدعاءها دون حدود معدل خارجية
  • تحتاج قدرة توجيه دون اتصال أو معزولة حيث لا يكون استدعاء واجهة برمجية خارجية خياراً

من يحتاجه

  • المطورون الذين يبنون تطبيقات خرائط أو لوجستيات ويحتاجون واجهة برمجية اتجاهات دون تكاليف لكل طلب
  • مستخدمو المختبرات المنزلية الذين يكملون حزمة خرائط ذاتية الاستضافة جنباً إلى جنب مع سيرفر بلاطات OSM ومحدد Nominatim الجغرافي
  • شركات اللوجستيات والتوصيل التي تريد توجيهاً دون إرسال بيانات الرحلات لواجهة برمجية تابعة لطرف ثالث
  • هواة تخطيط مسارات ركوب الدراجات والمشي الذين يريدون ملفات تعريف توجيه للدراجة والمشي على بنيتهم التحتية الخاصة
  • المستخدمون والمؤسسات المهتمون بالخصوصية الذين لا يريدون خروج بيانات الرحلات من سيرفراتهم
  • متخصصو نظم المعلومات الجغرافية (GIS) والباحثون الذين يحتاجون توجيهاً مخصصاً فوق مقتطف OpenStreetMap إقليمي معين
  • الشركات الصغيرة التي تبني أدوات داخلية تحتاج اتجاهات دون الاعتماد على تسعير واجهة Google Maps البرمجية

حالات الاستخدام الشائعة

  • توفير اتجاهات سيارة تفصيلية في تطبيق خرائط ذاتي الاستضافة
  • حساب مسارات دراجات لتطبيق ركوب دراجات يتجنب الطرق المخصصة للسيارات فقط ويستخدم مسارات ملائمة للدراجات
  • حساب اتجاهات مشي لميزة ملاحة للمشاة في تطبيق محلي
  • تشغيل حساب مسارات تطبيق توصيل أو لوجستيات دون تكاليف واجهة برمجية خارجية
  • العمل كطبقة توجيه في حزمة خرائط ذاتية الاستضافة كاملة جنباً إلى جنب مع سيرفر بلاطات وNominatim
  • اختبار وتطوير تطبيقات قائمة على الموقع تتطلب واجهة برمجية اتجاهات أثناء التطوير

الميزات الرئيسية

  • ملفات تعريف مركبات متعددة (سيارة، دراجة، مشي، وغيرها) مع تطبيق قواعد توجيه مناسبة لكل وسيلة تلقائياً
  • واجهة ويب للنقر التفاعلي على نقطتين على الخريطة وعرض المسار المحسوب
  • واجهة برمجية اتجاهات بصيغة JSON يمكن للتطبيقات استدعاءها مباشرة للاتجاهات التفصيلية والمسافة والوقت المقدّر للوصول
  • إيجاد مسار سريع عبر رسم بياني توجيه معالج مسبقاً، محسّن لاستجابات سريعة حتى على مناطق كبيرة
  • دعم ملفات تعريف توجيه وترجيح مخصصة، تتيح ضبطاً دقيقاً لتفضيلات مثل تجنب الطرق السريعة أو التلال
  • يعمل بالكامل من مقتطفات بيانات OpenStreetMap، من مدينة واحدة إلى دولة أو قارة كاملة
  • حساب مسارات بديلة، يُرجع أكثر من خيار مسار واحد بين نقطتين عند توفره
  • مفتوح المصدر برخصة Apache 2.0، قابل للاستخدام تجارياً دون رسوم ترخيص

كيفية الاستخدام بعد التثبيت

  • انتظر اكتمال بناء رسم بياني التوجيه عند التشغيل الأول — راجع السجلات، لأن GraphHopper لا يستطيع الإجابة على اتجاهات حتى ينتهي
  • افتح واجهة الويب على المنفذ 8990 وانقر نقطتين على الخريطة لاختبار مسار محسوب
  • استدعِ واجهة برمجية الاتجاهات مباشرة من تطبيقك، بتمرير إحداثيات البداية والنهاية وملف تعريف مركبة
  • بدّل ملف منطقة OSM إذا احتجت تغطية توجيه أبعد من مقتطف موناكو الافتراضي الذي يستخدمه سكريبت التثبيت
  • اختر ملف تعريف المركبة الصحيح (سيارة أو دراجة أو مشي) لكل طلب، لأن المسارات تختلف بشكل كبير حسب وسيلة السفر
  • راقب استهلاك الرام أثناء بناء الرسم البياني للمناطق الأكبر، لأن مقتطفات OSM الأكبر تحتاج ذاكرة أكثر للمعالجة
  • إذا كنت تدمجه مع سيرفر بلاطات وNominatim، اربط واجهتك الأمامية بالخدمات الثلاث للحصول على حزمة خرائط كاملة
  • ضع وكيلاً عكسياً بتحديد معدل أمام API إذا كنت تكشفه للاستخدام العام أو الإنتاجي

أفضل ممارسات الأمان

  • واجهة ويب وAPI في GraphHopper لا تملكان مصادقة مدمجة افتراضياً — قيّد الوصول على مستوى الشبكة أو الوكيل
  • لا تكشف المنفذ 8990 مباشرة للإنترنت دون تحديد معدل أبداً، لأن حساب التوجيه قد يكون مكثفاً للمعالج
  • ضع وكيلاً عكسياً بـ TLS أمام API لأي نشر عام أو إنتاجي
  • حدّد معدل طلبات API لمنع إساءة الاستخدام من سكريبتات آلية ترسل استعلامات توجيه مفرطة
  • حافظ على تحديث صورة GraphHopper في Docker لتحصل على تحسينات محرك التوجيه والتصحيحات الأمنية
  • إذا كنت توجّه بيانات رحلات حساسة (مثل مسارات التوصيل)، قيّد الوصول للشبكة على التطبيقات التي تحتاجها فقط
  • راقب استهلاك موارد السيرفر، لأن طلبات التوجيه الكبيرة أو الخبيثة على مناطق كبيرة يمكن أن تستهلك معالجاً وذاكرة كبيرين
  • تحقق من صحة وطهّر أي إحداثيات يوفرها المستخدم قبل تمريرها لـ API في تطبيق عام

المنافذ وإعدادات جدار الحماية

يستمع GraphHopper على منفذ المضيف 8990 في هذا النشر، معيّن من المنفذ الداخلي 8989 للحاوية، ويخدم واجهة الويب وواجهة برمجية الاتجاهات JSON على نفس المنفذ دون مصادقة مدمجة. لأي استخدام عام أو إنتاجي، ضع وكيلاً عكسياً بـ TLS وتحديد معدل أمام المنفذ 8990 بدلاً من كشفه مباشرة. على شبكة داخلية موثوقة أو للاستخدام الشخصي، قيّد المنفذ 8990 على شبكتك المحلية أو VPN بقواعد جدار ناري، لأن حساب التوجيه يمكن أن يستهلك معالجاً كبيراً إذا تُرك مفتوحاً لإساءة الاستخدام.

النسخ الاحتياطي والصيانة

  • انسخ احتياطياً docker-compose.yml أو أمر التشغيل حتى يمكن إعادة إنشاء منطقة OSM والإعداد الدقيقين بشكل مطابق
  • انسخ احتياطياً ملف مقتطف OSM المصدر (.pbf) الذي استخدمته لبناء رسم التوجيه البياني، لأنه مطلوب لإعادة البناء إذا فُقد الرسم البياني
  • الرسم البياني للتوجيه المبني نفسه يمكن إعادة توليده من مقتطف OSM، لذا عادة لا حاجة لنسخه احتياطياً بشكل منفصل
  • وثّق أي منطقة OSM وملفات تعريف مركبات أعددتها، تحسباً لاحتياج إعادة بناء الإعداد من الصفر
  • إذا خصّصت ملفات تعريف التوجيه أو الترجيح، انسخ ملف الإعداد ذاك احتياطياً لأنه ليس جزءاً من بيانات OSM
  • إعادة تشغيل سكريبت التثبيت بنفس منطقة OSM كافية عادة لاستعادة الوظائف الكاملة

الأخطاء الشائعة

  • توقع مسارات فوراً بعد بدء الحاوية دون انتظار اكتمال بناء رسم التوجيه البياني عند التشغيل الأول
  • نسيان أن سكريبت التثبيت يستخدم منطقة موناكو الافتراضية في OSM، ثم التساؤل عن سبب فشل التوجيه خارج تلك المنطقة
  • كشف المنفذ 8990 مباشرة للإنترنت دون تحديد معدل، مما يسمح لطلبات توجيه مكثفة للمعالج بإثقال السيرفر
  • استخدام ملف تعريف مركبة خاطئ للاستخدام، مثل حساب مسار دراجة بملف تعريف السيارة والحصول على نتائج مضللة
  • التقليل من تقدير الرام المطلوبة لمنطقة OSM كبيرة، مما يسبب فشل بناء رسم التوجيه البياني أو بطئه الشديد
  • عدم تقييد الوصول لـ API، تاركاً نقطة نهاية توجيه عامة يستطيع أي شخص استعلامها دون حدود
  • افتراض أن GraphHopper يتضمن بلاطات خريطة أو بحث عناوين مباشرة — إنه يوفر فقط التوجيه، وليس العرض أو الترميز الجغرافي
  • إعادة بناء رسم التوجيه البياني دون داعٍ عند كل إعادة تشغيل بدلاً من تخزينه مؤقتاً، مما يهدر وقتاً على المناطق الكبيرة

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

  • لا تُرجع أي مسارات — راجع السجلات للتأكد أن بناء رسم التوجيه البياني عند التشغيل الأول اكتمل فعلاً بنجاح
  • التوجيه يفشل لمواقع خارج المنطقة المتوقعة — تأكد أن ملف منطقة OSM يغطي المنطقة التي توجّه فيها
  • واجهة الويب غير متاحة — تحقق أن المنفذ 8990 معيّن بشكل صحيح وغير محظور بجدار ناري المضيف
  • بناء الرسم البياني يستغرق وقتاً طويلاً جداً أو يفشل — تحقق من الرام المتاحة، لأن مناطق OSM الأكبر تتطلب ذاكرة أكبر بكثير
  • مسارات الدراجة أو المشي تبدو مطابقة لمسارات السيارة — تأكد أنك تحدد ملف تعريف المركبة الصحيح في طلب API
  • طلبات API تنتهي مهلتها — تحقق من حمل معالج السيرفر، لأن استعلامات التوجيه المعقدة على مناطق كبيرة يمكن أن تكون مكلفة حسابياً
  • مسارات غير متوقعة أو غير مثالية — راجع ترجيح ملف تعريف التوجيه، لأن الإعدادات الافتراضية قد لا تطابق تفضيلاتك (مثل تجنب الطرق السريعة)
  • إعادة تشغيل الحاوية تُشغّل إعادة بناء كاملة للرسم البياني — تأكد أن دليل تخزين الرسم البياني المؤقت محفوظ في حجم بدلاً من إعادة إنشائه كل مرة

البدائل

OSRM (Open Source Routing Machine) محرك توجيه مفتوح المصدر شائع آخر يركّز بقوة على السرعة الخام، رغم أن دعم GraphHopper متعدد الملفات التعريفية وتكامله مع نظام Java البيئي غالباً أسهل للتعامل معه. Valhalla محرك توجيه أغنى بالميزات من جهود Mapbox المفتوحة المصدر، يوفر خيارات أكثر تقدماً بتكلفة إعداد أكثر تعقيداً. الواجهات البرمجية التجارية مثل Google Maps Directions أو Mapbox Directions توفر توجيهاً مصقولاً بدون إعداد لكنها تفرض رسوماً لكل طلب وتوجّه بيانات رحلات مستخدميك عبر طرف ثالث. لمحرك توجيه ذاتي الاستضافة ومُصان بنشاط بواجهة ويب بسيطة وواجهة برمجية مباشرة، يبقى GraphHopper من أكثر الخيارات سهولة.

متى لا تستخدمه

إذا احتجت تغطية توجيه للكوكب بأكمله دون إدارة مقتطفات OSM وموارد سيرفر خاصة بك، فقد تكون واجهة برمجية تجارية مثل Google Maps Directions أبسط رغم تكلفة كل طلب. إذا كانت سرعة التوجيه الخام على نطاق ضخم همّك الأساسي وتتقبل إعداداً أكثر تعقيداً، فقد يناسب OSRM أو Valhalla عمليات النشر الإنتاجية الكبيرة بشكل أفضل. إذا كنت تحتاج اتجاهات بشكل عرضي فقط ولا تريد صيانة بنية تحتية لرسم التوجيه البياني، فقد يكون تضمين أداة خريطة تجارية عبئاً أقل من استضافة GraphHopper ذاتياً.

هل تحتاج مساعدة احترافية؟

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

  • التثبيت وتجهيز السيرفر
  • الإعداد المتقدم وإعداد التوجيه
  • تصليب الأمان وتحسين جدار الحماية
  • إعداد شهادات SSL/TLS مع Let's Encrypt
  • ربط النطاق المخصص والوكيل العكسي
  • جدولة النسخ الاحتياطي التلقائي والتعافي من الكوارث
  • المراقبة الفورية وتنبيهات الجاهزية
  • الترحيل من المنصات القائمة
  • استكشاف مشكلات الاتصال والأداء وإصلاحها
  • سكريبتات أتمتة مخصصة وعقود دعم مستمر
تواصل مع PrismaTechWork

الأسئلة الشائعة

ما هو GraphHopper؟

GraphHopper محرك توجيه — يحسب الاتجاهات بين نقاط ويُرجع تعليمات تفصيلية والمسافة والوقت المقدّر، من بيانات OpenStreetMap. إنه الجزء الذي يجيب على سؤال "كيف أصل من أ إلى ب؟" في إعداد الخرائط. يوفر واجهة ويب لتوجيه نقطة لنقطة وواجهة برمجية اتجاهات يمكن لتطبيقك استدعاءها، بدعم ملفات تعريف السيارة والدراجة والمشي.

ما المنفذ الذي يستخدمه؟

يعمل GraphHopper على منفذ المضيف 8990، معيّن من منفذ الحاوية 8989 — لاحظ أن منفذ المضيف مختلف. افتح http://your-server:8990 لواجهة الويب، حيث يمكنك النقر على نقطتين لرؤية مسار، أو استدعِ واجهة برمجية الاتجاهات على ذلك العنوان من تطبيقك. للاستخدام العام، ضع وكيلاً عكسياً بـ TLS أمامه وحدّد معدل API.

ما هو رسم التوجيه البياني ولماذا يستغرق التشغيل الأول وقتاً؟

عند التشغيل الأول يعالج GraphHopper منطقة OpenStreetMap الخاصة بك إلى رسم توجيه بياني — تمثيل لشبكة الطرق محسّن لإيجاد المسار بسرعة. بناؤه يستغرق دقائق قليلة لمنطقة صغيرة ووقتاً أطول لمنطقة كبيرة، والمناطق الأكبر تحتاج رام أكثر. حتى يُبنى الرسم البياني، لا يستطيع GraphHopper إرجاع مسارات، لذا راقب السجلات ودع التشغيل الأول يكتمل.

هل يمكنه التوجيه للدراجات والمشي، وليس السيارات فقط؟

نعم — يدعم GraphHopper ملفات تعريف مركبات متعددة تشمل السيارة والدراجة والمشي، يطبّق كل منها القواعد المناسبة بحيث يستطيع مثلاً مسار الدراجة استخدام مسارات لا تستطيع السيارة استخدامها ويتجاهل مسار المشي اتجاهات الشوارع ذات الاتجاه الواحد. تختار ملف التعريف لكل طلب، وهذا مهم لأن أفضل مسار يختلف كثيراً حسب وسيلة السفر. استخدام ملف تعريف خاطئ سبب شائع لمسارات مفاجئة.

كيف يتناسب مع سيرفر بلاطات وNominatim؟

يشكّلون معاً حزمة خرائط ذاتية الاستضافة كاملة. سيرفر بلاطات OSM يرسم الخريطة، وNominatim يوفر الترميز الجغرافي (بحث العناوين)، وGraphHopper يوفر التوجيه (الاتجاهات). معاً يستبدلون العرض والبحث والاتجاهات لمنصة خرائط تجارية مثل Google Maps، كلها على سيرفراتك الخاصة باستخدام بيانات OpenStreetMap، دون فوترة لكل طلب مع بقاء الرحلات خاصة.