طرفية الويب

توثيق طرفية الويب، وهي جلسة clickhouse-client تفاعلية داخل المتصفح عبر WebSocket

طرفية الويب هي واجهة داخل المتصفح توفّر جلسة clickhouse-client تفاعلية عبر WebSocket. وهي متاحة من أي منفذ HTTP لـ ClickHouse على المسار /webterminal.

انتقل إلى /webterminal على أي منفذ HTTP لـ ClickHouse (على سبيل المثال، http://localhost:8123/webterminal) لفتح الطرفية.

​

تمكين الميزة وتعطيلها

تكون نقطة النهاية /webterminal مفعّلة افتراضيًا، ويتحكم فيها إعداد الخادم enable_webterminal. ولتعطيلها، اضبط الإعداد على false؛ وعندها ستعيد الطلبات المرسلة إلى /webterminal حالة HTTP 403 Forbidden.

<clickhouse>
    <enable_webterminal>false</enable_webterminal>
</clickhouse>

يحل enable_webterminal محل الإعداد السابق allow_experimental_webterminal. ولا يزال الاسم القديم مدعومًا للحفاظ على التوافق مع الإصدارات السابقة عند عدم تعيين enable_webterminal.

​

المصادقة

تُصادق طرفية الويب المستخدم باستخدام فحوصات Session نفسها وضوابط التحكم في الوصول نفسها المعتمدة في بروتوكول HTTP، لكن تُتبادل بيانات الاعتماد ضمن القناة نفسها عبر اتصال WebSocket القائم بدلًا من تمريرها عبر طلب ترقية HTTP. بعد اكتمال مصافحة WebSocket، يرسل المتصفح الرسالة الأولى بصيغة JSON:

{"type": "auth", "user": "<user>", "password": "<password>"}

يؤدي ذلك إلى تجنّب وضع بيانات الاعتماد في معلمات استعلام URL أو رؤوس Authorization المرفقة بطلب الترقية، إذ قد ينتهي بها المطاف في سجل التصفّح، وسجلات وصول الخادم، وسجلات الوكيل العكسي. ولا يعتمد /webterminal عمدًا على معلمات URL أو مصادقة HTTP Basic أو رؤوس X-ClickHouse-User/X-ClickHouse-Key في طلب الترقية.

تؤدي بيانات الاعتماد غير الصالحة إلى أن يغلق الخادم اتصال WebSocket بالرمز 1008؛ وتطلب واجهة المستخدم في المتصفح بيانات الاعتماد مرة أخرى.

​

كيف تبدو الجلسة

بمجرد إتمام المصادقة، يشغّل الخادم clickhouse-client متصلًا بـ طرفية زائفة، وينقل الإدخال والإخراج عبر WebSocket. وتدعم الجلسة تجربة clickhouse-client الكاملة، بما في ذلك:

• تمييز بناء الجملة.
• الإكمال التلقائي.
• الاستعلامات متعددة الأسطر.
• سجل الأوامر (يُخزَّن على الخادم طوال مدة الجلسة).

تستخدم الطرفية xterm.js للعرض. وتُقدَّم جميع الموارد من الملف التنفيذي ClickHouse نفسه — ولا يتم تحميل أي شبكات CDN تابعة لجهات خارجية.

​

التكامل مع /play

تضمّن واجهة SQL على الويب /play طرفية الويب كلوحة قابلة للإرساء. يمكنك إظهارها أو إخفاؤها باستخدام أيقونة الطرفية في الشريط الجانبي، أو بالضغط على المفتاح ~ عندما يكون محرر الاستعلام فارغًا. تكتشف صفحة /play مدى توفر /webterminal عند تحميلها، وتخفي عناصر التحكم في الطرفية عندما تكون نقطة النهاية غير متاحة (على سبيل المثال، عندما تكون enable_webterminal مضبوطة على false).

​

اعتبارات الأمان

تُتيح طرفية الويب جلسة تفاعلية شبيهة بواجهة الأوامر لأي شخص يمكنه المصادقة عبر نقطة نهاية ClickHouse لبروتوكول HTTP، لذا فإن المحاذير نفسها التي تنطبق على بروتوكول HTTP تنطبق هنا أيضًا:

• احرص دائمًا على تقديم /webterminal عبر HTTPS في البيئات غير الموثوق بها لحماية بيانات الاعتماد وبيانات الجلسة أثناء النقل.
• قيّد الوصول على مستوى الشبكة (جدار حماية، أو وكيل عكسي، أو إعداد listen_host) بالطريقة نفسها التي تقيّد بها الوصول إلى بروتوكول HTTP.
• تتحقق نقطة النهاية من الترويسة Origin بمقارنتها مع Host للتخفيف من اختطاف WebSocket عبر المصادر المختلفة؛ لذا اضبط الوكلاء العكسيين وفقًا لذلك إذا كنت تُنهي TLS خارجيًا.
• عند العمل خلف وكيل عكسي يُنهي TLS، يكون اتصال upstream إلى ClickHouse عبر http غير مشفّر رغم أن المتصفح يستخدم https، لذا فإن التحقق الصارم من تطابق المصدر سيرفض الاتصالات المشروعة. في مثل هذه البيئات، اضبط webterminal_allowed_origins على قائمة مفصولة بفواصل تتضمن المصادر الكاملة المسموح لها بفتح جلسات WebSocket؛ وعندما لا تكون هذه القيمة فارغة، فإنها تحل محل التحقق الافتراضي من تطابق المصدر. مثال: <webterminal_allowed_origins>https://example.com,https://app.example.com:8443</webterminal_allowed_origins>.

يفرض المعالج أيضًا الامتثال لبروتوكول WebSocket وفقًا للمعيار RFC 6455: إذ تُرفض إطارات العميل غير المقنّعة، ورموز التشغيل المحجوزة، وإطارات التحكم كبيرة الحجم أو المُجزأة، وبتات RSV المحجوزة، باستخدام رموز إغلاق تشير إلى خطأ في البروتوكول.

​

توفّر المنصات

يُجمَّع المعالج على جميع المنصات التي يدعمها ClickHouse. وتُنفَّذ طبقة الطرفية الزائفة التي يستخدمها المشغّل المضمَّن clickhouse-client بالاعتماد على بدائيات POSIX القابلة للنقل (posix_openpt/grantpt/unlockpt)، مع مسار خاص بـ Linux يستخدم ptsname_r الآمن للخيوط. وتُخفى الروابط إلى /webterminal في صفحة بدء ClickHouse وفي /play تلقائيًا عندما لا تكون نقطة النهاية متاحة (على سبيل المثال، عند ضبط enable_webterminal على false).