لماذا واجهة مولَّدة بدل خلفية مكتوبة يدوياً
في معظم التطبيقات، يقتصر جزء كبير من شيفرة الخادم على ترجمة طلبات HTTP إلى SQL: عرض وتصفية وتقسيم صفحات وإنشاء وتعديل وحذف، مع التحقق في كل مرة من أن المستخدم مخوَّل. هذه الشيفرة مكرّرة وتحتاج إلى اختبارات، وكل عمود جديد يفرض تعديلها.
ينطلق Hasura من مخطط القاعدة. يصبح الجدول المتتبَّع نوعاً في GraphQL، والمفتاح الأجنبي حقلاً متداخلاً، وقاعدة الصلاحية المكتوبة مرة واحدة تسري على كل الاستعلامات. أما منطق عملك الخاص — دفع أو إرسال بريد أو حساب — فيبقى في شيفرتك التي يستدعيها Hasura عبر webhook. وتحتفظ بقاعدة PostgreSQL: لا شيء محبوس في صيغة مغلقة.
ما يقدّمه Hasura
- واجهة GraphQL فورية — استعلامات وتعديلات وفلاتر وترتيب وتقسيم صفحات وتجميعات على كل جدول متتبَّع.
- العلاقات — تتحوّل المفاتيح الأجنبية إلى حقول متداخلة يمكن استعلامها في طلب واحد.
- اشتراكات فورية — يشترك العميل في استعلام ويتلقّى التغييرات عبر WebSocket.
- صلاحيات حسب الدور — قواعد على مستوى السطر والعمود تغذّيها claims رمز JWT.
- Actions والمشغّلات — webhooks تستدعيها عملية تعديل أو تغيّر في البيانات أو جدولة cron.
- لوحة ونقاط REST — إدارة عبر الويب، ومستكشف GraphiQL، وتحويل استعلام إلى مسار REST.
Hasura مقارنةً بطرق أخرى لعرض PostgreSQL
مرّر الجدول أفقيًا
| Hasura | واجهة مكتوبة يدوياً | PostgREST | |
|---|---|---|---|
| واجهة مولَّدة من المخطط | نعم، GraphQL وREST | لا | نعم، REST |
| علاقات متداخلة في طلب واحد | نعم | حسب الشيفرة | نعم، عبر embedding |
| الزمن الحقيقي | اشتراكات GraphQL | يجب تطويره | لا |
| الصلاحيات | حسب الدور والسطر والعمود، من اللوحة | في الشيفرة | أدوار PostgreSQL وRLS |
| منطق العمل | Actions ومشغّلات عبر webhooks | حرّ | دوال SQL |
| واجهة إدارة | لوحة ويب | لا | لا |
المتطلبات
يكفي خادم Ubuntu 24.04 بذاكرة 1 غيغابايت للبدء: في وضع السكون يستهلك محرّك Hasura وPostgreSQL معاً نحو 200 ميغابايت. خطّط لـ 2 غيغابايت حين تكبر القاعدة أو تتكاثر الاشتراكات. تحتاج إلى Docker مع إضافة Compose، وإلى اسم نطاق يشير إلى الخادم مع nginx وشهادة HTTPS: ستستدعي المتصفحات وتطبيقات الجوال واجهتك، فيجب أن تردّ على عنوان ثابت ومشفّر.
تثبيت Hasura عبر Docker Compose
تحضير الأسرار
أنشئ مجلد التطبيق وملف
.envيحمل كلمة مرور القاعدة وadmin secret، المفتاح الرئيسي للواجهة. لا يقرأ الملف إلا root.mkdir -p /opt/hasura && cd /opt/hasura cat > .env <<EOF DB_PASSWORD=$(openssl rand -hex 16) ADMIN_SECRET=$(openssl rand -hex 24) EOF chmod 600 .envإنشاء ملف Compose
يشغّل ملف
docker-compose.ymlهذا PostgreSQL على الشبكة الداخلية للمجموعة دون نشر أي منفذ، ثم Hasura حين تصبح القاعدة جاهزة. يُنشر منفذ Hasura على الواجهة المحلية فقط؛ وتُقدَّم اللوحة من الصورة نفسها دون استدعاء شبكة CDN الخاصة بالناشر، والقياس عن بعد معطّل.services: postgres: image: postgres:17.11-alpine restart: unless-stopped environment: POSTGRES_DB: hasura POSTGRES_USER: hasura POSTGRES_PASSWORD: ${DB_PASSWORD} volumes: - hasura-pgdata:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U hasura -d hasura"] interval: 10s retries: 10 hasura: image: hasura/graphql-engine:v2.51.3 restart: unless-stopped depends_on: postgres: condition: service_healthy ports: - "127.0.0.1:8103:8080" env_file: .env environment: HASURA_GRAPHQL_DATABASE_URL: postgres://hasura:${DB_PASSWORD}@postgres:5432/hasura HASURA_GRAPHQL_ADMIN_SECRET: ${ADMIN_SECRET} HASURA_GRAPHQL_ENABLE_CONSOLE: "true" HASURA_GRAPHQL_CONSOLE_ASSETS_DIR: /srv/console-assets HASURA_GRAPHQL_DEV_MODE: "false" HASURA_GRAPHQL_ENABLE_TELEMETRY: "false" volumes: hasura-pgdata: {}تشغيل المجموعة
عند التشغيل الأول ينشئ Hasura جداول بياناته الوصفية في المخطط
hdb_catalogويربط القاعدة مصدراً باسمdefault. تردّ النقطة/healthzبـOKحين يصبح المحرّك جاهزاً.docker compose up -d curl -fsS http://127.0.0.1:8103/healthz # OKالنشر عبر HTTPS خلف nginx
أضف كتلة
serverلنطاقك مع شهادة Let's Encrypt. الترويستانUpgradeوConnectionضروريتان: تمرّ الاشتراكات عبر WebSocket.location / { proxy_pass http://127.0.0.1:8103; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; }
لا يغادر admin secret الخادم أبداً
من دون HASURA_GRAPHQL_ADMIN_SECRET تكون اللوحة والواجهة كلها مفتوحة لكل من يعرف العنوان. ومعه يمنح السرّ كل الصلاحيات: قراءة كل الجداول والكتابة فيها، وتنفيذ SQL، وتعديل البيانات الوصفية. احتفظ به للوحة ولسكربتات الإدارة، ولا تضعه أبداً في شيفرة واجهة أمامية أو تطبيق جوال.
إنشاء جدول واستعلامه
افتح https://api.example.com/console وأدخل admin secret، ثم في تبويب Data أنشئ جدولاً todos بالأعمدة id (عدد صحيح تلقائي الزيادة) وtitle (نص) وdone (منطقي). انقر Track: يظهر الجدول فوراً في مستكشف تبويب API. ومن سكربت إدارة يُرسَل الاستعلام نفسه مع admin secret:
curl -s https://api.example.com/v1/graphql \
-H "x-hasura-admin-secret: $ADMIN_SECRET" \
-H 'content-type: application/json' \
-d '{"query":"{ todos { id title done } }"}'مصادقة المستخدمين وضبط الصلاحيات
يجب ألا يستخدم مستخدموك admin secret: يقدّمون رمز JWT يصدره مزوّد الهوية لديك (Logto أو Authentik أو Zitadel أو Auth0…). أخبر Hasura أين يجد مفاتيح التحقق، وأي دور يُمنح للطلبات بلا رمز، في ملف .env:
HASURA_GRAPHQL_JWT_SECRET={"type":"RS256","jwk_url":"https://auth.example.com/oidc/jwks"}
HASURA_GRAPHQL_UNAUTHORIZED_ROLE=anonymousأعد تشغيل المجموعة بالأمر docker compose up -d، فالخدمة hasura تقرأ هذا الملف عبر env_file. يجب أن يحمل الرمز الـ claims x-hasura-default-role وx-hasura-allowed-roles وx-hasura-user-id. ثم في تبويب Permissions لكل جدول حدّد ما يمكن لكل دور قراءته أو إدراجه أو تعديله — مثلاً لا يرى الدور user إلا الأسطر التي يساوي فيها user_id القيمة X-Hasura-User-Id.
استكشاف الأخطاء
تعرض اللوحة «invalid x-hasura-admin-secret»: السرّ المُدخل لا يطابق قيمة .env. تحقّق منها بالأمر grep ADMIN_SECRET /opt/hasura/.env ثم أعد تحميل الصفحة.
يعيد Hasura التشغيل بلا توقف: لا يمكن الوصول إلى القاعدة. يعرض docker compose logs hasura خطأ الاتصال؛ تحقّق من أن كلمة المرور في الرابط HASURA_GRAPHQL_DATABASE_URL هي كلمة مرور PostgreSQL. وإن غيّرتها بعد التشغيل الأول فقد احتفظ PostgreSQL بالقديمة: فهو لا يقرأ POSTGRES_PASSWORD إلا عند إنشاء وحدة التخزين.
تنقطع الاشتراكات: لا يمرّر الوكيل العكسي ترقية WebSocket. أضف الترويستين Upgrade وConnection المذكورتين أعلاه، وارفع proxy_read_timeout إن بقي عملاؤك خاملين طويلاً.
لا يظهر جدول في الواجهة: هو موجود في القاعدة لكنه غير متتبَّع. انقر Track في تبويب Data، أو تتبّع كل جداول المخطط دفعة واحدة.
التثبيت بنقرة واحدة من متجر ServOrbit
يثبّت متجر ServOrbit تطبيق Hasura على خادمك دون سطر أوامر: ينشر PostgreSQL ومحرّك Hasura، ويولّد admin secret وكلمة مرور القاعدة، ويربط القاعدة مصدراً باسم default، وينشر الواجهة عبر HTTPS على نطاق فرعي لنطاقك أو على النطاق الفرعي المجاني للخادم. يظهر admin secret في مساحة العميل؛ ولا يبقى إلا فتح اللوحة وإنشاء جداولك.
