> ## 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`), чтобы открыть терминал.
## Включение и отключение возможности
Конечная точка `/webterminal` включена по умолчанию и управляется настройкой сервера `enable_webterminal`. Чтобы отключить её, задайте для этой настройки значение `false`; после этого запросы к `/webterminal` будут возвращать статус HTTP `403 Forbidden`. ```xml theme={null} false ``` Параметр `enable_webterminal` заменяет прежний параметр `allow_experimental_webterminal`. Старое название по-прежнему поддерживается для обратной совместимости, если `enable_webterminal` не указан.
## Аутентификация
Веб-терминал аутентифицирует пользователя с помощью тех же проверок `Session` и контроля доступа, что и в HTTP-протоколе, однако учетные данные передаются по уже установленному WebSocket-соединению, а не через HTTP-запрос Upgrade. После завершения рукопожатия WebSocket браузер отправляет первое сообщение в формате JSON: ```json theme={null} {"type": "auth", "user": "", "password": ""} ``` Поле `user` необязательно: если оно отсутствует или пусто, в качестве имени пользователя используется значение настройки сервера `default_session_user` [настройка сервера](/ru/reference/settings/server-settings/settings) (или ее переопределение для конечной точки в конфигурации [компонуемых протоколов](/ru/concepts/features/configuration/server-config/composable-protocols)); по умолчанию — `default`, если не настроено иначе. Если для `default_session_user` задана пустая строка, подключения без имени пользователя запрещены: сообщение `auth` с отсутствующим или пустым `user` не проходит аутентификацию, сервер закрывает WebSocket с кодом `1008`, а при включенном в конфигурации сервера разделе `session_log` отказ записывается в [`system.session_log`](/ru/reference/system-tables/session_log) как событие `LoginFailure` с пустым `user`. Это позволяет не передавать учетные данные в параметрах URL-запроса или в заголовках `Authorization`, добавляемых к запросу на upgrade, откуда они могут попасть в историю браузера, журналы доступа сервера и журналы обратного прокси. Параметры URL, HTTP Basic и заголовки `X-ClickHouse-User`/`X-ClickHouse-Key` в запросе на upgrade намеренно **не** используются `/webterminal`. Недействительные учетные данные приводят к тому, что сервер закрывает WebSocket с кодом `1008`; интерфейс браузера снова запрашивает учетные данные.
## Как выглядит сеанс
После аутентификации сервер запускает `clickhouse-client`, подключённый к псевдотерминалу, и передаёт его ввод и вывод через WebSocket. Сеанс поддерживает все возможности `clickhouse-client`, включая: * Подсветку синтаксиса. * Автодополнение. * Многострочные запросы. * Историю команд (хранится на стороне сервера в течение сеанса). Для отрисовки терминала используется [xterm.js](https://xtermjs.org/). Все ресурсы отдаются непосредственно из бинарного файла ClickHouse — сторонние CDN не загружаются.
## Интеграция с `/play`
Интерфейс Web SQL [`/play`](/ru/concepts/features/interfaces/http) встраивает веб-терминал в виде прикрепляемой панели. Его можно включать и выключать с помощью значка терминала на боковой панели или нажатием клавиши `~`, когда редактор запросов пуст. При загрузке страница `/play` определяет доступность `/webterminal` и скрывает элементы управления терминалом, если конечная точка недоступна (например, когда `enable_webterminal` имеет значение `false`).
## Интеграция с сайтом документации
На этом сайте документации тот же терминал встроен в узкую панель разработчика внизу страницы и подключён к [песочнице ClickHouse](https://play.clickhouse.com) от имени пользователя `play` с доступом только для чтения. Благодаря этому примеры с любой страницы можно опробовать, не покидая её. Фиксированная панель резервирует соответствующее место внизу страницы, чтобы не перекрывать элементы нижнего колонтитула. Пока терминал открыт, страница документации заблокирована, а её полоса прокрутки скрыта. Прокрутка над терминалом ограничивается его буфером прокрутки и не прокручивает страницу документации за ним. Нажмите на панель «Терминал ClickHouse» или клавишу `~`, чтобы открыть панель с внутренними отступами над ней. Чтобы свернуть её, снова нажмите на панель, используйте шеврон, нажмите `~` или `Escape` либо перетащите верхний край панели вниз; этим же краем можно изменять её размер. Завершение сеанса — `exit` или `Ctrl+D` — также сворачивает панель. При закрытии панели сеанс и его буфер прокрутки сохраняются: при повторном открытии терминала отображается тот же промпт. Сеанс существует в пределах страницы, поэтому сохраняется при переходе между страницами документации, но не при перезагрузке вкладки браузера: после перезагрузки панель откроется с новым сеансом. Панель терминала является частью десктопной версии сайта и недоступна при узкой ширине области просмотра.
## Вопросы безопасности
Веб-терминал предоставляет интерактивный сеанс, похожий на работу в оболочке, любому, кто может пройти аутентификацию через HTTP-конечную точку ClickHouse, поэтому здесь действуют те же ограничения, что и для HTTP-протокола: * Всегда предоставляйте `/webterminal` по HTTPS в недоверенных средах, чтобы защитить учетные данные и трафик сеанса. * Ограничивайте доступ на сетевом уровне (с помощью межсетевого экрана, обратного прокси или настройки `listen_host`) так же, как вы ограничиваете доступ к HTTP-протоколу. * Конечная точка сверяет заголовок `Origin` с `Host`, чтобы снизить риск захвата WebSocket-соединения между разными источниками; если вы завершаете TLS на внешнем прокси, настройте обратные прокси соответствующим образом. * Если используется обратный прокси с завершением TLS, вышестоящее соединение с ClickHouse будет обычным `http`, хотя браузер использует `https`, поэтому строгая проверка same-origin будет отклонять легитимные соединения. Для таких развертываний задайте `webterminal_allowed_origins` как разделенный запятыми список полных источников, которым разрешено открывать WebSocket-сеансы; если этот параметр не пуст, он заменяет проверку same-origin по умолчанию. Пример: `https://example.com,https://app.example.com:8443`. Обработчик также проверяет соответствие протоколу WebSocket согласно RFC 6455: немаскированные клиентские фреймы, зарезервированные коды операций, слишком большие или фрагментированные управляющие фреймы, а также зарезервированные биты RSV отклоняются с кодами закрытия protocol-error.
## Доступность платформы
Обработчик компилируется на всех платформах, поддерживаемых ClickHouse. Слой псевдотерминала, используемый встроенным средством запуска `clickhouse-client`, реализован поверх переносимых примитивов POSIX (`posix_openpt`/`grantpt`/`unlockpt`), а для Linux предусмотрен отдельный путь с использованием потокобезопасного `ptsname_r`. Ссылки на `/webterminal` на главной странице ClickHouse и в `/play` автоматически скрываются, если конечная точка недоступна (например, когда `enable_webterminal` установлено в `false`).