Saltar al contenido principal
El terminal web es una interfaz experimental 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.
El terminal web es una función experimental y está desactivado de forma predeterminada; consulta Habilitar la función a continuación.

​
Habilitar la funcionalidad

El endpoint /webterminal está controlado por la configuración del servidor allow_experimental_webterminal. Cuando esta configuración es false (el valor predeterminado), las solicitudes a /webterminal devuelven el estado HTTP 403 Forbidden. Para habilitarlo, añade lo siguiente a la configuración del servidor: 
<clickhouse>
    <allow_experimental_webterminal>true</allow_experimental_webterminal>
</clickhouse>
Después de habilitarlo, ve a /webterminal en cualquier puerto HTTP de ClickHouse (por ejemplo, http://localhost:8123/webterminal) para abrir el terminal.

​
Autenticación

El terminal web autentica al usuario con las mismas comprobaciones de 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>"}
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.

​
Cómo es la sesión

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.

​
Integración con /play

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 la configuración experimental no está activada).

​
Consideraciones de seguridad

El terminal web expone una sesión interactiva similar a un shell a cualquier persona que pueda autenticarse en el endpoint HTTP de ClickHouse, por lo que aquí se aplican las mismas advertencias que para el protocolo HTTP:
  • 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.

​
Disponibilidad de la plataforma

El manejador 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 allow_experimental_webterminal no está habilitado).
Última modificación el 10 de junio de 2026