🗄️ تثبيت CouchDB — قاعدة بيانات مستندات JSON عبر HTTP بالكامل
انشر Apache CouchDB على Ubuntu بـ Docker — قاعدة بيانات مستندات JSON بواجهة HTTP REST كاملة ومزامنة متعددة السادة (master-master) مصممة للتطبيقات العاملة دون اتصال والموزّعة.
📦 الملفات والأكواد المطلوبة
قبل البدء، يرجى التأكد من تحميل الأكواد المطلوبة من مستودعنا على GitHub لتتمكن من تطبيق الخطوات مع الفيديو بسهولة.
التثبيت السريع:
wget https://raw.githubusercontent.com/mhmdali94/Docker/refs/heads/main/databases/couchdb/couchdb-ubuntu.sh
chmod +x couchdb-ubuntu.sh
sudo bash couchdb-ubuntu.sh
خطوات التنفيذ
1 تحميل السكريبت
wget https://raw.githubusercontent.com/mhmdali94/Docker/refs/heads/main/databases/couchdb/couchdb-ubuntu.sh
2 منحه صلاحية التنفيذ
chmod +x couchdb-ubuntu.sh
3 تشغيل المثبّت
يثبّت السكريبت Docker إن لزم ويُشغّل CouchDB مع تخزين دائم وبيانات اعتماد المسؤول التي تضبطها كمتغيرات بيئة. يستمع CouchDB على المنفذ 5984 لواجهة HTTP API وواجهة إدارة Fauxton.
sudo bash couchdb-ubuntu.sh
4 الدخول إلى واجهة الويب
افتح Fauxton، واجهة الإدارة المدمجة في CouchDB، في متصفحك وسجّل الدخول باسم المستخدم وكلمة المرور اللذين ضبطتهما للمسؤول:
http://:5984/_utils
# Fauxton admin UI — log in with your admin credentials
المنافذ المستخدمة
| المنفذ | الغرض |
|---|---|
| 5984 | HTTP API + Fauxton UI + replication |
| 4369 / 9100s | Erlang clustering (single-node: keep closed) |
نظرة عامة
CouchDB (Apache CouchDB) قاعدة بيانات NoSQL موجّهة للمستندات تخزّن البيانات كمستندات JSON وتعرض كل وظائفها — القراءة والكتابة والاستعلام والمزامنة والإدارة — عبر واجهة HTTP REST عادية بدلاً من بروتوكول ثنائي مخصص. كل مستند يُنسَّخ (versioned) باستخدام MVCC (التحكم بالتزامن متعدد الإصدارات) عبر معرّفات مراجعة (revision IDs)، بحيث تُكتشف التعديلات المتزامنة وتُحل بدلاً من الكتابة فوقها بصمت. الميزة المميّزة لـ CouchDB هي المزامنة متعددة السادة (master-master): أي نسختين من CouchDB (أو سيرفر CouchDB مع نسخة PouchDB تعمل في متصفح أو تطبيق جوال) يمكنهما التزامن ثنائي الاتجاه، ودمج التغييرات، ومواصلة العمل بشكل مستقل عند الانقطاع. واجهة الإدارة المدمجة Fauxton تتيح تصفح قواعد البيانات وتشغيل الاستعلامات وإدارة السيرفر دون أي أدوات خارجية.
لماذا تستخدمه
معظم قواعد البيانات تفترض وجود مصدر رئيسي واحد متصل دائماً وتحتاج أدوات معقدة لمزامنة البيانات في مكان آخر. بُني CouchDB من الأساس على الافتراض المعاكس — أن الشبكات غير موثوقة وأن العملاء يحتاجون الاستمرار بالعمل أثناء الانقطاع. ولأن كل عملية هي استدعاء HTTP قياسي، يمكنك التحدث مع CouchDB بـ curl أو متصفح أو أي عميل HTTP دون مكتبة تعريف، ولأن المزامنة عنصر أساسي وليس إضافة، فإن مزامنة البيانات بين سيرفر ولابتوب وتطبيق جوال هو إعداد بسيط وليس كوداً مخصصاً. للتطبيقات التي تحتاج العمل دون اتصال وحل التعارضات بأمان عند عودة الاتصال، يزيل CouchDB كماً هائلاً من جهد الهندسة الذي كان سيُبنى يدوياً.
متى تحتاجه
- تبني تطبيق جوال أو ويب يعمل دون اتصال (offline-first) ويحتاج الاستمرار بالعمل بلا شبكة والمزامنة تلقائياً عند عودتها
- تحتاج مزامنة متعددة السادة حيث يمكن تحديث نسختين أو أكثر من قاعدة البيانات بشكل مستقل ودمجهما لاحقاً بأمان
- تريد قاعدة بيانات يمكن استعلامها وإدارتها بطلبات HTTP عادية بدلاً من بروتوكول ثنائي خاص بقاعدة البيانات ومكتبة تعريف
- تحتاج كشف تعارضات مدمجاً للتعديلات المتزامنة بدلاً من نظام "آخر كتابة تفوز" الذي يفقد البيانات بصمت
- تخزّن مستندات JSON شبه منظّمة، مع مرفقات ثنائية اختيارية، لا تتناسب بسلاسة مع مخطط علائقي
- تريد قاعدة بيانات خفيفة ومستقلة لمخزن إعدادات أو خلفية CMS أو تطبيق صغير إلى متوسط دون عبء تشغيلي ثقيل
من يحتاجه
- مطورو تطبيقات الجوال والويب الذين يبنون تطبيقات offline-first تتزامن مع PouchDB في المتصفح أو عميل الجوال
- الفرق التي تحتاج تكرار بيانات متعدد المناطق أو المكاتب حيث يجب أن يستمر كل موقع بالعمل أثناء انقطاعات الشبكة
- مطورو الواجهة الخلفية الذين يفضّلون واجهة HTTP/REST عادية على بروتوكول سلكي خاص لتسهيل التصحيح والأدوات
- مشاريع إنترنت الأشياء (IoT) حيث تجمع الأجهزة الطرفية بيانات محلياً وتتزامن مع نسخة CouchDB مركزية بشكل متقطع
- الفرق الصغيرة التي تبني خلفيات بأسلوب CMS أو مخازن إعدادات تستفيد من مرونة مستندات JSON
- المطورون الذين يستخدمون PouchDB على العميل بالفعل ويريدون نظيراً خلفياً طبيعياً ومتوافقاً في البروتوكول
حالات الاستخدام الشائعة
- مزامنة البيانات بين تطبيق جوال وسيرفر مركزي، مما يتيح للمستخدمين الاستمرار بالعمل دون اتصال تماماً ودمج التغييرات عند عودة الاتصال
- تكرار قاعدة بيانات عبر عدة مواقع مكتبية بحيث يملك كل موقع نسخة محلية سريعة تبقى متسقة نهائياً
- دعم تطبيق تدوين ملاحظات أو جمع بيانات ميدانية أو استبيانات يجب أن يعمل دون اتصال في الميدان
- تخزين وتقديم إعدادات أو محتوى JSON يُستعلَم عنه ويُحدَّث بالكامل عبر طلبات HTTP
- بناء طبقة تخزين مؤقت موزّعة حيث يحتفظ كل سيرفر تطبيق بنسخة محلية متزامنة من البيانات المشتركة
- تشغيل تطبيق يعمل في المتصفح باستخدام PouchDB يتزامن مباشرة مع خلفية CouchDB دون كود مزامنة مخصص
الميزات الرئيسية
- كل عملية — CRUD والاستعلامات والإدارة والمزامنة — تُعرض عبر واجهة HTTP REST قياسية بحمولات JSON
- مزامنة أصلية متعددة السادة (master-master) تدمج التغييرات من مصادر متعددة وتُظهر التعارضات بدلاً من إسقاط البيانات بصمت
- تنسيخ مستندات MVCC باستخدام معرّفات مراجعة، بحيث تُفحص كل كتابة مقابل المراجعة الحالية للمستند
- عروض MapReduce لفهرسة واستعلام المستندات، بالإضافة إلى لغة استعلام Mango التصريحية بأسلوب شبيه بـ MongoDB
- واجهة إدارة ويب مدمجة Fauxton لتصفح قواعد البيانات وتشغيل الاستعلامات وإدارة المستخدمين دون أدوات إضافية
- محرك تخزين B-tree للإلحاق فقط مقاوم للأعطال بتصميمه، لأن البيانات لا تُكتب فوق نفسها أبداً
- دعم من الدرجة الأولى للمرفقات، لتخزين الملفات الثنائية (صور، PDF) جنباً إلى جنب مع بيانات المستند الوصفية بصيغة JSON
- متوافق في البروتوكول مع PouchDB، مما يتيح مزامنة سلسة offline-first بين عملاء المتصفح أو الجوال والسيرفر
كيفية الاستخدام بعد التثبيت
- سجّل الدخول لـ Fauxton على http://your-server-ip:5984/_utils باسم المستخدم وكلمة المرور اللذين ضبطتهما للمسؤول
- أنشئ أول قاعدة بيانات لك من واجهة Fauxton أو بطلب HTTP PUT بسيط إلى /your-db-name
- أضف مستندات كـ JSON عبر HTTP PUT/POST، أو استورد بيانات موجودة باستخدام واجهة المستندات المجمّعة في CouchDB
- أعدّ مهمة مزامنة في Fauxton (أو عبر نقطة /_replicate) إذا احتجت مزامنة البيانات لنسخة CouchDB أو PouchDB أخرى
- صمّم عروض MapReduce أو فهارس Mango للاستعلامات التي يحتاجها تطبيقك، لأن الاستعلامات العشوائية دون فهرس قد تكون بطيئة
- تأكد من ضبط مستخدم مسؤول وكلمة مرور حتى لا تعمل النسخة بوضع مفتوح بالكامل
- اضبط CORS في إعدادات Fauxton إذا احتاج تطبيق يعمل في المتصفح (بما فيه PouchDB) التحدث مع CouchDB مباشرة
- أعدّ وكيلاً عكسياً مع HTTPS أمام المنفذ 5984 إذا احتاجت النسخة أن تكون متاحة من خارج شبكتك المحلية
أفضل ممارسات الأمان
- اضبط دائماً اسم مستخدم وكلمة مرور للمسؤول أثناء الإعداد — نسخة CouchDB بلا مسؤول مضبوط تسمح لأي شخص بقراءة وكتابة كل البيانات
- لا تكشف المنفذ 5984 مباشرة للإنترنت العام دون HTTPS — بيانات الاعتماد والبيانات تنتقل بـ HTTP عادي افتراضياً
- ضع CouchDB خلف وكيل عكسي مثل Nginx Proxy Manager وقيّد الوصول على الشبكات الموثوقة أو VPN
- استخدم كائنات الأمان الخاصة بكل قاعدة بيانات ومستند في CouchDB لتقييد أي مستخدمين أو أدوار يمكنهم قراءة أو كتابة بيانات معينة
- عطّل أو قيّد CORS بشدة على النطاقات المحددة التي يحتاجها تطبيقك فقط، بدلاً من السماح لكل النطاقات
- حافظ على تحديث CouchDB — تصدر تصحيحات أمنية لكل من النسخة أحادية العقدة والنسخة العنقودية
- إذا فُعّل التجميع العنقودي، أبقِ منافذ Erlang بين العقد (4369 ونطاق 9100s) مغلقة تماماً عن الإنترنت العام
- غيّر بيانات اعتماد المسؤول دورياً وتجنّب إعادة استخدام نفس كلمة مرور المسؤول عبر عدة نسخ CouchDB
المنافذ وإعدادات جدار الحماية
يستمع CouchDB على المنفذ 5984 (TCP) لواجهة HTTP API وواجهة الويب Fauxton وحركة المزامنة — وهو المنفذ الوحيد المطلوب لإعداد بعقدة واحدة. إذا فعّلت التجميع العنقودي، يستخدم CouchDB أيضاً المنفذ 4369 (Erlang Port Mapper Daemon) ونطاقاً حول 9100-9200 لحركة توزيع Erlang بين العقد؛ يجب أن تبقى هذه مغلقة عن الإنترنت العام ومتاحة فقط بين عقد المجموعة. يجب ألا يُكشف المنفذ 5984 مباشرة للإنترنت دون HTTPS — ضع CouchDB خلف وكيل عكسي مثل Nginx Proxy Manager على المنفذ 443 مع شهادة SSL صالحة، وقيّد الوصول المباشر للمنفذ 5984 في جدار الحماية بحيث يكون متاحاً فقط من الوكيل أو شبكتك المحلية.
النسخ الاحتياطي والصيانة
- انسخ دليل بيانات CouchDB احتياطياً، والذي يحتوي ملفات قواعد البيانات بأسلوب الإلحاق فقط لكل قاعدة بيانات على النسخة
- استخدم مزامنة CouchDB المدمجة كاستراتيجية نسخ احتياطي حي — زامن باستمرار مع نسخة ثانية أو نسخة CouchDB مخصصة للنسخ الاحتياطي فقط
- صدّر قواعد البيانات دورياً باستخدام واجهة HTTP (_all_docs مع المرفقات) إذا احتجت لقطات JSON قابلة للنقل خارج صيغة CouchDB الأصلية
- انسخ ملفات الإعداد (local.ini) احتياطياً جنباً إلى جنب مع دليل البيانات حتى يمكن استعادة بيانات اعتماد المسؤول والإعدادات معاً
- خزّن النسخ الاحتياطية خارج السيرفر، لأن عطل قرص على المضيف سيدمّر البيانات الحية والنسخة الاحتياطية معاً بخلاف ذلك
- اختبر استعادة نسخة احتياطية على نسخة منفصلة دورياً للتأكد أن البيانات وإعدادات المسؤول تعودان بشكل صحيح
الأخطاء الشائعة
- ترك النسخة دون مستخدم مسؤول مضبوط، مما كان تاريخياً يشغّلها بوضع "admin party" الذي يمنح أي شخص وصولاً كاملاً
- كشف المنفذ 5984 للإنترنت العام دون HTTPS أو وكيل عكسي أمامه
- الاستعلام عن قواعد بيانات كبيرة بـ _all_docs أو عروض مؤقتة عشوائية بدلاً من تصميم عروض MapReduce أو فهارس Mango مناسبة
- عدم معالجة تعارضات المزامنة في التطبيق — تُظهر CouchDB التعارضات لكن يجب حلها بمنطق التطبيق
- تفعيل CORS لكل النطاقات بدلاً من تقييده على النطاقات المحددة التي تحتاج وصول متصفح
- نسيان ضغط قواعد البيانات دورياً، مما يسمح للتخزين بأسلوب الإلحاق فقط بالنمو أكبر بكثير من البيانات الحية الفعلية
- فتح منافذ التجميع العنقودي لـ Erlang (4369، نطاق 9100s) للإنترنت العام على نسخة بعقدة واحدة لا تحتاجها إطلاقاً
استكشاف الأخطاء وإصلاحها
- تعذّر تسجيل الدخول لـ Fauxton — تحقق أن اسم مستخدم وكلمة مرور المسؤول يطابقان ما ضُبط في متغيرات البيئة أو local.ini
- استعلامات بطيئة — تحقق ما إذا كان الاستعلام يعتمد على عرض مؤقت/عشوائي أو مسح _all_docs بدلاً من عرض MapReduce أو فهرس Mango مناسب
- حجم ملف قاعدة البيانات ينمو بشكل غير متوقع — شغّل ضغطاً على قاعدة البيانات، لأن تخزين CouchDB بأسلوب الإلحاق فقط لا يستعيد المساحة تلقائياً
- المزامنة لا تعمل — تحقق من حالة مهمة المزامنة في Fauxton أو عبر نقطة /_active_tasks لتفاصيل الخطأ، وتأكد من الاتصال الشبكي بين النسختين
- مراجعات مستندات متعارضة بعد المزامنة — هذا سلوك متوقع؛ استعلم عن التعارضات وحلّها صراحة في منطق تطبيقك
- تعذّر الاتصال من تطبيق متصفح — تحقق من إعداد CORS في إعدادات Fauxton إذا كانت الطلبات تُحظر من المتصفح
- يبدو التجميع العنقودي معطلاً — تأكد أن المنفذ 4369 ونطاق 9100s مفتوحان بين عقد المجموعة لكن غير مكشوفين علناً
البدائل
MongoDB هي المقارنة الأكثر شيوعاً — كلاهما يخزّن مستندات شبيهة بـ JSON، لكن MongoDB تستخدم بروتوكولاً سلكياً ثنائياً ولغة استعلام أغنى، بينما تفتقر لنموذج المزامنة ثنائية الاتجاه المدمج في CouchDB. Couchbase، رغم تشابه الاسم، منتج مختلف يركّز على التخزين المؤقت والاستعلام الموزّع عالي الأداء بدلاً من المزامنة offline-first. Firebase Firestore وRealtime Database يقدّمان قدرات مزامنة دون اتصال مشابهة لكنهما خدمتان سحابيتان مغلقتا المصدر وليستا شيئاً تستضيفه ذاتياً. RethinkDB ركّز على استعلامات الدفع الفوري لكنه أقل صيانة نشطة اليوم بكثير. للفرق التي تبني تحديداً تطبيقات offline-first مع PouchDB على العميل، يبقى CouchDB السيرفر ذاتي الاستضافة الأكثر طبيعية وتوافقاً في البروتوكول.
متى لا تستخدمه
إذا كان تطبيقك لا يحتاج دعم العمل دون اتصال أو مزامنة متعددة السادة، فإن قاعدة بيانات علائقية مثل PostgreSQL أو مخزن مستندات أبسط قد يناسب أكثر ويقدّم قدرات استعلام أغنى جاهزة. نموذج عروض MapReduce في CouchDB له منحنى تعلّم مقارنة بلغة استعلام MongoDB الأكثر مرونة، والاستعلامات التحليلية العشوائية ليست نقطة قوة CouchDB. إذا احتجت ضمانات معاملات صارمة عبر عدة مستندات، فإن نموذج اتساق CouchDB على مستوى المستند غير مصمم لذلك. للفرق التي تريد قاعدة بيانات مزامنة دون اتصال مُدارة بالكامل وسحابية دون تشغيل بنية تحتية بنفسها، قد تكون خدمة مُدارة مثل Firebase أبسط من استضافة CouchDB ذاتياً.
هل تحتاج مساعدة احترافية؟
توفر PrismaTechWork خدمات بنية تحتية شاملة — من النشر الأولي وتصليب الأمان إلى المراقبة المستمرة والنسخ الاحتياطي التلقائي والدعم المخصص. سواء كنت تحتاج إعداد سيرفر واحد أو شبكة متعددة المواقع، يضمن فريقنا بناء بنيتك التحتية بشكل صحيح وتأمينها بالشكل المناسب وصيانتها باستمرار.
- التثبيت وتجهيز السيرفر
- الإعداد المتقدم وإعداد التوجيه
- تصليب الأمان وتحسين جدار الحماية
- إعداد شهادات SSL/TLS مع Let's Encrypt
- ربط النطاق المخصص والوكيل العكسي
- جدولة النسخ الاحتياطي التلقائي والتعافي من الكوارث
- المراقبة الفورية وتنبيهات الجاهزية
- الترحيل من المنصات القائمة
- استكشاف مشكلات الاتصال والأداء وإصلاحها
- سكريبتات أتمتة مخصصة وعقود دعم مستمر
الأسئلة الشائعة
ما الذي يميّز CouchDB عن قواعد بيانات المستندات الأخرى؟
يعرض CouchDB واجهته بالكامل عبر HTTP عادي — كل قراءة وكتابة واستعلام وإجراء إداري هو طلب HTTP قياسي بـ JSON. ميزته المميّزة هي المزامنة الأصلية متعددة السادة: يمكن لنسختين أو أكثر من CouchDB (أو PouchDB) التزامن ثنائي الاتجاه ومواصلة العمل بشكل مستقل أثناء الانقطاع، ثم دمج التغييرات وإظهار التعارضات عند عودة الاتصال.
هل يدعم CouchDB تطبيقات الجوال والويب العاملة دون اتصال؟
نعم، هذا هو حالة الاستخدام الأساسية لـ CouchDB. إنه متوافق في البروتوكول مع PouchDB، قاعدة بيانات JavaScript تعمل في المتصفح أو تطبيق الجوال وتتزامن مباشرة مع CouchDB. يستطيع المستخدمون الاستمرار بقراءة وكتابة البيانات بلا اتصال، وتتزامن التغييرات تلقائياً عند عودة الشبكة.
كيف أستعلم عن البيانات في CouchDB؟
يدعم CouchDB طريقتي استعلام رئيسيتين: عروض MapReduce المكتوبة بـ JavaScript لاستعلامات مفهرسة وعالية الأداء، وMango، لغة استعلام تصريحية بصيغة JSON مشابهة بأسلوبها لصيغة استعلام MongoDB للبحث العشوائي البسيط. للحصول على أداء متوقع على قواعد البيانات الكبيرة، يُنصح بعرض MapReduce أو فهرس Mango مناسب بدلاً من مسح كل المستندات.
ماذا يحدث عندما تعدّل نسختان نفس المستند أثناء الانقطاع؟
يكتشف CouchDB التعارض باستخدام نظام المراجعات (MVCC) ويحتفظ بكلا الإصدارين بدلاً من تجاهل أحدهما بصمت. تُعلَّم المراجعات المتعارضة وتُظهر عبر الواجهة، وتقع على عاتق التطبيق مسؤولية اختيار الإصدار الفائز أو دمج التغييرات — لن يخمّن CouchDB أي تعديل يجب أن يفوز.
هل CouchDB آمن افتراضياً؟
فقط إذا ضبطت اسم مستخدم وكلمة مرور للمسؤول أثناء الإعداد. نسخ CouchDB الأقدم بلا مسؤول مضبوط كانت تعمل بوضع 'admin party' المفتوح بالكامل حيث يستطيع أي شخص قراءة وكتابة كل البيانات. اضبط دائماً بيانات اعتماد المسؤول، وأبقِ المنفذ 5984 خلف وكيل عكسي مع HTTPS في بيئة الإنتاج، وقيّد CORS على النطاقات التي يحتاجها تطبيقك فعلياً.
