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.
<clickhouse>
<enable_webterminal>false</enable_webterminal>
</clickhouse>
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:
{"type": "auth", "user": "<user>", "password": "<password>"}
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).
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). 
