clickhouse-client تفاعلية عبر WebSocket. وهي متاحة من أي منفذ HTTP لـ ClickHouse على المسار /webterminal.
انتقل إلى /webterminal على أي منفذ HTTP لـ ClickHouse (على سبيل المثال، http://localhost:8123/webterminal) لفتح الطرفية.
تمكين الميزة وتعطيلها
/webterminal مفعّلة افتراضيًا، ويتحكم فيها إعداد الخادم enable_webterminal. ولتعطيلها، اضبط الإعداد على false؛ وعندها ستعيد الطلبات المرسلة إلى /webterminal حالة HTTP 403 Forbidden.
يحل
enable_webterminal محل الإعداد السابق allow_experimental_webterminal. ولا يزال الاسم القديم مدعومًا للحفاظ على التوافق مع الإصدارات السابقة عند عدم تعيين enable_webterminal.المصادقة
Session نفسها وضوابط التحكم في الوصول نفسها المعتمدة في بروتوكول HTTP، لكن تُتبادل بيانات الاعتماد ضمن القناة نفسها عبر اتصال WebSocket القائم بدلًا من تمريرها عبر طلب ترقية HTTP. بعد اكتمال مصافحة WebSocket، يرسل المتصفح الرسالة الأولى بصيغة JSON:
user اختياري: عند حذفه أو تركه فارغًا، يُستخدم اسم المستخدم المحدد في إعداد الخادم default_session_user إعداد الخادم (أو تجاوزه الخاص بكل نقطة نهاية في تهيئة البروتوكولات القابلة للتركيب)، وهو default ما لم يُهيَّأ بخلاف ذلك. إذا ضُبط default_session_user على سلسلة فارغة، تُحظر الاتصالات التي لا تحتوي على اسم مستخدم: تفشل مصادقة رسالة auth التي يكون فيها user محذوفًا أو فارغًا، ويغلق الخادم اتصال WebSocket بالرمز 1008، وعند تمكين قسم session_log في تهيئة الخادم، يُسجَّل الرفض في system.session_log بوصفه حدث LoginFailure مع user فارغ.
يؤدي ذلك إلى تجنّب وضع بيانات الاعتماد في معلمات استعلام URL أو رؤوس Authorization المرفقة بطلب الترقية، إذ قد ينتهي بها المطاف في سجل التصفّح، وسجلات وصول الخادم، وسجلات الوكيل العكسي. ولا يعتمد /webterminal عمدًا على معلمات URL أو مصادقة HTTP Basic أو رؤوس X-ClickHouse-User/X-ClickHouse-Key في طلب الترقية.
تؤدي بيانات الاعتماد غير الصالحة إلى أن يغلق الخادم اتصال WebSocket بالرمز 1008؛ وتطلب واجهة المستخدم في المتصفح بيانات الاعتماد مرة أخرى.
كيف تبدو الجلسة
clickhouse-client متصلًا بـ طرفية زائفة، وينقل الإدخال والإخراج عبر WebSocket. وتدعم الجلسة تجربة clickhouse-client الكاملة، بما في ذلك:
- تمييز بناء الجملة.
- الإكمال التلقائي.
- الاستعلامات متعددة الأسطر.
- سجل الأوامر (يُخزَّن على الخادم طوال مدة الجلسة).
التكامل مع /play
/play طرفية الويب كلوحة قابلة للإرساء. يمكنك إظهارها أو إخفاؤها باستخدام أيقونة الطرفية في الشريط الجانبي، أو بالضغط على المفتاح ~ عندما يكون محرر الاستعلام فارغًا. تكتشف صفحة /play مدى توفر /webterminal عند تحميلها، وتخفي عناصر التحكم في الطرفية عندما تكون نقطة النهاية غير متاحة (على سبيل المثال، عندما تكون enable_webterminal مضبوطة على false).
التكامل مع موقع التوثيق
play ذي صلاحية القراءة فقط، بحيث يمكنك تجربة الأمثلة في أي صفحة دون مغادرتها. يحجز الشريط الثابت مساحة مماثلة في نهاية الصفحة كي لا يحجب عناصر التحكم في التذييل. عند فتح الطرفية، تُقفل صفحة التوثيق ويُخفى شريط تمريرها. يقتصر التمرير فوق الطرفية على سجل تمريرها ولا يحرّك صفحة التوثيق الموجودة خلفها. انقر شريط “طرفية ClickHouse” أو اضغط المفتاح ~ لفتح اللوحة ذات الهوامش الداخلية فوق الشريط. انقر الشريط مجددًا، أو استخدم السهم، أو اضغط ~ أو Escape، أو اسحب الحافة العلوية للوحة إلى الأسفل لطيّها؛ ويمكنك أيضًا تغيير حجمها من تلك الحافة. يؤدي إنهاء الجلسة — exit أو Ctrl+D — إلى طيّ اللوحة أيضًا.
يؤدي إغلاق اللوحة إلى الاحتفاظ بالجلسة وسجل تمريرها: فعند إعادة فتح الطرفية، ستعود إلى الموجّه نفسه. تستمر الجلسة ضمن الصفحة عند التنقل بين صفحات التوثيق، لكنها لا تستمر بعد إعادة تحميل علامة تبويب المتصفح — إذ تعود اللوحة بعد إعادة التحميل بجلسة جديدة.
يُعد شريط الطرفية جزءًا من تخطيط سطح المكتب للموقع، ولا يتوفر في منافذ العرض الضيقة.
اعتبارات الأمان
- احرص دائمًا على تقديم
/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>.
توفّر المنصات
clickhouse-client بالاعتماد على بدائيات POSIX القابلة للنقل (posix_openpt/grantpt/unlockpt)، مع مسار خاص بـ Linux يستخدم ptsname_r الآمن للخيوط. وتُخفى الروابط إلى /webterminal في صفحة بدء ClickHouse وفي /play تلقائيًا عندما لا تكون نقطة النهاية متاحة (على سبيل المثال، عند ضبط enable_webterminal على false).