Перейти к основному содержимому
Перейти к основному содержимому

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

Веб-терминал — это экспериментальный браузерный интерфейс, предоставляющий интерактивный сеанс 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​

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

Соображения безопасности​

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

  • Всегда используйте HTTPS для /webterminal в недоверенных средах, чтобы защитить учетные данные и трафик сеанса.
  • Ограничивайте доступ на сетевом уровне (межсетевой экран, обратный прокси или конфигурация listen_host) так же, как вы ограничиваете доступ к HTTP-протоколу.
  • Конечная точка проверяет соответствие заголовка Origin значению Host, чтобы снизить риск перехвата WebSocket-запросов между источниками; если TLS завершается на внешнем прокси, настройте обратные прокси соответствующим образом.
  • За обратным прокси, завершающим TLS, соединение с ClickHouse на стороне upstream использует обычный http, хотя браузер работает через https, поэтому строгая проверка same-origin будет отклонять легитимные соединения. Для таких развертываний задайте webterminal_allowed_origins как список полных 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 не включён).