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

> Документация по веб-терминалу — браузерному сеансу `clickhouse-client` через WebSocket

# Веб-терминал

Веб-терминал — это экспериментальный браузерный интерфейс, который предоставляет интерактивный сеанс `clickhouse-client` через WebSocket. Он доступен через любой HTTP-порт ClickHouse по пути `/webterminal`.

<Note>
  Веб-терминал — экспериментальная возможность и по умолчанию отключён; см. раздел [Включение возможности](#enabling-the-feature) ниже.
</Note>

<div id="enabling-the-feature">
  ## Включение возможности
</div>

Доступ к конечной точке `/webterminal` управляется настройкой сервера `allow_experimental_webterminal`. Если для этой настройки установлено значение `false` (по умолчанию), запросы к `/webterminal` возвращают HTTP-статус `403 Forbidden`.

Чтобы включить её, добавьте в конфигурацию сервера следующее:

```xml theme={null}
<clickhouse>
    <allow_experimental_webterminal>true</allow_experimental_webterminal>
</clickhouse>
```

После включения перейдите по адресу `/webterminal` на любом HTTP-порту ClickHouse (например, `http://localhost:8123/webterminal`), чтобы открыть терминал.

<div id="authentication">
  ## Аутентификация
</div>

Веб-терминал аутентифицирует пользователя с помощью тех же проверок `Session` и контроля доступа, что и в HTTP-протоколе, однако учетные данные передаются по уже установленному WebSocket-соединению, а не через HTTP-запрос Upgrade. После завершения рукопожатия WebSocket браузер отправляет первое сообщение в формате JSON:

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

Это позволяет не передавать учетные данные в параметрах URL-запроса или в заголовках `Authorization`, добавляемых к запросу на upgrade, откуда они могут попасть в историю браузера, журналы доступа сервера и журналы обратного прокси. Параметры URL, HTTP Basic и заголовки `X-ClickHouse-User`/`X-ClickHouse-Key` в запросе на upgrade намеренно **не** используются `/webterminal`.

Недействительные учетные данные приводят к тому, что сервер закрывает WebSocket с кодом `1008`; интерфейс браузера снова запрашивает учетные данные.

<div id="session">
  ## Как выглядит сеанс
</div>

После аутентификации сервер запускает `clickhouse-client`, подключённый к псевдотерминалу, и передаёт его ввод и вывод через WebSocket. Сеанс поддерживает все возможности `clickhouse-client`, включая:

* Подсветку синтаксиса.
* Автодополнение.
* Многострочные запросы.
* Историю команд (хранится на стороне сервера в течение сеанса).

Для отрисовки терминала используется [xterm.js](https://xtermjs.org/). Все ресурсы отдаются непосредственно из бинарного файла ClickHouse — сторонние CDN не загружаются.

<div id="play-integration">
  ## Интеграция с `/play`
</div>

Интерфейс Web SQL [`/play`](/ru/concepts/features/interfaces/http) встраивает веб-терминал в виде прикрепляемой панели. Его можно включать и выключать с помощью значка терминала на боковой панели или нажатием клавиши `~`, когда редактор запросов пуст. При загрузке страница `/play` определяет доступность `/webterminal` и скрывает элементы управления терминалом, если конечная точка недоступна (например, когда экспериментальный параметр не включен).

<div id="security">
  ## Вопросы безопасности
</div>

Веб-терминал предоставляет интерактивный сеанс, похожий на работу в оболочке, любому, кто может пройти аутентификацию через HTTP-конечную точку ClickHouse, поэтому здесь действуют те же ограничения, что и для HTTP-протокола:

* Всегда предоставляйте `/webterminal` по HTTPS в недоверенных средах, чтобы защитить учетные данные и трафик сеанса.
* Ограничивайте доступ на сетевом уровне (с помощью межсетевого экрана, обратного прокси или настройки `listen_host`) так же, как вы ограничиваете доступ к HTTP-протоколу.
* Конечная точка сверяет заголовок `Origin` с `Host`, чтобы снизить риск захвата WebSocket-соединения между разными источниками; если вы завершаете TLS на внешнем прокси, настройте обратные прокси соответствующим образом.
* Если используется обратный прокси с завершением TLS, вышестоящее соединение с ClickHouse будет обычным `http`, хотя браузер использует `https`, поэтому строгая проверка same-origin будет отклонять легитимные соединения. Для таких развертываний задайте `webterminal_allowed_origins` как разделенный запятыми список полных источников, которым разрешено открывать WebSocket-сеансы; если этот параметр не пуст, он заменяет проверку same-origin по умолчанию. Пример: `<webterminal_allowed_origins>https://example.com,https://app.example.com:8443</webterminal_allowed_origins>`.

Обработчик также проверяет соответствие протоколу WebSocket согласно RFC 6455: немаскированные клиентские фреймы, зарезервированные коды операций, слишком большие или фрагментированные управляющие фреймы, а также зарезервированные биты RSV отклоняются с кодами закрытия protocol-error.

<div id="platform">
  ## Доступность платформы
</div>

Обработчик компилируется на всех платформах, поддерживаемых ClickHouse. Слой псевдотерминала, используемый встроенным средством запуска `clickhouse-client`, реализован поверх переносимых примитивов POSIX (`posix_openpt`/`grantpt`/`unlockpt`), а для Linux предусмотрен отдельный путь с использованием потокобезопасного `ptsname_r`. Ссылки на `/webterminal` на главной странице ClickHouse и в `/play` автоматически скрываются, если конечная точка недоступна (например, когда `allow_experimental_webterminal` не включен).