💻 تثبيت Hasura — واجهة GraphQL فورية فوق PostgreSQL

انشر Hasura على Ubuntu بـ Docker — محرك يولّد واجهة GraphQL جاهزة للإنتاج فوق قاعدة بيانات PostgreSQL تلقائياً، مع سر إداري مُولَّد، على المنفذ 8241.

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

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

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

سكريبت تثبيت آلي — أمر واحد ينشر Hasura مع PostgreSQL على المنفذ 8241 ويولّد سراً إدارياً من 32 حرفاً. افتح الكونسول عند /console.
عرض على GitHub

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

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

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

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

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/dev/hasura/hasura-ubuntu.sh

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

chmod +x hasura-ubuntu.sh

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

./hasura-ubuntu.sh

4 فتح الكونسول

http://your-server-ip:8241/console

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

المنفذالغرض
8241Hasura GraphQL API and web console at /console (mapped from container port 8080)
5432PostgreSQL — internal to the Docker network, not exposed to the host

نظرة عامة

Hasura محرك GraphQL مفتوح المصدر يتصل مباشرة بقاعدة بيانات PostgreSQL ويولّد فوراً واجهة GraphQL (وREST) كاملة وجاهزة للإنتاج — تشمل الاستعلامات والتعديلات والاشتراكات الفورية — عبر فحص مخطط قاعدة بياناتك الحالي. لا حاجة لكتابة أي كود resolver: يترجم Hasura عمليات GraphQL مباشرة إلى استعلامات SQL محسّنة. يأتي كحاوية Docker واحدة، ويضم كونسول ويب لاستكشاف مخططك وبناء صلاحيات دقيقة قائمة على الأدوار، ويمكنه أيضاً دمج منطق أعمال مخصص عبر Actions والمخططات البعيدة.

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

يلغي Hasura أسابيع من العمل المتكرر في الواجهة الخلفية التي عادة تُصرف على كتابة resolvers للعمليات الأساسية والترقيم والتصفية ومنطق الاشتراكات يدوياً. وجّهه لقاعدة بيانات PostgreSQL وستحصل على واجهة GraphQL كاملة النوع وقابلة للاستكشاف خلال ثوانٍ، مع اشتراكات فورية مدمجة عبر WebSockets ونظام صلاحيات دقيق يُفرض على مستوى قاعدة البيانات. للفرق التي تنمذج بياناتها بالفعل في PostgreSQL، يزيل Hasura طبقة كاملة من تطوير الواجهات البرمجية المخصصة، مع السماح بمنطق مخصص عبر Actions وEvent Triggers ودمج المخططات البعيدة عندما لا تكفي الواجهة المولّدة تلقائياً.

متى تحتاجه

  • لديك قاعدة بيانات PostgreSQL قائمة وتريد واجهة GraphQL (أو REST) مُولَّدة تلقائياً دون كتابة resolvers
  • تحتاج بيانات فورية — اشتراكات GraphQL عبر WebSockets — للوحات تحكم مباشرة أو الدردشة أو ميزات تعاونية
  • تريد صلاحيات دقيقة قائمة على الأدوار على مستوى الصفوف والأعمدة تُفرض باستمرار عبر جميع العملاء
  • تحتاج دمج مخطط قاعدة بياناتك مع منطق أعمال مخصص عبر دوال خدمية (Actions) أو خدمات خارجية (remote schemas)
  • تريد تشغيل webhooks أو مهام خلفية تلقائياً عند إدراج أو تعديل أو حذف صفوف في قاعدة البيانات (Event Triggers)
  • فريق الواجهة الأمامية لديك يريد التقدم بسرعة مقابل واجهة موثّقة ذاتياً وقوية النوع دون انتظار نقاط نهاية الواجهة الخلفية
  • تحتاج توحيد مصادر بيانات متعددة (Postgres وMySQL وواجهات GraphQL/REST بعيدة) خلف نقطة نهاية GraphQL واحدة

من يحتاجه

  • مطورو الواجهة الكاملة والأمامية الذين يريدون واجهة فورية وقوية النوع فوق PostgreSQL دون كتابة كود خلفي يدوياً
  • الشركات الناشئة والفرق الصغيرة التي تحتاج إطلاق نسخة أولية بسرعة دون تخصيص مهندسين لتطوير واجهات CRUD
  • الفرق التي تبني تطبيقات فورية — دردشة، لوحات تحكم مباشرة، أدوات تعاونية — وتحتاج اشتراكات GraphQL جاهزة
  • مهندسو الواجهة الخلفية الذين يريدون تحكم وصول دقيق وقابل للتدقيق قائم على الأدوار يُفرض مركزياً بدلاً من كود التطبيق
  • الشركات المهاجرة من REST إلى GraphQL التي تريد مساراً تدريجياً باستخدام المخططات البعيدة جنباً إلى جنب مع الخدمات الحالية
  • فرق البيانات التي تحتاج كشف بيانات PostgreSQL الداخلية بأمان لأدوات داخلية أو تكاملات مع شركاء
  • المطورون الذين يبنون بنى قائمة على الأحداث ويريدون أن تُطلق تغييرات قاعدة البيانات webhooks تلقائياً

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

  • توليد واجهة GraphQL فورية فوق مخطط PostgreSQL قائم لتطبيق ويب أو جوال
  • بناء ميزات فورية — تتبع طلبات مباشر، دردشة، إشعارات — باستخدام اشتراكات GraphQL
  • فرض أمان على مستوى الصف بحيث لا يرى أو يعدّل كل دور مستخدم إلا البيانات المصرح له بها
  • تشغيل webhooks أو دوال خدمية تلقائياً عند أحداث الإدراج/التعديل/الحذف في قاعدة البيانات
  • دمج عمليات CRUD المولّدة تلقائياً مع منطق أعمال مخصص عبر Actions التي تستدعي واجهاتك البرمجية الخاصة
  • العمل كبوابة API توحّد بيانات PostgreSQL مع خدمات GraphQL أو REST بعيدة في مخطط واحد

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

  • توليد فوري لواجهة GraphQL وREST من فحص مخطط PostgreSQL — دون الحاجة لكتابة أي كود resolver
  • اشتراكات GraphQL فورية عبر WebSockets تدفع التحديثات المباشرة من قاعدة البيانات إلى العملاء
  • تحكم وصول قائم على الأدوار مع قواعد صلاحيات على مستوى الصف والعمود تُضبط لكل جدول ودور
  • Event Triggers تستدعي webhooks تلقائياً عند عمليات الإدراج أو التعديل أو الحذف في قاعدة البيانات
  • Actions لربط منطق أعمال مخصص وواجهات REST خارجية بمخطط GraphQL كعمليات أصلية
  • دمج مخططات بعيدة لتوحيد واجهة Hasura المولّدة تلقائياً مع خدمات GraphQL أخرى في نقطة نهاية واحدة
  • كونسول ويب مدمج لاستكشاف المخطط بصرياً واختبار الاستعلامات وإدارة الصلاحيات
  • تحسين تلقائي لأداء الاستعلامات يترجم GraphQL مباشرة إلى استعلام SQL واحد فعّال

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

  • احفظ السر الإداري الذي ولّده المثبّت — إنه المفتاح الرئيسي المطلوب لفتح الكونسول واستخدام واجهة Hasura
  • افتح الكونسول عند http://your-server-ip:8241/console وأدخل السر الإداري عند الطلب
  • تتبّع جداول PostgreSQL الحالية من Data — يسردها الكونسول تلقائياً وجاهزة للاستعلام عبر GraphQL
  • اضبط الصلاحيات لكل جدول ودور من تبويب Permissions قبل كشف الواجهة لأي تطبيق عميل
  • اختبر الاستعلامات والتعديلات في مستكشف API المدمج بأسلوب GraphiQL داخل الكونسول
  • اضبط Actions إذا احتجت منطق أعمال مخصص يتجاوز CRUD المولّد تلقائياً، وربطه بنقاط webhook خاصة بك
  • اضبط Event Triggers على الجداول التي تحتاج إخطار أنظمة خارجية عند تغيّر البيانات
  • عطّل HASURA_GRAPHQL_DEV_MODE وHASURA_GRAPHQL_ENABLE_CONSOLE قبل كشف هذا النشر لحركة مرور إنتاجية

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

  • غيّر السر الإداري المُولَّد وخزّنه بأمان — أي شخص يملكه يحصل على وصول قراءة وكتابة غير مقيد لكامل قاعدة بياناتك
  • لا تكشف Hasura للإنترنت مع تفعيل HASURA_GRAPHQL_DEV_MODE — فهو يسرّب تفاصيل الأخطاء الداخلية وخطط الاستعلام
  • عطّل الكونسول (HASURA_GRAPHQL_ENABLE_CONSOLE=false) في الإنتاج وأدر المخطط والصلاحيات عبر Hasura CLI والترحيلات بدلاً منه
  • اضبط صلاحيات قائمة على الأدوار لكل جدول قبل السماح لأي عميل غير إداري بالوصول — يرفض Hasura الوصول افتراضياً فقط عند ضبط الصلاحيات صراحةً
  • ضع Hasura خلف وكيل عكسي مع HTTPS/TLS لأن السر الإداري وكل الاستعلامات تنتقل بنص عادي بدون ذلك
  • استخدم مصادقة JWT أو webhook بدلاً من الاعتماد فقط على السر الإداري لطلبات المستخدمين النهائيين
  • أبقِ PostgreSQL مقيداً على شبكة Docker الداخلية — لا تكشف المنفذ 5432 مباشرة للإنترنت أبداً
  • حافظ على تحديث صورة Hasura من Docker لتحصل على تصحيحات الأمان وتحسينات نظام الصلاحيات الجديدة

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

يكشف هذا النشر واجهة GraphQL وكونسول Hasura على منفذ المضيف 8241، المرتبط بالمنفذ الداخلي 8080 للحاوية، مع تقديم الكونسول عند المسار /console. يعمل PostgreSQL كحاوية منفصلة على نفس شبكة Docker ويستمع على المنفذ 5432 داخلياً، لكن هذا المنفذ غير منشور للمضيف — فقط Hasura يمكنه الوصول إليه. يجب ألا يُكشف المنفذ 8241 مباشرة للإنترنت دون وكيل عكسي يوفر TLS، لأن استعلامات GraphQL والسر الإداري ينتقلان بدون تشفير خلاف ذلك. ضع Hasura خلف Nginx Proxy Manager أو وكيل عكسي مماثل على المنفذ 443 مع شهادة صالحة، وعطّل الكونسول ووضع dev mode تماماً إذا كانت الواجهة مخصصة لخدمة تطبيقات عميل إنتاجية.

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

  • انسخ قاعدة بيانات PostgreSQL احتياطياً بانتظام باستخدام pg_dump — Hasura نفسه عديم الحالة ولا يخزّن أي بيانات تطبيق خاصة به
  • صدّر بيانات Hasura الوصفية الخاصة بالجداول المتتبَّعة والصلاحيات والعلاقات وActions وEvent Triggers باستخدام تصدير Hasura CLI
  • أدر مجلد بيانات Hasura الوصفية والترحيلات بنظام تحكم إصدارات مثل Git حتى تُتابَع تغييرات المخطط والصلاحيات وتكون قابلة لإعادة الإنتاج
  • انسخ السر الإداري وأي متغيرات بيئة احتياطياً في مدير أسرار آمن، وليس في ملفات نصية عادية
  • احتفظ بنسخة من docker-compose.yml لإعادة إنشاء حاويتي Hasura وPostgreSQL بنفس الإعدادات
  • اختبر استعادة PostgreSQL وإعادة تطبيق بيانات Hasura الوصفية على نسخة تجريبية دورياً للتأكد من عمل عملية النسخ الاحتياطي بالكامل

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

  • ترك HASURA_GRAPHQL_DEV_MODE مفعّلاً في الإنتاج، مما يكشف تفاصيل الأخطاء الداخلية وخطط الاستعلام لأي عميل
  • عدم ضبط صلاحيات الجداول قبل كشف الواجهة، مما يمنع الوصول المشروع أو يترك البيانات مكشوفة بشكل غير مقصود حسب إعدادات الدور الافتراضية
  • ترميز أو رفع السر الإداري إلى مستودع الكود بدلاً من تخزينه في مدير أسرار أو ملف بيئة
  • كشف مسار /console علناً في الإنتاج بدلاً من تعطيله وإدارة تغييرات المخطط عبر ترحيلات CLI
  • كشف منفذ PostgreSQL 5432 مباشرة للإنترنت بدلاً من إبقائه داخلياً على شبكة Docker
  • عدم استخدام HTTPS أمام Hasura، مما يرسل السر الإداري وحمولات الاستعلام بنص عادي
  • نسيان تتبّع الجداول المُنشأة حديثاً في الكونسول، فلا تظهر في مخطط GraphQL حتى يتم تتبعها يدوياً
  • الاعتماد فقط على السر الإداري لكل طلبات العملاء بدلاً من إعداد مصادقة JWT وأدوار لكل مستخدم

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

  • الكونسول يطلب السر الإداري بشكل متكرر أو يرفضه — تحقق من عدم وجود مسافات إضافية عند اللصق وتأكد أن متغير البيئة HASURA_GRAPHQL_ADMIN_SECRET مطابق
  • الجداول الجديدة لا تظهر في مخطط GraphQL — اذهب إلى Data في الكونسول واضغط "Track" بجانب الجدول غير المتتبَّع
  • استعلامات GraphQL تُرجع نتائج فارغة رغم وجود البيانات — تحقق من الصلاحيات المضبوطة للدور المستخدم في الطلب؛ يُصفّي Hasura الصفوف حسب الدور النشط
  • تعذّر الاتصال بـ PostgreSQL — تحقق من متغير البيئة DATABASE_URL وتأكد أن الحاويتين على نفس شبكة Docker
  • الاشتراكات لا تستقبل تحديثات مباشرة — تأكد أن العميل يتصل عبر WebSocket (wss/ws) وليس عبر HTTP polling كبديل
  • أخطاء 401 Unauthorized من الواجهة — تأكد من إرسال ترويسة x-hasura-admin-secret أو رمز JWT بشكل صحيح مع الطلب
  • استعلامات بطيئة على جداول كبيرة — أضف فهارس PostgreSQL مناسبة؛ يدفع Hasura التصفية والترتيب إلى SQL، فتؤثر فهرسة قاعدة البيانات مباشرة على أداء GraphQL
  • الكونسول يعرض تحذير عدم اتساق في المخطط/البيانات الوصفية — راجع Settings → Metadata Status وأعد التحميل أو أصلح العنصر غير المتسق المُدرج

البدائل

PostgREST يولّد واجهة REST (وليس GraphQL) مباشرة من مخطط PostgreSQL وهو أخف وزناً لكنه يفتقر لاشتراكات Hasura الفورية وواجهة الصلاحيات. Supabase يجمع واجهة مولّدة تلقائياً مشابهة (REST عبر PostgREST وGraphQL معاً) مع مصادقة وتخزين ودوال حدّية كخدمة خلفية كاملة، مما يجعله خياراً جيداً إذا أردت أكثر من مجرد طبقة API. PostGraphile منافس مباشر أقرب، يولّد أيضاً GraphQL من مخططات PostgreSQL بنظام إضافات قوي، رغم أن كونسول Hasura وActions/Event Triggers تُعتبر عموماً أكثر نضجاً للفرق الجديدة على GraphQL. Apollo Server أو خادم GraphQL مكتوب يدوياً يمنحك تحكماً كاملاً في resolvers لكنه يتطلب كتابة وصيانة كل منطق CRUD الذي يولّده Hasura تلقائياً. لأسرع مسار من مخطط PostgreSQL قائم إلى واجهة GraphQL فورية جاهزة للإنتاج، يبقى Hasura الخيار الأكمل.

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

Hasura ليس الخيار المناسب إذا كانت بياناتك لا تعيش في قاعدة بيانات مدعومة (PostgreSQL وMySQL وSQL Server وقلة أخرى) — فهو ليس إطار عمل خلفي عام ولن يساعد في منطق غير متعلق بقاعدة البيانات يتجاوز ما يمكن لـ Actions وEvent Triggers ربطه. إذا كان فريقك يفضّل REST بشدة على GraphQL لأسباب توافق العملاء، فقد يكون PostgREST أو طبقة REST مكتوبة يدوياً أبسط من تبني لغة استعلام جديدة. المشاريع الصغيرة جداً وقصيرة الأجل بنقطة نهاية أو اثنتين قد تجد إعداد Hasura — تشغيل قاعدة بيانات بالإضافة لحاوية محرك GraphQL منفصلة — أثقل من كتابة مسارات REST مباشرة. إذا كان معظم سطح الواجهة البرمجية لديك منطق أعمال مخصص حقاً وليس عمليات CRUD على البيانات، فخادم تطبيق تقليدي يمنحك تحكماً مباشراً أكبر من الالتفاف حول نموذج التوليد التلقائي لـ Hasura باستخدام Actions لكل شيء.

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

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

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

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

ما هو Hasura؟

Hasura محرك يولّد واجهة GraphQL كاملة فوق قاعدة بيانات PostgreSQL تلقائياً — استعلامات وتعديلات واشتراكات فورية — دون كتابة أي كود resolver.

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

هذا النشر يقدّم Hasura على منفذ المضيف 8241، مع كونسول الويب عند المسار /console — أي http://your-server:8241/console. عند فتح الكونسول سيطلب السر الإداري الذي ولّده المثبّت وطبعه.

ما السر الإداري ولماذا يهم؟

يولّد المثبّت سراً إدارياً من 32 حرفاً وهو المفتاح الرئيسي لكامل واجهتك وكونسولك. يتجاوز كل الصلاحيات، لذا أي شخص يملكه يحصل على وصول قراءة وكتابة غير مقيد لكامل قاعدة بياناتك عبر Hasura.

هل هذا النشر جاهز للإنتاج؟

ليس كما هو مُسلَّم. فهو يفعّل dev mode، الذي يكشف تفاصيل الأخطاء الداخلية وخطط الاستعلام المفيدة أثناء البناء لكن يجب ألا تكون ظاهرة في الإنتاج.

ما الفرق بين Hasura وSupabase؟

يركّز Hasura تحديداً على أن يكون محرك GraphQL قوياً فوق PostgreSQL مع اشتراكات فورية ونظام صلاحيات غني قائم على الأدوار. أما Supabase فهو خدمة خلفية أشمل تجمع واجهة REST ومصادقة وتخزين وميزات فورية معاً.