El terminal web es una interfaz en el navegador que proporciona una sesión interactiva de clickhouse-client a través de WebSocket. Está disponible en cualquier puerto HTTP de ClickHouse en la ruta /webterminal.
Ve a /webterminal en cualquier puerto HTTP de ClickHouse (por ejemplo, http://localhost:8123/webterminal) para abrir el terminal.
Activar y desactivar la función
/webterminal está habilitado de forma predeterminada y se controla mediante la configuración del servidor enable_webterminal. Para desactivarlo, establezca la configuración en false; las solicitudes a /webterminal devolverán el código de estado HTTP 403 Forbidden.
enable_webterminal sustituye a la antigua configuración allow_experimental_webterminal. El nombre anterior sigue siendo válido por compatibilidad con versiones anteriores cuando no se ha configurado enable_webterminal.
Session y de control de acceso que el protocolo HTTP, pero las credenciales se intercambian por el propio canal a través de la conexión WebSocket ya establecida, en lugar de hacerlo mediante la solicitud HTTP de actualización. Una vez completado el handshake de WebSocket, el navegador envía el primer mensaje en formato JSON:
El campo user es opcional: cuando se omite o está vacío, se utiliza el nombre de usuario definido por la configuración del servidor default_session_user (o su sobrescritura por endpoint en una configuración de protocolos componibles); de forma predeterminada, default. Si default_session_user se establece como una cadena vacía, se prohíben las conexiones sin nombre de usuario: un mensaje auth con user omitido o vacío no supera la autenticación, el servidor cierra el WebSocket con el código 1008 y, cuando la sección session_log está habilitada en la configuración del servidor, el rechazo se registra en system.session_log como un evento LoginFailure con un user vacío.
Esto evita poner credenciales en los parámetros de consulta de la URL o en los encabezados Authorization enviados con la solicitud de actualización, donde podrían acabar en el historial del navegador, en los registros de acceso del servidor y en los registros del proxy inverso. Los parámetros de URL, HTTP Basic y los encabezados X-ClickHouse-User/X-ClickHouse-Key de la solicitud de actualización deliberadamente no se tienen en cuenta en /webterminal.
Las credenciales no válidas hacen que el servidor cierre el WebSocket con el código 1008; la interfaz de usuario del navegador vuelve a solicitar las credenciales.
Una vez autenticado, el servidor ejecuta clickhouse-client asociado a un pseudoterminal y canaliza su entrada y salida a través de WebSocket. La sesión ofrece toda la experiencia de clickhouse-client, lo que incluye:
- Resaltado de sintaxis.
- Autocompletado.
- Consultas de varias líneas.
- Historial de comandos (almacenado en el servidor mientras dura la sesión).
La terminal usa xterm.js para renderizar. Todos los recursos se sirven desde el propio binario de ClickHouse; no se carga ninguna CDN de terceros.
La interfaz web SQL /play incorpora el terminal web como un panel acoplable. Actívalo con el icono del terminal en la barra lateral o pulsa la tecla ~ cuando el editor de consultas esté vacío. La página /play detecta la disponibilidad de /webterminal al cargarse y oculta los controles del terminal cuando el endpoint no está disponible (por ejemplo, cuando enable_webterminal está configurado como false).
Integración con el sitio web de documentación
play, para que pueda probar los ejemplos de cualquier página sin salir de ella. La bandeja fija reserva un espacio equivalente al final de la página para no ocultar los controles del pie de página. Mientras la terminal está abierta, la página de documentación queda bloqueada y su barra de desplazamiento se oculta. El desplazamiento sobre la terminal queda limitado a su búfer de desplazamiento y no mueve la página de documentación que hay detrás. Haga clic en la barra «ClickHouse terminal» o pulse la tecla ~ para abrir el panel con relleno situado sobre la barra. Vuelva a hacer clic en la barra, use su chevrón, pulse ~ o Escape, o arrastre hacia abajo el borde superior del panel para contraerlo; ese borde también permite cambiar su tamaño. Al finalizar la sesión —exit o Ctrl+D—, el panel también se contrae.
Al cerrar el panel se conservan la sesión y su búfer de desplazamiento: al volver a abrir la terminal, regresará al mismo prompt. La sesión se mantiene en la página, por lo que persiste al navegar entre páginas de documentación, pero no al recargar la pestaña del navegador; tras recargarla, el panel vuelve con una sesión nueva.
La bandeja de la terminal forma parte del diseño de escritorio del sitio web y no está disponible en ventanas gráficas estrechas.
Consideraciones de seguridad
- Sirve siempre
/webterminal mediante HTTPS en entornos no confiables para proteger las credenciales y el tráfico de la sesión.
- Restringe el acceso a nivel de red (
firewall, proxy inverso o la configuración listen_host) del mismo modo que restringes el acceso al protocolo HTTP.
- El endpoint valida el encabezado
Origin con Host para mitigar el secuestro de WebSocket entre orígenes; configura los proxies inversos en consecuencia si terminas TLS de forma externa.
- Detrás de un proxy inverso que termina TLS, la conexión ascendente a ClickHouse usa
http sin cifrar aunque el navegador use https, por lo que la comprobación estricta del mismo origen rechazaría conexiones legítimas. Para estas implementaciones, establece webterminal_allowed_origins como una lista de orígenes completos separados por comas a los que se permite abrir sesiones de WebSocket; cuando esta configuración no está vacía, reemplaza la comprobación predeterminada del mismo origen. Ejemplo: <webterminal_allowed_origins>https://example.com,https://app.example.com:8443</webterminal_allowed_origins>.
El controlador también exige la conformidad con el protocolo WebSocket según la RFC 6455: las tramas de cliente sin enmascarar, los códigos de operación reservados, las tramas de control demasiado grandes o fragmentadas y los bits RSV reservados se rechazan con códigos de cierre por error de protocolo.
El controlador se compila en todas las plataformas compatibles con ClickHouse. La capa de seudoterminal utilizada por el ejecutor integrado de clickhouse-client está implementada sobre primitivas POSIX portátiles (posix_openpt/grantpt/unlockpt), con una implementación específica para Linux que utiliza ptsname_r, que es seguro para hilos. Los enlaces a /webterminal en la página de inicio de ClickHouse y en /play se ocultan automáticamente cuando el endpoint no está disponible (por ejemplo, cuando enable_webterminal se establece en false). 
