> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.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>"}
```

حقل `user` اختياري: عند حذفه أو تركه فارغًا، يُستخدم اسم المستخدم المحدد في إعداد الخادم `default_session_user` [إعداد الخادم](/ar/reference/settings/server-settings/settings) (أو تجاوزه الخاص بكل نقطة نهاية في تهيئة [البروتوكولات القابلة للتركيب](/ar/concepts/features/configuration/server-config/composable-protocols))، وهو `default` ما لم يُهيَّأ بخلاف ذلك. إذا ضُبط `default_session_user` على سلسلة فارغة، تُحظر الاتصالات التي لا تحتوي على اسم مستخدم: تفشل مصادقة رسالة `auth` التي يكون فيها `user` محذوفًا أو فارغًا، ويغلق الخادم اتصال WebSocket بالرمز `1008`، وعند تمكين قسم `session_log` في تهيئة الخادم، يُسجَّل الرفض في [`system.session_log`](/ar/reference/system-tables/session_log) بوصفه حدث `LoginFailure` مع `user` فارغ.

يؤدي ذلك إلى تجنّب وضع بيانات الاعتماد في معلمات استعلام 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="docs-integration">
  ## التكامل مع موقع التوثيق
</div>

يضمّن موقع التوثيق هذا الطرفية نفسها في شريط ضيق للمطورين أسفل الصفحة، متصلةً بـ [ClickHouse playground](https://play.clickhouse.com) بصفتها المستخدم `play` ذي صلاحية القراءة فقط، بحيث يمكنك تجربة الأمثلة في أي صفحة دون مغادرتها. يحجز الشريط الثابت مساحة مماثلة في نهاية الصفحة كي لا يحجب عناصر التحكم في التذييل. عند فتح الطرفية، تُقفل صفحة التوثيق ويُخفى شريط تمريرها. يقتصر التمرير فوق الطرفية على سجل تمريرها ولا يحرّك صفحة التوثيق الموجودة خلفها. انقر شريط "طرفية ClickHouse" أو اضغط المفتاح `~` لفتح اللوحة ذات الهوامش الداخلية فوق الشريط. انقر الشريط مجددًا، أو استخدم السهم، أو اضغط `~` أو `Escape`، أو اسحب الحافة العلوية للوحة إلى الأسفل لطيّها؛ ويمكنك أيضًا تغيير حجمها من تلك الحافة. يؤدي إنهاء الجلسة — `exit` أو `Ctrl+D` — إلى طيّ اللوحة أيضًا.

يؤدي إغلاق اللوحة إلى الاحتفاظ بالجلسة وسجل تمريرها: فعند إعادة فتح الطرفية، ستعود إلى الموجّه نفسه. تستمر الجلسة ضمن الصفحة عند التنقل بين صفحات التوثيق، لكنها لا تستمر بعد إعادة تحميل علامة تبويب المتصفح — إذ تعود اللوحة بعد إعادة التحميل بجلسة جديدة.

يُعد شريط الطرفية جزءًا من تخطيط سطح المكتب للموقع، ولا يتوفر في منافذ العرض الضيقة.

<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`).