> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

# طرفية الويب

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

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

<div id="enabling-the-feature">
  ## تمكين الميزة وتعطيلها
</div>

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

```xml theme={null}
<clickhouse>
    <enable_webterminal>false</enable_webterminal>
</clickhouse>
```

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

<div id="authentication">
  ## المصادقة
</div>

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

```json theme={null}
{"type": "auth", "user": "<user>", "password": "<password>"}
```

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

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

<div id="session">
  ## كيف تبدو الجلسة
</div>

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

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

تستخدم الطرفية [xterm.js](https://xtermjs.org/) للعرض. وتُقدَّم جميع الموارد من الملف التنفيذي ClickHouse نفسه — ولا يتم تحميل أي شبكات CDN تابعة لجهات خارجية.

<div id="play-integration">
  ## التكامل مع `/play`
</div>

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

<div id="security">
  ## اعتبارات الأمان
</div>

تُتيح طرفية الويب جلسة تفاعلية شبيهة بواجهة الأوامر لأي شخص يمكنه المصادقة عبر نقطة نهاية 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 المحجوزة، باستخدام رموز إغلاق تشير إلى خطأ في البروتوكول.

<div id="platform">
  ## توفّر المنصات
</div>

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