بروتوكول قابل للتركيب

نظرة عامة

تتيح البروتوكولات القابلة للتركيب إعدادًا أكثر مرونة للوصول عبر TCP إلى خادم ClickHouse. ويمكن أن يتعايش هذا الإعداد مع الإعداد التقليدي، أو يحلّ محلّه.

إعداد البروتوكولات القابلة للتركيب

يمكن إعداد البروتوكولات القابلة للتركيب في ملف تهيئة بتنسيق XML. ويُحدَّد قسم البروتوكولات بوسوم protocols في ملف تهيئة XML:

<protocols>

</protocols>

إعداد طبقات البروتوكول

يمكنك تحديد طبقات البروتوكول باستخدام وحدات أساسية. على سبيل المثال، لتحديد طبقة HTTP، يمكنك إضافة وحدة أساسية جديدة إلى قسم protocols:

<protocols>

  <!-- plain_http module -->
  <plain_http>
    <type>http</type>
  </plain_http>

</protocols>

يمكن تهيئة الوحدات وفقًا لما يلي:

plain_http - اسم يمكن الرجوع إليه من طبقة أخرى
type - يشير إلى معالج البروتوكول الذي سيُنشأ لمعالجة البيانات. وتتوافر له معالجات البروتوكول المعرّفة مسبقًا التالية:
- tcp - معالج بروتوكول ClickHouse الأصلي
- http - معالج بروتوكول HTTP لـ ClickHouse
- tls - طبقة تشفير TLS
- proxy1 - طبقة PROXYv1
- mysql - معالج بروتوكول التوافق مع MySQL
- postgres - معالج بروتوكول التوافق مع PostgreSQL
- prometheus - معالج بروتوكول Prometheus
- interserver - معالج الاتصال الداخلي بين خوادم ClickHouse

لم يُنفَّذ معالج بروتوكول gRPC في Composable protocols

تكوين نقاط النهاية

يُشار إلى نقاط النهاية (منافذ الاستماع) بالوسمين <port> و<host> الاختياريين. على سبيل المثال، لتكوين نقطة نهاية على طبقة HTTP التي أُضيفت سابقًا، يمكننا تعديل التكوين كما يلي:

<protocols>

  <plain_http>

    <type>http</type>
    <!-- endpoint -->
    <host>127.0.0.1</host>
    <port>8123</port>

  </plain_http>

</protocols>

إذا أُهمِل الوسم <host>، فسيُستخدم <listen_host> من إعدادات الجذر.

تهيئة تسلسلات الطبقات

تُعرَّف تسلسلات الطبقات باستخدام الوسم <impl>، مع الإشارة إلى وحدة أخرى. على سبيل المثال، لتهيئة طبقة TLS فوق وحدة plain_http الخاصة بنا، يمكننا تعديل الإعدادات على النحو التالي:

<protocols>

  <!-- http module -->
  <plain_http>
    <type>http</type>
  </plain_http>

  <!-- https module configured as a tls layer on top of plain_http module -->
  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
  </https>

</protocols>

إرفاق نقاط النهاية بالطبقات

يمكن إرفاق نقاط النهاية بأي طبقة. على سبيل المثال، يمكننا تحديد نقاط نهاية لكلٍّ من HTTP (المنفذ 8123) وHTTPS (المنفذ 8443):

<protocols>

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
  </https>

</protocols>

تعريف نقاط نهاية إضافية

يمكن تعريف نقاط نهاية إضافية بالإشارة إلى أي وحدة مع حذف الوسم <type>. على سبيل المثال، يمكننا تعريف نقطة النهاية another_http لوحدة plain_http كما يلي:

<protocols>

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
  </https>

  <another_http>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8223</port>
  </another_http>

</protocols>

معالجات HTTP مخصّصة لكل نقطة نهاية

بشكل افتراضي، تشترك جميع إدخالات البروتوكول type=http في الإعداد <http_handlers> نفسه. يمكنك تجاوز ذلك بإضافة وسم <handlers> يشير إلى قسم إعدادات مختلف. يتيح هذا لكل منفذ HTTP أن يقدّم مجموعة مختلفة من قواعد توجيه HTTP. على سبيل المثال، لتشغيل واجهة برمجة تطبيقات HTTP بديلة على المنفذ 8124 مع معالجاتها الخاصة:

<protocols>

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <alt_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8124</port>
    <handlers>http_handlers_alt</handlers>
  </alt_http>

</protocols>

<!-- Default handlers used by plain_http (port 8123) -->
<http_handlers>
    <defaults/>
</http_handlers>

<!-- Alternative handlers used by alt_http (port 8124) -->
<http_handlers_alt>
    <rule>
        <url>/custom</url>
        <handler>
            <type>predefined_query_handler</type>
            <query>SELECT 'custom_endpoint'</query>
        </handler>
    </rule>
    <defaults/>
</http_handlers_alt>

في هذا المثال، تستخدم الطلبات الواردة إلى المنفذ 8123 قواعد <http_handlers> القياسية، بينما تستخدم الطلبات الواردة إلى المنفذ 8124 قواعد <http_handlers_alt>. وإذا حُذف <handlers> فإن نقطة النهاية تعود إلى <http_handlers> الافتراضي. يتبع قسم المعالِجات المخصّصة التنسيق نفسه المستخدم في <http_handlers>. ويُكتشف أي تغيير في قسم المعالِجات المخصّصة أثناء إعادة تحميل config، وتُعاد تشغيل نقطة النهاية المقابلة تلقائيًا.

مستخدم الجلسة الافتراضي لكل نقطة نهاية

عندما يتصل عميل دون تحديد اسم مستخدم (على سبيل المثال، طلب HTTP دون المعلَمة user، أو حزمة Hello من البروتوكول الأصلي ذات اسم مستخدم فارغ)، يصادقه الخادم بصفته مستخدم الجلسة الافتراضي، وهو إعداد الخادم default_session_user إعداد الخادم الذي قيمته الافتراضية هي default. يتجاوز الوسم <default_session_user> هذا الإعداد لنقطة نهاية واحدة. يتيح ذلك لمنافذ الاستماع المختلفة خدمة مستخدمين مجهولين مختلفين:

<protocols>

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <readonly_http>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8124</port>
    <default_session_user>readonly_user</default_session_user>
  </readonly_http>

</protocols>

في هذا المثال، تُصادَق الطلبات التي لا تتضمن بيانات اعتماد على المنفذ 8123 باستخدام مستخدم الجلسة الافتراضي المُهيأ عموميًا، بينما تُصادَق الطلبات على المنفذ 8124 باستخدام readonly_user. ولا يتأثر العميل الذي يمرر اسم مستخدم صراحةً. يُبحث عن الوسم بدءًا من وحدة نقطة نهاية وصولًا إلى الوحدات (impl) المشار إليها، وتُعتمد القيمة الأقرب إلى نقطة نهاية. وينطبق ذلك على معالجات البروتوكولات tcp وhttp وmysql وpostgres، وعلى معالجات prometheus التي تُصادِق الطلبات (remote_write وremote_read وquery وapi_v1)؛ أما نقاط نهاية عرض المقاييس (بما في ذلك نقاط نهاية Keeper المخصصة للمقاييس فقط) فتُخدَم دون مصادقة وتتجاهل هذا الإعداد. وتُصادِق المعالجات ذات المستخدم الثابت (مفتاح user داخل handler في قاعدة http_handlers، أو مفتاح user داخل handler في قاعدة prometheus.handlers) باستخدام مستخدمها المُهيأ، وتتجاهل هذا الإعداد أيضًا - وعلى نحو خاص، لا يؤدي ترك default_session_user فارغًا إلى رفض هذه المعالجات. ولا يمكن استخدامه مع بروتوكول interserver: إذ تُصادَق اتصالات الاتصال الداخلي بين خوادم ClickHouse بواسطة secret الخاص بـ cluster والمستخدم الأولي، ولا تستخدم أبدًا مستخدم الجلسة الافتراضي.

تحديد معلمات إضافية للطبقة

قد تتضمن بعض الوحدات معلمات إضافية للطبقة. على سبيل المثال، تتيح طبقة TLS تحديد مفتاح خاص (privateKeyFile) وملفات الشهادة (certificateFile) كما يلي:

<protocols>

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
    <privateKeyFile>another_server.key</privateKeyFile>
    <certificateFile>another_server.crt</certificateFile>
  </https>

</protocols>

Fundamentals

ClickHouse concepts

Best practices

نظرة عامة

إعداد البروتوكولات القابلة للتركيب

إعداد طبقات البروتوكول

تكوين نقاط النهاية

تهيئة تسلسلات الطبقات

إرفاق نقاط النهاية بالطبقات

تعريف نقاط نهاية إضافية

معالجات HTTP مخصّصة لكل نقطة نهاية

مستخدم الجلسة الافتراضي لكل نقطة نهاية

تحديد معلمات إضافية للطبقة

​نظرة عامة

​إعداد البروتوكولات القابلة للتركيب

​إعداد طبقات البروتوكول

​تكوين نقاط النهاية

​تهيئة تسلسلات الطبقات

​إرفاق نقاط النهاية بالطبقات

​تعريف نقاط نهاية إضافية

​معالجات HTTP مخصّصة لكل نقطة نهاية

​مستخدم الجلسة الافتراضي لكل نقطة نهاية

​تحديد معلمات إضافية للطبقة

نظرة عامة

إعداد البروتوكولات القابلة للتركيب

إعداد طبقات البروتوكول

تكوين نقاط النهاية

تهيئة تسلسلات الطبقات

إرفاق نقاط النهاية بالطبقات

تعريف نقاط نهاية إضافية

معالجات HTTP مخصّصة لكل نقطة نهاية

مستخدم الجلسة الافتراضي لكل نقطة نهاية

تحديد معلمات إضافية للطبقة