clickhouse-client через WebSocket. Он доступен через любой HTTP-порт ClickHouse по пути /webterminal.
Перейдите по адресу /webterminal на любом HTTP-порту ClickHouse (например, http://localhost:8123/webterminal), чтобы открыть терминал.
Включение и отключение возможности
/webterminal включена по умолчанию и управляется настройкой сервера enable_webterminal. Чтобы отключить её, задайте для этой настройки значение false; после этого запросы к /webterminal будут возвращать статус HTTP 403 Forbidden.
Параметр
enable_webterminal заменяет прежний параметр allow_experimental_webterminal. Старое название по-прежнему поддерживается для обратной совместимости, если enable_webterminal не указан.Аутентификация
Session и контроля доступа, что и в HTTP-протоколе, однако учетные данные передаются по уже установленному WebSocket-соединению, а не через HTTP-запрос Upgrade. После завершения рукопожатия WebSocket браузер отправляет первое сообщение в формате JSON:
user необязательно: если оно отсутствует или пусто, в качестве имени пользователя используется значение настройки сервера default_session_user настройка сервера (или ее переопределение для конечной точки в конфигурации компонуемых протоколов); по умолчанию — default, если не настроено иначе. Если для default_session_user задана пустая строка, подключения без имени пользователя запрещены: сообщение auth с отсутствующим или пустым user не проходит аутентификацию, сервер закрывает WebSocket с кодом 1008, а при включенном в конфигурации сервера разделе session_log отказ записывается в system.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, включая:
- Подсветку синтаксиса.
- Автодополнение.
- Многострочные запросы.
- Историю команд (хранится на стороне сервера в течение сеанса).
Интеграция с /play
/play встраивает веб-терминал в виде прикрепляемой панели. Его можно включать и выключать с помощью значка терминала на боковой панели или нажатием клавиши ~, когда редактор запросов пуст. При загрузке страница /play определяет доступность /webterminal и скрывает элементы управления терминалом, если конечная точка недоступна (например, когда enable_webterminal имеет значение false).
Интеграция с сайтом документации
play с доступом только для чтения. Благодаря этому примеры с любой страницы можно опробовать, не покидая её. Фиксированная панель резервирует соответствующее место внизу страницы, чтобы не перекрывать элементы нижнего колонтитула. Пока терминал открыт, страница документации заблокирована, а её полоса прокрутки скрыта. Прокрутка над терминалом ограничивается его буфером прокрутки и не прокручивает страницу документации за ним. Нажмите на панель «Терминал ClickHouse» или клавишу ~, чтобы открыть панель с внутренними отступами над ней. Чтобы свернуть её, снова нажмите на панель, используйте шеврон, нажмите ~ или Escape либо перетащите верхний край панели вниз; этим же краем можно изменять её размер. Завершение сеанса — exit или Ctrl+D — также сворачивает панель.
При закрытии панели сеанс и его буфер прокрутки сохраняются: при повторном открытии терминала отображается тот же промпт. Сеанс существует в пределах страницы, поэтому сохраняется при переходе между страницами документации, но не при перезагрузке вкладки браузера: после перезагрузки панель откроется с новым сеансом.
Панель терминала является частью десктопной версии сайта и недоступна при узкой ширине области просмотра.
Вопросы безопасности
- Всегда предоставляйте
/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>.
Доступность платформы
clickhouse-client, реализован поверх переносимых примитивов POSIX (posix_openpt/grantpt/unlockpt), а для Linux предусмотрен отдельный путь с использованием потокобезопасного ptsname_r. Ссылки на /webterminal на главной странице ClickHouse и в /play автоматически скрываются, если конечная точка недоступна (например, когда enable_webterminal установлено в false).