🔌 تثبيت Hoppscotch — أداة اختبار API ذاتية الاستضافة (بديل Postman)
انشر Hoppscotch على Ubuntu باستخدام Docker — عميل API سريع ومفتوح المصدر لاختبار REST وGraphQL وWebSocket والمزيد، ذاتي الاستضافة بالكامل مع مساحات عمل جماعية على سيرفرك الخاص.
📦 الملفات والأكواد المطلوبة
قبل البدء، يرجى التأكد من تحميل الأكواد المطلوبة من مستودعنا على GitHub لتتمكن من تطبيق الخطوات مع الفيديو بسهولة.
التثبيت السريع:
wget https://raw.githubusercontent.com/mhmdali94/Docker/refs/heads/main/dev/hoppscotch/hoppscotch-ubuntu.sh
chmod +x hoppscotch-ubuntu.sh
sudo bash hoppscotch-ubuntu.sh
خطوات التنفيذ
1 تحميل السكريبت
wget https://raw.githubusercontent.com/mhmdali94/Docker/refs/heads/main/dev/hoppscotch/hoppscotch-ubuntu.sh
2 منحه صلاحية التنفيذ
chmod +x hoppscotch-ubuntu.sh
3 تشغيل المثبت
يثبّت السكريبت Docker إن لزم، ويُشغّل قاعدة بيانات PostgreSQL، ثم يُطلق تطبيق Hoppscotch وواجهة API الخلفية ولوحة تحكم المسؤول كحاويات منفصلة.
sudo bash hoppscotch-ubuntu.sh
4 الدخول إلى واجهة الويب
افتح المتصفح وانتقل إلى التطبيق، ثم سجّل حساب المسؤول الأول عبر لوحة تحكم المسؤول:
http://:3000 # app
http://:3100 # admin dashboard (register first admin here)
المنافذ المستخدمة
| المنفذ | الغرض |
|---|---|
| 3000 | Hoppscotch app UI |
| 3100 | Admin dashboard |
| 3170 | Backend API (must be reachable by browsers) |
| 5432 | PostgreSQL (internal only) |
نظرة عامة
Hoppscotch نظام بيئي مجاني ومفتوح المصدر لتطوير واختبار واجهات API مبني بـ Vue.js — بديل خفيف وسريع لـ Postman وInsomnia. يدعم اختبار طلبات REST وGraphQL وWebSocket وأحداث الخادم المرسلة (SSE) وSocket.IO وMQTT وgRPC من واجهة واحدة. تُنشر نسخة المجتمع ذاتية الاستضافة كأربعة أجزاء — تطبيق واجهة أمامية، وواجهة API خلفية، ولوحة تحكم مسؤول، وقاعدة بيانات PostgreSQL — لتمنحك مساحات عمل جماعية ومجموعات مشتركة وسجل طلبات بالكامل على بنيتك التحتية الخاصة بدلاً من نسخة Hoppscotch السحابية العامة.
لماذا تستخدمه
Hoppscotch أخف وأسرع بشكل ملحوظ من Postman، إذ يُحمَّل في المتصفح فوراً تقريباً دون العبء الذي يفرضه تطبيق سطح مكتب مبني بـ Electron. استضافته ذاتياً تُبقي طلبات API الخاصة بك ورموز المصادقة وعناوين النقاط الداخلية بعيدة تماماً عن أي خدمة سحابية لطرف ثالث — وهذا مهم للفرق التي تختبر واجهات API داخلية أو بيئات تجريبية أو أي شيء مشمول باتفاقية عدم إفصاح. إنه مفتوح المصدر بالكامل برخصة MIT دون حدود مصطنعة على المجموعات أو الطلبات في نسخة المجتمع، وتمنحك لوحة تحكم المسؤول تحكماً في حسابات المستخدمين وعضوية مساحات العمل تماماً كما يجب أن تكون عليه أداة داخلية.
متى تحتاجه
- فريقك يختبر واجهات API داخلية أو تجريبية ولا يريد أن تغادر بيانات الطلبات بنيتك التحتية إلى أداة SaaS عامة
- تريد عميل API خفيف يعمل بالمتصفح بدلاً من تثبيت تطبيق ثقيل مبني بـ Electron مثل Postman
- تحتاج مساحات عمل ومجموعات جماعية مشتركة دون الدفع مقابل خطة Postman Team أو Enterprise
- تختبر أكثر من REST — GraphQL وWebSocket وSSE أو MQTT — وتريد أداة واحدة تغطيها جميعاً
- تريد أن يُحفظ سجل الطلبات والمجموعات على قاعدة بياناتك الخاصة بدلاً من حساب لدى طرف ثالث
- مؤسستك لديها سياسة تمنع إرسال بيانات اعتماد API أو الروابط الداخلية عبر أدوات SaaS خارجية
من يحتاجه
- مطورو الواجهات الخلفية وAPI الذين يختبرون نقاط النهاية يومياً ويريدون عميل طلبات سريعاً وسهل الاستخدام بلوحة المفاتيح
- فرق ضمان الجودة والاختبار التي تحتاج مجموعات وبيئات مشتركة عبر الفريق بأكمله
- فرق DevOps والمنصات التي تريد أداة اختبار API داخلية لا تعتمد على سحابة طرف ثالث
- الشركات الناشئة والوكالات التي تريد وظائف شبيهة بـ Postman دون تسعير SaaS لكل مستخدم
- الفرق المهتمة بالأمان التي تعمل مع واجهات API داخلية أو تجريبية أو مشمولة باتفاقية عدم إفصاح لا يمكنها لمس خدمات خارجية
- الطلاب والمطورون الذين يتعلمون تصميم API ويريدون أداة مجانية ومفتوحة المصدر دون حدود حساب
حالات الاستخدام الشائعة
- بناء وتنظيم طلبات REST API ضمن مجموعات مشتركة عبر فريق التطوير بأكمله
- اختبار استعلامات وتعديلات GraphQL مع استبطان المخطط (schema introspection) ومحرر استعلامات مدمج
- تصحيح ميزات الوقت الفعلي بالاتصال المباشر بنقاط نهاية WebSocket أو Socket.IO أو Server-Sent Events
- توليد مقتطفات كود جاهزة للاستخدام (curl، fetch، Axios، Python requests، والمزيد) لأي طلب
- استيراد مجموعات Postman أو Insomnia الموجودة لترحيل سير عمل اختبار API الخاص بالفريق
- تشغيل المجموعات ضمن خطوط أنابيب CI/CD باستخدام Hoppscotch CLI لاختبار API آلي
- إدارة متغيرات البيئة لكل مرحلة (تطوير، تجريبي، إنتاج) دون كتابة الروابط والرموز بشكل ثابت في الكود
الميزات الرئيسية
- دعم REST وGraphQL وWebSocket وSSE وSocket.IO وMQTT وgRPC في واجهة موحدة واحدة
- مساحات عمل جماعية مع مجموعات وبيئات وسجل طلبات مشترك في الواجهة الخلفية ذاتية الاستضافة
- توليد كود للطلبات بعشرات اللغات ومكتبات عملاء HTTP
- لوحة تحكم مسؤول لإدارة حسابات المستخدمين وعضوية مساحات العمل وإعدادات النسخة بأكملها
- استيراد وتصدير متوافق مع تنسيقات Postman وInsomnia وOpenAPI وHAR
- إضافة متصفح متاحة لتجاوز قيود CORS عند اختبار واجهات API محلية أو داخلية
- أداة سطر أوامر Hoppscotch CLI لتشغيل المجموعات المحفوظة بدون واجهة ضمن خطوط أنابيب CI/CD
- واجهة داكنة وسريعة تعتمد على لوحة المفاتيح بزمن تحميل شبه معدوم مقارنة بالعملاء المبنية على Electron
كيفية الاستخدام بعد التثبيت
- افتح لوحة تحكم المسؤول على http://your-server-ip:3100 أولاً وسجّل حساب المسؤول الأولي
- سجّل الدخول إلى التطبيق الرئيسي على http://your-server-ip:3000 باستخدام نفس بيانات الحساب
- أنشئ مساحة عمل جماعية تحت Team Workspaces إذا أردت مشاركة المجموعات بين عدة مستخدمين
- أعدّ متغيرات البيئة لكل مرحلة (تطوير، تجريبي، إنتاج) حتى لا تُكتب الروابط والرموز بشكل ثابت في الطلبات
- استورد مجموعات Postman أو Insomnia الموجودة عبر خيار الاستيراد إذا كنت تُرحّل سير عمل قائم
- ادعُ أعضاء الفريق من لوحة تحكم المسؤول حتى يتمكنوا من تسجيل الدخول والوصول لمساحات العمل المشتركة
- اضبط مزودي المصادقة (البريد الإلكتروني، Google، GitHub) في متغيرات بيئة الواجهة الخلفية إذا أردت تسجيل دخول موحد SSO
- أضف رابط التطبيق للإشارات المرجعية أو إلى Homepage/لوحة تحكمك الداخلية للوصول السريع اليومي
أفضل ممارسات الأمان
- لا تكشف لوحة تحكم المسؤول (المنفذ 3100) للإنترنت العام أبداً — فهي تتحكم بحسابات المستخدمين وإعدادات النسخة
- ضع كل خدمات Hoppscotch خلف وكيل عكسي مع HTTPS، لأن بيانات الاعتماد ورموز API تمر عبر التطبيق
- قيّد التسجيل إذا كنت لا تريد نسخة تسجيل مفتوحة — اضبط طرق التسجيل المسموح بها في متغيرات بيئة الواجهة الخلفية
- استخدم كلمات مرور قوية وفريدة لقاعدة بيانات PostgreSQL وجدّد سر JWT الذي تستخدمه الواجهة الخلفية بشكل دوري
- حدّث صور الواجهة الخلفية والتطبيق ولوحة تحكم المسؤول معاً، لأنها تُصدر كمجموعة متطابقة الإصدارات
- اقصر عضوية مساحة العمل على من يحتاجون فعلاً الوصول للمجموعات المشتركة وبيانات الاعتماد المحفوظة
- إذا كان فريقك يخزّن مفاتيح أو رموز API داخل المجموعات، تعامل مع النسخة بأكملها كبيانات حساسة وقيّد الوصول للشبكة تبعاً لذلك
المنافذ وإعدادات جدار الحماية
يستخدم مكدس Hoppscotch ذاتي الاستضافة أربعة منافذ: 3000 لواجهة التطبيق الرئيسية، و3100 للوحة تحكم المسؤول، و3170 لواجهة API الخلفية (التي يجب أن يصلها المتصفح مباشرة)، و5432 لـ PostgreSQL التي يجب أن تبقى داخلية لشبكة Docker ولا تُنشر خارجياً أبداً. لا ينبغي كشف أي من المنافذ المواجهة للعامة مباشرة للإنترنت دون HTTPS — ضع وكيلاً عكسياً مثل Nginx Proxy Manager أمام المنافذ 3000 و3100 و3170، كل واحد على نطاق فرعي خاص به مع شهادة SSL صالحة، لأن واجهة API الخلفية يجب أن يصلها المتصفح أيضاً عبر HTTPS حتى يعمل التطبيق بشكل صحيح. احظر الوصول المباشر لكل المنافذ الأربعة في جدار الحماية واسمح بحركة المرور فقط عبر الوكيل العكسي.
النسخ الاحتياطي والصيانة
- انسخ قاعدة بيانات PostgreSQL احتياطياً بانتظام باستخدام pg_dump — فهي تحتوي كل المجموعات ومساحات العمل والبيئات وحسابات المستخدمين
- انسخ ملف docker-compose.yml وأي ملفات .env تحتوي أسراراً مثل مفتاح JWT وبيانات اعتماد قاعدة البيانات احتياطياً
- خزّن نسخ قاعدة البيانات الاحتياطية خارج السيرفر وشفّرها، لأنها قد تحتوي رموز API محفوظة داخل الطلبات
- صدّر المجموعات الحرجة دورياً إلى JSON كنسخة احتياطية ثانوية قابلة للقراءة البشرية ومستقلة عن قاعدة البيانات
- وثّق إعداد الوكيل العكسي والنطاقات الفرعية للتطبيق والواجهة الخلفية ولوحة تحكم المسؤول حتى يمكن إعادة إنشائها
- اختبر استعادة نسخة PostgreSQL على نسخة منفصلة وتأكد من عودة مساحات العمل والمجموعات سليمة
الأخطاء الشائعة
- كشف واجهة API الخلفية (المنفذ 3170) دون HTTPS، لأن المتصفح يحتاج الوصول إليها مباشرة وهي تحمل كل البيانات
- ترك لوحة تحكم المسؤول على المنفذ 3100 مفتوحة للإنترنت العام بدلاً من تقييدها على الشبكات الموثوقة
- نسيان أن الواجهة الأمامية والخلفية ولوحة تحكم المسؤول يجب أن تكون كل منها قابلة للوصول عبر نطاقها الفرعي الخاص عند وضعها خلف وكيل عكسي
- عدم ضبط سر JWT قوي في إعداد الواجهة الخلفية، ما يُضعف أمان الجلسات
- نشر منفذ PostgreSQL 5432 خارجياً بدلاً من إبقائه داخلياً في شبكة Docker
- تخزين مفاتيح API الإنتاجية الحساسة مباشرة داخل مجموعات الفريق المشتركة دون مراعاة من يملك الوصول لمساحة العمل
- تخطي النسخ الاحتياطي لقاعدة البيانات وفقدان كل مجموعة وبيئة محفوظة بعد عطل السيرفر
- تشغيل إصدارات غير متطابقة من صور التطبيق والواجهة الخلفية ولوحة تحكم المسؤول، ما يسبب أخطاء غير متوقعة
استكشاف الأخطاء وإصلاحها
- التطبيق يُحمَّل لكن الطلبات تفشل — تحقق أن رابط API الخلفية مضبوط بشكل صحيح وقابل للوصول عبر HTTPS من المتصفح
- لا يمكن تسجيل الدخول للوحة تحكم المسؤول — تأكد أن المنفذ 3100 قابل للوصول وأن حساب المسؤول الأولي سُجّل بشكل صحيح
- أخطاء CORS عند اختبار واجهات API محلية — ثبّت إضافة متصفح Hoppscotch لتجاوز قيود CORS بالمتصفح
- ميزات مساحة العمل الجماعية مفقودة — تأكد أنك تستخدم الواجهة الخلفية ذاتية الاستضافة وأنك مسجّل دخول، وليس فقط الواجهة الأمامية المستقلة
- اتصالات WebSocket أو SSE تفشل — تحقق أن نقطة النهاية المستهدفة قابلة للوصول من السيرفر المُستضيف لـ Hoppscotch وليس فقط من جهازك المحلي
- أخطاء اتصال بقاعدة البيانات عند بدء التشغيل — تحقق أن حاوية PostgreSQL سليمة وأن سلسلة الاتصال في بيئة الواجهة الخلفية مطابقة
- مجموعة Postman المستوردة تفتقد طلبات — تحقق من ميزات خاصة بـ Postman غير مدعومة وأعد التصدير باستخدام تنسيق متوافق
- المستخدمون لا يستطيعون التسجيل أو تسجيل الدخول — تحقق من مزودي المصادقة المسموح بهم المضبوطين في متغيرات بيئة الواجهة الخلفية
البدائل
Postman هو عميل API الأكثر استخداماً بأوسع مجموعة ميزات وتعاون جماعي ناضج، لكنه يتطلب حساباً ويُمرّر الاستخدام عبر سحابة Postman ويقفل ميزات الفريق المتقدمة خلف خطط مدفوعة. Insomnia بديل قوي مفتوح المصدر جزئياً بتطبيق سطح مكتب مصقول، لكن ميزات مزامنة الفريق فيه تتطلب حساباً مدفوعاً أيضاً. Bruno عميل API أحدث يعمل بلا اتصال بالكامل ويخزّن المجموعات كملفات نصية عادية في مستودعك بدلاً من قاعدة بيانات، وهذا يروق للمطورين الذين يريدون مجموعات أصيلة لـ Git. كأداة ذاتية الاستضافة بالكامل ومفتوحة المصدر بمساحات عمل جماعية ودون تسعير SaaS لكل مستخدم، Hoppscotch هو الخيار الأقوى — خاصة للفرق التي تحتاج دعماً متعدد البروتوكولات يتجاوز REST العادي.
متى لا تستخدمه
إذا كان فريقك مرتاحاً لسحابة Postman وخطته الجماعية المدفوعة ولا توجد لديه مخاوف بشأن إقامة البيانات، فقد يفوق نضج Postman ومنظومة إضافاته فوائد الاستضافة الذاتية. إذا كنت تختبر واجهات API أحياناً فقط ولا تحتاج مساحات عمل جماعية، فقد يكون تطبيق ويب Hoppscotch العام المجاني على hoppscotch.io أبسط من تشغيل نسختك الخاصة. إذا كنت تفضّل مجموعات أصيلة لـ Git مخزّنة كملفات بدلاً من قاعدة بيانات، فأداة مثل Bruno تناسب سير العمل هذا بشكل أفضل. وإذا لم تكن لديك القدرة التشغيلية لصيانة قاعدة بيانات PostgreSQL ووكيل عكسي وحاويات متعددة، فإن عميل API بنظام SaaS مُستضاف يُزيل عبء الصيانة هذا بالكامل.
هل تحتاج مساعدة احترافية؟
توفر PrismaTechWork خدمات بنية تحتية شاملة — من النشر الأولي وتصليب الأمان إلى المراقبة المستمرة والنسخ الاحتياطي التلقائي والدعم المخصص. سواء كنت تحتاج إعداد سيرفر واحد أو شبكة متعددة المواقع، يضمن فريقنا بناء بنيتك التحتية بشكل صحيح وتأمينها بالشكل المناسب وصيانتها باستمرار.
- التثبيت وتجهيز السيرفر
- الإعداد المتقدم وإعداد التوجيه
- تصليب الأمان وتحسين جدار الحماية
- إعداد شهادات SSL/TLS مع Let's Encrypt
- ربط النطاق المخصص والوكيل العكسي
- جدولة النسخ الاحتياطي التلقائي والتعافي من الكوارث
- المراقبة الفورية وتنبيهات الجاهزية
- الترحيل من المنصات القائمة
- استكشاف مشكلات الاتصال والأداء وإصلاحها
- سكريبتات أتمتة مخصصة وعقود دعم مستمر
الأسئلة الشائعة
هل Hoppscotch مجاني ومفتوح المصدر؟
نعم. نسخة المجتمع من Hoppscotch مفتوحة المصدر بالكامل برخصة MIT ومجانية للاستضافة الذاتية دون حدود مصطنعة على الطلبات أو المجموعات. تقدّم Hoppscotch أيضاً نسخة Enterprise مدفوعة بميزات إضافية لتسجيل الدخول الموحد SSO وإدارة المؤسسات للشركات الكبيرة.
ما الفرق بين حاويات التطبيق والواجهة الخلفية ولوحة تحكم المسؤول؟
التطبيق (المنفذ 3000) هو الواجهة الرئيسية حيث تبني الطلبات وترسلها. الواجهة الخلفية (المنفذ 3170) هي سيرفر API الذي يشغّل مساحات العمل الجماعية والمصادقة وتخزين البيانات في PostgreSQL. لوحة تحكم المسؤول (المنفذ 3100) هي حيث يُنشأ حساب المسؤول الأول وحيث تدير المستخدمين وإعدادات النسخة.
هل يمكنني استيراد مجموعات Postman الموجودة لدي؟
نعم. يدعم Hoppscotch استيراد المجموعات من Postman وInsomnia ومواصفات OpenAPI وملفات HAR، ما يجعل ترحيل سير عمل اختبار API الحالي لفريقك مباشراً دون البدء من الصفر.
هل يدعم Hoppscotch اختبار GraphQL وWebSocket، وليس فقط REST؟
نعم. يملك Hoppscotch واجهات مخصصة لـ REST وGraphQL (مع استبطان المخطط) وWebSocket وServer-Sent Events وSocket.IO وMQTT وgRPC، كلها ضمن التطبيق نفسه.
هل أحتاج PostgreSQL للنسخة ذاتية الاستضافة؟
نعم، إذا أردت الواجهة الخلفية الكاملة بمساحات عمل جماعية ومجموعات مشتركة وسجل دائم. تخزّن PostgreSQL كل تلك البيانات. إذا احتجت فقط الواجهة الأمامية المستقلة دون ميزات جماعية، يمكنك تشغيل حاوية التطبيق فقط، لكنك ستفقد مشاركة مساحة العمل والسجل من جانب السيرفر.
