🔍 تثبيت Typesense — محرك البحث اللحظي فائق السرعة والمتسامح مع الأخطاء الإملائية على Docker

نشر محرك Typesense على Ubuntu باستخدام Docker — محرك البحث الفوري مفتوح المصدر الرائد والبديل لـ Algolia مع استجابة فائقة السرعة والتسامح مع الأخطاء الإملائية على المنفذ 8108.

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

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

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

سكريبت تثبيت مؤتمت — أمر واحد ينشر Typesense على المنفذ 8108 مع التخزين الدائم للفهارس ومفاتيح API والبحث اللحظي جاهزاً.
عرض على GitHub

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

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/databases/typesense/typesense-ubuntu.sh
chmod +x typesense-ubuntu.sh
sudo bash typesense-ubuntu.sh

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

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

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/databases/typesense/typesense-ubuntu.sh

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

chmod +x typesense-ubuntu.sh

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

يقوم السكريبت بتثبيت Docker وتجهيز مجلد التخزين الدائم للفهارس (`./data`) وتوليد مفتاح المشرف الرئيسي (`TYPESENSE_API_KEY`) وتشغيل حاوية Typesense على المنفذ 8108.

sudo bash typesense-ubuntu.sh

4 فحص الجاهزية وإنشاء أول فهرس بحث

أرسل طلب فحص صحة الخدمة عبر الرابط http://ip-سيرفرك:8108/health. واستخدم واجهات REST API أو مكتبات SDK (بـ JS وبايثون وPHP) لإنشاء المجموعات وفهرسة البيانات والبحث الفوري.

curl http://<your-server-ip>:8108/health

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

المنفذالغرض
8108REST API — search, indexing, and admin (no web UI)
./dataOn-disk index and collection schemas

نظرة عامة

تعد Typesense محرك بحث لحظي مفتوح المصدر وفائق السرعة تمت برمجته بلغة C++ ليكون بديلاً عصرياً ومريحاً للمطورين عن منصات Algolia ومحركات Elasticsearch المعقدة. يعمل المحرك عبر المنفذ 8108 من خلال واجهات REST API، ليخزن فهارس البحث بالذاكرة الحية (RAM) مع حفظها دورياً على القرص الصلب. ويقدم استجابة فورية للبحث أثناء الكتابة في أقل من 50 ميلي ثانية، مع تسامح آلي مع الأخطاء الإملائية، وفلترة متقدمة للسمات، وبحث جغرافي، ودعم المتجهات والذكاء الاصطناعي.

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

تفرض المنصات السحابية التجارية (مثل Algolia) تكاليف شهرية باهظة تتضاعف مع زيادة عدد عمليات البحث والسجلات، بينما يتطلب محرك Elasticsearch خوادم عملاقة واستهلاكاً ضخماً للذاكرة وإعدادات معقدة. تمنحك Typesense المعادلة المثالية: بحث لحظي فوري وسلس خلال أقل من 50 ميلي ثانية، واستهلاك ضئيل للرام، وبدون أي رسوم تراخيص، مع حزم SDK رسمية لكافة لغات البرمجة على سيرفرك الخاص.

متى تحتاجه

  • تحتاج إلى بحث فوري مع الإكمال التلقائي أثناء الكتابة (Search-as-you-type) لمتجرك أو موقعك
  • تريد تسامحاً ذكياً مع الأخطاء الإملائية (Typo Tolerance) يعيد النتائج الصحيحة حتى مع كتابة كلمات خاطئة
  • تبحث عن بديل مفتوح المصدر ومستضاف ذاتياً بنسبة 100% لمنصة Algolia السحابية المكلفة
  • تحتاج إلى تصفية وفلترة متعددة الأوجه (Faceted Search) كالفلترة حسب السعر، والتقييم، والماركة، والقسم
  • تريد دمج البحث النصي التقليدي مع البحث الدلالي بالمتجهات والذكاء الاصطناعي (Hybrid Vector Search)

من يحتاجه

  • مطورو الويب والواجهات الأمامية لبناء شاشات بحث فورية وتفاعلية مع Instantsearch.js وReact
  • المتاجر الإلكترونية والأسواق الرقمية لتقديم تجربة بحث وتصفح سلسة وفورية لكتالوج المنتجات
  • الشركات الناشئة والمنصات الإخبارية لفهرسة المقالات، ومراكز المساعدة، وملفات المستخدمين
  • مهندسو البيانات لربط فهرس بحث ثانوي فائق السرعة بجانب قواعد PostgreSQL وMongoDB
  • أصحاب السيرفرات المنزلية لفهرسة المكتبات الشخصية والكتب والوصفات للبحث فيها فورياً

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

  • تقديم بحث لحظي وفوري عبر 500,000 منتج تجاري مع فلاتر تفاعلية تتحدث في أقل من 50 ميلي ثانية
  • تصحيح الكلمات المكتوبة خطأً للمستخدمين تلقائياً (مثل تصحيح 'iphne' إلى 'iPhone') وعرض النتائج فوراً
  • إجراء استعلامات جغرافية للبحث عن أقرب المتاجر أو الفروع في نطاق 10 كم مرتبة حسب المسافة
  • دمج البحث بالكلمات المفتاحية مع متجهات OpenAI لتقديم بحث دلالي ذكي بمستندات التوثيق
  • تثبيت وترويج منتجات أو لافتات محددة في أعلى نتائج البحث لكلمات مفتاحية مخصصة (Curation)

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

  • بحث بالذاكرة الحية فائق السرعة على المنفذ 8108: استجابة للاستعلامات في أقل من 50 ميلي ثانية بلغة C++ النقية
  • تسامح أصلي مع الأخطاء الإملائية: خوارزميات ذكية لتصحيح أخطاء الحروف والتبديل تلقائياً
  • تصفية وفلترة السمات (Faceted Search): تصنيف دقيق للنتائج حسب الأقسام والنطاقات السعرية والوسوم
  • بحث هجين بالمتجهات (Vector Search): دعم أصلي لمتجهات التعلم الآلي والتشابه الجيبي (Cosine Similarity)
  • تخصيص وترويج النتائج: تثبيت أو إخفاء أو تعزيز ترتيب مستندات معينة لكلمات بحث مستهدفة
  • مفاتيح API مقيدة للواجهات: توليد مفاتيح بحث فقط للعملاء مع قيود صلاحيات مدمجة لمنع التلاعب
  • منظومة SDK متكاملة: مكتبات رسمية لجافاسكريبت، وبايثون، وPHP، وروبي، وGo، وجافا
  • معمارية Docker Compose تجمع Typesense مع ربط مجلد `./data` لحفظ الفهارس وقاعدة البيانات على القرص

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

  • افحص جاهزية السيرفر بأمر: `curl http://ip-سيرفرك:8108/health` (يجب أن يعيد `{"ok":true}`)
  • أنشئ أول مجموعة بيانات (Collection) بالـ API أو بمكتبة بايثون/JS باستخدام مفتاح `TYPESENSE_API_KEY`
  • استورد مستنداتك عبر واجهة الاستيراد المجمعة (`/collections/{name}/documents/import`)
  • أنشئ مفتاح API مخصص للبحث فقط للواجهة الأمامية من مسار `/keys`
  • اربط محول Instantsearch في واجهة موقعك للحصول على شريط بحث وفلاتر تفاعلية فورية
  • ضع Typesense خلف وكيل عكسي مشفر بـ HTTPS (مثل Nginx) مع شهادة SSL صالحة
  • أعد سكريبت نسخ احتياطي دوري لمجلد البيانات والفهارس `./data`

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

  • تنبيه أمني حاسم: عيّن مفتاح API رئيسي قوي ومعقد لمتغير `TYPESENSE_API_KEY` قبل تشغيل الحاوية
  • لا تضع مفتاح المشرف الرئيسي داخل كود جافاسكريبت بالواجهة الأمامية؛ ولد مفاتيح بحث مقيدة (Search-Only) للعملاء
  • استخدم تشفير HTTPS دائماً عبر وكيل عكسي لحماية عبارات البحث وبيانات العملاء المنقولة بالشبكة
  • اقصر الاتصال بالمنفذ 8108 على سيرفرات التطبيقات المعتمدة والوكيل العكسي
  • احمِ مجلد البيانات `./data` بصلاحيات نظام صارمة بالسيرفر (`chmod 700`)
  • حدّث صورة الحاوية دورياً للحصول على التحديثات الأمنية وإصلاحات الأداء

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

يقدم Typesense واجهته البرمجية REST API عبر منفذ TCP 8108 (لا يحتوي على لوحة تحكم ويب رسومية مدمجة). اسمح بالمنفذ 8108 للشبكة المحلية (`ufw allow 8108/tcp`). وإذا كنت تتيح البحث المباشر للزوار، وجه حركة المرور عبر وكيل عكسي مشفر بـ SSL على المنفذ 443 باستخدام مفاتيح بحث مقيدة، مع حظر الوصول الإداري الخارجي.

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

  • انسخ مجلد `./data` احتياطياً، والذي يحتوي على فهارس RocksDB وبيانات المجموعات المحفوظة على القرص
  • استخرج نسخة احتياطية حية عبر الـ API: `curl -X POST 'http://localhost:8108/operations/snapshot?snapshot_path=/tmp/typesense-snapshot' -H 'X-TYPESENSE-API-KEY: YOUR_KEY'`
  • احتفظ بنسخة من ملف `docker-compose.yml` وملف المتغيرات `.env`
  • أتمت النسخ الاحتياطي اليومي للمجلدات وارفعه إلى مساحة تخزين سحابية عبر restic أو rsync
  • اختبر الاستعادة بربط مجلد البيانات بحاوية تجريبية للتأكد من استرجاع الفهارس بنجاح

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

  • وضع مفتاح المشرف الرئيسي في كود المتصفح مما يتيح لأي زائر مسح وتعديل فهارس البحث بالكامل
  • الاعتقاد بأن Typesense يحتوي على لوحة ويب مرئية مدمجة (حيث أنه محرك API نقي يُدار بالكود ومكتبات SDK)
  • فهرسة ملايين السجلات الضخمة على سيرفر برام قليلة مما يسبب نفاد الذاكرة
  • عدم ربط مجلد التخزين الدائم `./data`، مما يسبب فقدان الفهارس والمجموعات عند تحديث الحاوية
  • كشف المنفذ 8108 للإنترنت العام مباشرة دون تشفير SSL

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

  • فحص الجاهزية يفشل — تأكد من عمل الحاوية بالأمر `docker compose ps` وافحص السجلات: `docker logs typesense -f`
  • الاستعلامات تعيد خطأ 401 Unauthorized — تأكد من تطابق ترويسة `X-TYPESENSE-API-KEY` مع المفتاح المضبوط
  • انهيار الحاوية أثناء استيراد البيانات — قلل حجم دفعات الاستيراد (مثل 500 إلى 1000 سجل لكل دفعة) أو ارفع RAM السيرفر
  • التسامح مع الأخطاء لا يعيد النتائج المطلوبة — اضبط معاملات البحث `num_typos` و`typo_tokens_threshold`
  • فشل فهرسة المستندات — تأكد من تطابق أنواع حقول الـ JSON مع المخطط الهيكلي المحدد للمجموعة

البدائل

محرك Meilisearch مفتوح المصدر. محرك Elasticsearch المؤسسي. محرك OpenSearch مفتوح المصدر من AWS. منصة Algolia السحابية التجارية. محرك Apache Solr الكلاسيكي.

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

تجنب استخدام Typesense كقاعدة بياناتك الأساسية للمعاملات المالية والكتابة المستمرة (حيث تعد PostgreSQL أو MySQL مصدر الحقيقة الأساسي، بينما يعمل Typesense كفهرس بحث ثانوي فائق السرعة). وإذا كنت تحتاج لتحليل وتجميع تيرابايت من سجلات السيرفرات والشبكات، فإن Elasticsearch أو VictoriaLogs مخصص للسجلات.

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

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

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

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

ما هو محرك Typesense وما الفرق بينه وبين Elasticsearch؟

تعد Typesense محرك بحث بالذاكرة الحية مفتوح المصدر ومكتوب بلغة C++. وعلى عكس Elasticsearch المبني على Java والذي يتطلب ضبطاً معقداً للذاكرة والعناقيد، يعمل Typesense فورياً بدون إعدادات معقدة، ويقدم بحثاً أسرع (<50 ميلي ثانية) باستهلاك رام أقل بكثير.

هل يحتوي Typesense على لوحة تحكم ويب رسومية؟

يعمل Typesense كخدمة REST API نقية بدون واجهة ويب مدمجة. ويتم التعامل معه عبر مكتبات SDK البرمجية (بايثون، جافاسكريبت، PHP) أو عبر لوحات تحكم خارجية مفتوحة المصدر.

كيف يعمل التسامح مع الأخطاء الإملائية في Typesense؟

يستخدم المحرك خوارزميات مسافة Damerau-Levenshtein المتطورة لاكتشاف وتصحيح الأخطاء المطبعية وتبديل الحروف في الوقت الفعلي، مما يعيد النتائج الصحيحة للمستخدم حتى لو أخطأ في كتابة الكلمات.

هل يمكن استخدام Typesense مع مكتبات React وInstantsearch؟

نعم! توفر Typesense مكتبة `typesense-instantsearch-adapter` الرسمية التي تتيح استخدام كافة عناصر واجهات Algolia Instantsearch (أشرطة البحث، الفلاتر، الترقيم) مباشرة مع سيرفر Typesense الخاص بك.

كم يستهلك Typesense من الذاكرة العشوائية (RAM)؟

نظراً لأن Typesense يخزن الفهارس النشطة بالذاكرة الحية، يتناسب استهلاك الرام مع حجم البيانات. تستهلك مجموعة من 100,000 سجل صغير حوالي 100 إلى 250 ميجابايت RAM، بينما تستهلك مليون سجل حوالي 1 إلى 2 جيجابايت RAM.