إعداد واستخدام محرك البحث Typesense في ServBay

يُعد Typesense محرك بحث مفتوح المصدر وخفيف الوزن وسريع جدًا، صُمم لتقديم تجربة بحث فورية في الوقت الفعلي ("البحث أثناء الكتابة") مع زمن استجابة منخفض. غالبًا ما يُستخدم كبديل خفيف لمحركات مثل Algolia أو Elasticsearch. عبر منصة ServBay، يمكنك نشر وإدارة نسخة كاملة الوظائف من Typesense في بيئة macOS محلية لديك بسهولة، وإضافة إمكانيات بحث قوية لتطبيقاتك.

نظرة عامة

يُسهّل ServBay عملية تثبيت وتكوين Typesense إلى حد كبير. لم تعد بحاجة للتعامل مع سطر الأوامر أو مهام معقدة؛ جميع الإعدادات تتم من خلال واجهة رسومية سهلة، لتصبح خدمة البحث المحلية جاهزة للعمل فورًا.

ولتحسين تجربة التطوير، يقوم ServBay تلقائيًا بتهيئة نقطة وصول HTTPS آمنة وسهلة لـ Typesense: https://typesense.servbay.host/. هذا يلغي عنك عناء إعداد المنافذ وشهادات SSL، ويمكنك مباشرة استخدام هذا النطاق لإجراء استدعاءات واجهة برمجة التطبيقات (API) داخل مشروعك.

المتطلبات الأساسية

• تأكد من تثبيت وتشغيل ServBay على نظام macOS الخاص بك.
• لديك مشروع قيد التطوير يحتاج لدمج ميزة البحث.
• لديك فهم أساسي لمفاهيم محركات البحث (مثل المجموعة/الفهرسة Collection، الوثائق Document، مفتاح API).

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

1. تثبيت حزمة Typesense

اتبع الخطوات التالية لتثبيت Typesense عبر ServBay:

1. افتح تطبيق ServBay.
2. من شريط التنقل الأيسر، اضغط على الحزم (Packages).
3. في قائمة الحزم، ابحث عن قسم البحث - ثم اختر Typesense.
4. اضغط زر التثبيت بجانب Typesense وانتظر حتى يكتمل التثبيت.
5. بعد ذلك، فعّل خدمة Typesense بالنقر على الزر بجانبها.

2. إعداد خدمة Typesense

بعد التثبيت، قم بإجراء التكوينات الأساسية لـ Typesense:

1. من شريط التنقل الأيسر في ServBay، اضغط على البحث (Search).

2. من القائمة المنسدلة، اختر Typesense للانتقال إلى واجهة الإعدادات الخاصة به.

   

3. ستظهر لك الحقول التالية، يمكنك تعديلها حسب حاجتك أو ترك القيم الافتراضية:

   • عنوان IP (Bind IP): عنوان IP الذي يستمع عليه Typesense. الافتراضي هو 127.0.0.1 لضمان التوافر فقط من نفس الجهاز – وهو الخيار الأكثر أمانًا أثناء التطوير المحلي.
   • المنفذ (Port): منفذ الاتصال على مستوى Typesense API. القيمة الافتراضية هي 8108. رغم ذلك، نوصي بشدة باستخدام النطاق https://typesense.servbay.host الذي يوفره ServBay للوصول.
   • مفتاح API: يُستخدم للتحقق من جميع طلبات API. هذا هو خط الدفاع الرئيسي لحماية بيانات البحث الخاصة بك؛ تأكد من تعيين مفتاح قوي وفريد واحتفظ به في مكان آمن.
   • مسار البيانات (Data Path): حيث يحفظ Typesense بيانات الفهارس والإعدادات محليًا. المسار الافتراضي /Applications/ServBay/data/typesense. يمكنك النقر على أيقونة المجلد على اليمين للوصول السريع لهذا الدليل عبر Finder.

3. حفظ الإعدادات وتشغيل الخدمة

1. بعد إكمال جميع الإعدادات، اضغط على زر حفظ (Save) في أسفل يمين الشاشة.
2. انتقل إلى قائمة الحزم (Packages)، وابحث عن Typesense، ثم استخدم زر التبديل لتشغيل الخدمة.
3. عند ضبط الإعدادات بشكل صحيح، سيتحول مؤشر حالة الخدمة إلى اللون الأخضر، مما يعني أن Typesense يعمل بنجاح.

4. دمج Typesense في تطبيقك

يمكن لأي تطبيق (مثل JavaScript، PHP، Python، Go ...) الاتصال بنسخة Typesense التي أنشأتها عبر أي مكتبة رسمية أو مجتمعية متوافقة.

استخدم المعلومات التالية عند إعداد الاتصال:

• المضيف/العقدة (Host/Node): typesense.servbay.host
• المنفذ (Port): 443 (وهو المنفذ الافتراضي لاتصالات HTTPS)
• البروتوكول (Protocol): https
• مفتاح API: المفتاح الذي قمت بإعداده في الخطوة رقم 2

مثال كود JavaScript (باستخدام عميل typesense-js)

أولاً، ثبّت حزمة العميل الخاص بـ Typesense في مشروعك:

npm install typesense
# أو
yarn add typesense

ثم، استخدم الكود التالي للتهيئة والتفاعل مع Typesense:

import Typesense from 'typesense'

// تهيئة عميل Typesense
// لاحظ استخدام النطاق الخاص الآمن المقدم من ServBay
const client = new Typesense.Client({
  nodes: [{
    host: 'typesense.servbay.host',
    port: 443,
    protocol: 'https'
  }],
  apiKey: 'YOUR-SUPER-STRONG-API-KEY', // استبدلها بمفتاح API الذي أعددته في ServBay
  connectionTimeoutSeconds: 2
})

// مثال: إنشاء مجموعة باسم 'books'
const bookSchema = {
  name: 'books',
  fields: [
    { name: 'title', type: 'string' },
    { name: 'author', type: 'string', facet: true },
    { name: 'publication_year', type: 'int32', facet: true }
  ],
  default_sorting_field: 'publication_year'
}

async function setupTypesense() {
  try {
    // إنشاء المجموعة
    await client.collections().create(bookSchema);
    console.log("تم إنشاء مجموعة 'books' بنجاح.");

    // إضافة وثيقة كتاب
    const bookDocument = {
      'title': 'The Hitchhiker\'s Guide to the Galaxy',
      'author': 'Douglas Adams',
      'publication_year': 1979
    };
    await client.collections('books').documents().create(bookDocument);
    console.log("تمت إضافة الوثيقة بنجاح.");

    // إجراء بحث
    const searchParameters = {
      'q': 'hitchhiker',
      'query_by': 'title',
      'sort_by': 'publication_year:desc'
    };
    const searchResults = await client.collections('books').documents().search(searchParameters);
    console.log('نتائج البحث:', searchResults);

  } catch (error) {
    console.error('خطأ في Typesense:', error);
  }
}

setupTypesense();

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

• س: نسيت مفتاح API، كيف أعيد تعيينه؟
  • ج: عملية إعادة التعيين سهلة على ServBay. فقط أدخل مفتاحًا جديدًا في حقل API Key ضمن واجهة إعداد Typesense (من البحث -> Typesense)، ثم اضغط على حفظ (Save)، وأعد تشغيل خدمة Typesense.
• س: فشل تشغيل خدمة Typesense، ما الحل؟
  • ج: تحقق مما يلي:
    1. اضغط على أيقونة السجل في أعلى يمين إعدادات Typesense لمراجعة رسائل الأخطاء، وغالبًا ستجد السبب المباشر هناك.
    2. تأكد أن المنفذ المحلي 8108 غير مشغول بتطبيق آخر.
    3. راجع مسار بيانات Typesense (Data Path) وتأكد من وجوده وإعطاء ServBay الصلاحيات اللازمة للقراءة والكتابة عليه.
• س: هل يمكنني الوصول إلى API مباشرة عبر http://127.0.0.1:8108؟
  • ج: نعم، يمكن الوصول عبر هذا المنفذ محليًا. لكن يُوصى بشدة باستخدام https://typesense.servbay.host/ للاتصال لأنه يوفر تشفير HTTPS دون إعدادات إضافية، وهو أقرب لطبيعة بيئات الإنتاج ويوفر مزيدًا من الأمان.

الخلاصة

يجمع ServBay بين قوة Typesense وسهولة التكامل ليمنحك تجربة تطوير بحثية متقدمة على macOS. بفضل الإعداد المرئي السلس ونقطة الوصول HTTPS الجاهزة، يمكنك التركيز على بناء تجربة البحث المثالية لمستخدميك دون الانشغال بتعقيدات التكوين والصيانة.