واجهة برمجة تطبيقات HTTP لـ Keeper ولوحة المعلومات

توثيق واجهة برمجة تطبيقات HTTP لـ ClickHouse Keeper ولوحة المعلومات المضمّنة على الويب

يوفّر ClickHouse Keeper واجهة برمجة تطبيقات HTTP ولوحة المعلومات مضمّنة على الويب لأغراض المراقبة، وفحوصات السلامة، وإدارة التخزين. تتيح هذه الواجهة للمشغّلين فحص حالة العنقود، وتنفيذ الأوامر، وإدارة مساحة تخزين Keeper عبر متصفح ويب أو عملاء HTTP.

​

التهيئة

لتمكين واجهة برمجة تطبيقات HTTP، أضِف القسم http_control إلى تهيئة keeper_server:

<keeper_server>
    <!-- Other keeper_server configuration -->

    <http_control>
        <port>9182</port>
        <!-- <secure_port>9443</secure_port> -->
    </http_control>
</keeper_server>

​

خيارات التهيئة

الإعداد	الافتراضي	الوصف
http_control.port	-	منفذ HTTP للوحة المعلومات وواجهة برمجة تطبيقات
http_control.secure_port	-	منفذ HTTPS (يتطلب تهيئة SSL)
http_control.readiness.endpoint	/ready	مسار مخصص لنقطة نهاية فحص الجاهزية
http_control.storage.session_timeout_ms	30000	مهلة الجلسة لعمليات واجهة برمجة تطبيقات التخزين

​

نقاط النهاية

​

لوحة المعلومات

• المسار: /dashboard
• الطريقة: GET
• الوصف: يعرض لوحة معلومات ويب مضمّنة لمراقبة Keeper وإدارته

توفر لوحة المعلومات ما يلي:

• تصور لحالة العنقود في الوقت الفعلي
• مراقبة العقد (الدور، زمن الاستجابة، الاتصالات)
• مستعرض التخزين
• واجهة تنفيذ الأوامر

​

علامة تبويب العنقود

تعرض علامة التبويب العنقود أعضاء Raft في رسم بياني للطوبولوجيا وجدول. ويُعرض كل عضو بلون يوضح حالته الصحية:

• أخضر — نشط ومتزامن مع القائد
• أصفر — نشط، لكنه متأخر عن القائد بأكثر من stale_log_gap من إدخالات السجل
• أحمر — يتعذر الوصول إليه (لا توجد استجابة ناجحة من Raft ضمن مهلة نبضات القلب)
• رمادي — غير معروف (لا تظهر صحة النظير إلا من القائد؛ ويرى التابعون نظراءهم بحالة غير معروفة)

يعرض الجدول أيضًا دور كل عضو (قائد أو تابع أو مراقب)، وأولوية Raft، وآخر فهرس للسجل، وتأخر النسخ المتماثل مقارنةً بالقائد، والوقت المنقضي منذ آخر استجابة ناجحة من Raft. عندما لا تكون العقدة الحالية هي القائد، توفر علامة التبويب رابطًا مباشرًا يفتح لوحة معلومات القائد، حيث تتوفر معلومات الصحة الكاملة للنظراء. ويمكن فتح علامة التبويب مباشرةً باستخدام /dashboard?tab=cluster.

​

مسبار الجاهزية

• المسار: /ready (قابل للتهيئة)
• الطريقة: GET
• الوصف: نقطة نهاية للفحص الصحي

استجابة النجاح (HTTP 200):

{
  "status": "ok",
  "details": {
    "role": "leader",
    "hasLeader": true
  }
}

​

واجهة برمجة تطبيقات الأوامر

• المسار: /api/v1/commands/{command}
• الطرق: GET, POST
• الوصف: ينفّذ أوامر Four-Letter Word أو أوامر CLI الخاصة بعميل ClickHouse Keeper

معلمات الاستعلام:

• command - الأمر المراد تنفيذه
• cwd - دليل العمل الحالي للأوامر المعتمدة على المسار (الافتراضي: /)

أمثلة:

# Four-Letter Word command
curl http://localhost:9182/api/v1/commands/stat

# ZooKeeper CLI command
curl "http://localhost:9182/api/v1/commands/ls?command=ls%20'/'&cwd=/"

​

واجهة برمجة تطبيقات التخزين

• المسار الأساسي: /api/v1/storage
• الوصف: واجهة برمجة تطبيقات REST لعمليات تخزين Keeper

تتبع واجهة برمجة تطبيقات التخزين مبادئ REST، حيث تشير طُرق HTTP إلى نوع العملية:

العملية	المسار	الطريقة	رمز الحالة	الوصف
الحصول	/api/v1/storage/{path}	GET	200	الحصول على بيانات العقدة
إدراج	/api/v1/storage/{path}?children=true	GET	200	إدراج العُقد الفرعية
التحقق من الوجود	/api/v1/storage/{path}	HEAD	200	التحقق من وجود العقدة
إنشاء	/api/v1/storage/{path}	POST	201	إنشاء عقدة جديدة
تحديث	/api/v1/storage/{path}?version={v}	PUT	200	تحديث بيانات العقدة
حذف	/api/v1/storage/{path}?version={v}	DELETE	204	حذف العقدة