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

​
Включение возможности

Доступ к конечной точке /webterminal управляется настройкой сервера allow_experimental_webterminal. Если для этой настройки установлено значение false (по умолчанию), запросы к /webterminal возвращают HTTP-статус 403 Forbidden. Чтобы включить её, добавьте в конфигурацию сервера следующее: 
<clickhouse>
    <allow_experimental_webterminal>true</allow_experimental_webterminal>
</clickhouse>
После включения перейдите по адресу /webterminal на любом HTTP-порту ClickHouse (например, http://localhost:8123/webterminal), чтобы открыть терминал.

​
Аутентификация

Веб-терминал аутентифицирует пользователя с помощью тех же проверок Session и контроля доступа, что и в HTTP-протоколе, однако учетные данные передаются по уже установленному WebSocket-соединению, а не через HTTP-запрос Upgrade. После завершения рукопожатия WebSocket браузер отправляет первое сообщение в формате JSON: 
{"type": "auth", "user": "<user>", "password": "<password>"}
Это позволяет не передавать учетные данные в параметрах URL-запроса или в заголовках Authorization, добавляемых к запросу на upgrade, откуда они могут попасть в историю браузера, журналы доступа сервера и журналы обратного прокси. Параметры URL, HTTP Basic и заголовки X-ClickHouse-User/X-ClickHouse-Key в запросе на upgrade намеренно не используются /webterminal. Недействительные учетные данные приводят к тому, что сервер закрывает WebSocket с кодом 1008; интерфейс браузера снова запрашивает учетные данные.

​
Как выглядит сеанс

После аутентификации сервер запускает clickhouse-client, подключённый к псевдотерминалу, и передаёт его ввод и вывод через WebSocket. Сеанс поддерживает все возможности clickhouse-client, включая:
  • Подсветку синтаксиса.
  • Автодополнение.
  • Многострочные запросы.
  • Историю команд (хранится на стороне сервера в течение сеанса).
Для отрисовки терминала используется xterm.js. Все ресурсы отдаются непосредственно из бинарного файла ClickHouse — сторонние CDN не загружаются.

​
Интеграция с /play

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

​
Вопросы безопасности

Веб-терминал предоставляет интерактивный сеанс, похожий на работу в оболочке, любому, кто может пройти аутентификацию через 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.

​
Доступность платформы

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