Pular para o conteúdo principal
O terminal web é uma interface experimental no navegador que fornece uma sessão interativa do clickhouse-client via WebSocket. Ele está disponível em qualquer porta HTTP do ClickHouse no caminho /webterminal.
O terminal web é um recurso experimental e vem desativado por padrão; consulte Como habilitar o recurso abaixo.

​
Habilitando o recurso

O endpoint /webterminal é controlado pela configuração de servidor allow_experimental_webterminal. Quando essa configuração está como false (o padrão), as solicitações para /webterminal retornam o status HTTP 403 Forbidden. Para habilitá-lo, adicione o seguinte à configuração do servidor: 
<clickhouse>
    <allow_experimental_webterminal>true</allow_experimental_webterminal>
</clickhouse>
Depois de habilitar, acesse /webterminal em qualquer porta HTTP do ClickHouse (por exemplo, http://localhost:8123/webterminal) para abrir o terminal.

​
Autenticação

O terminal web autentica o usuário com as mesmas verificações de Session e de controle de acesso do protocolo HTTP, mas as credenciais são transmitidas pelo próprio canal da conexão WebSocket já estabelecida, em vez de pela solicitação de upgrade HTTP. Após a conclusão do handshake do WebSocket, o navegador envia a primeira mensagem em JSON: 
{"type": "auth", "user": "<user>", "password": "<password>"}
Isso evita colocar credenciais em parâmetros de consulta da URL ou em cabeçalhos Authorization incluídos na solicitação de upgrade, onde elas poderiam acabar no histórico do navegador, nos logs de acesso do servidor e nos logs do proxy reverso. Os parâmetros de URL, o HTTP Basic e os cabeçalhos X-ClickHouse-User/X-ClickHouse-Key na solicitação de upgrade intencionalmente não são considerados pelo /webterminal. Credenciais inválidas fazem o servidor fechar o WebSocket com o código 1008; a interface do navegador solicita as credenciais novamente.

​
Como funciona a sessão

Após a autenticação, o servidor executa o clickhouse-client conectado a um pseudoterminal e encaminha sua entrada e saída via WebSocket. A sessão oferece a experiência completa do clickhouse-client, incluindo:
  • Realce de sintaxe.
  • Autocompletar.
  • Consultas de várias linhas.
  • Histórico de comandos (armazenado no servidor durante a sessão).
O terminal usa xterm.js para renderização. Todos os recursos são fornecidos pelo próprio binário do ClickHouse — nenhum CDN de terceiros é carregado.

​
Integração com /play

A interface Web SQL /play incorpora o terminal web como um painel acoplável. Ative-o pelo ícone de terminal na barra lateral ou pressione a tecla ~ quando o editor de consulta estiver vazio. A página /play detecta a disponibilidade de /webterminal ao carregar e oculta os controles do terminal quando o endpoint não está disponível (por exemplo, quando a configuração experimental não está ativada).

​
Considerações de segurança

O terminal web expõe uma sessão interativa semelhante a um shell para qualquer pessoa que consiga se autenticar no endpoint HTTP do ClickHouse, portanto as mesmas ressalvas aplicáveis ao protocolo HTTP também se aplicam aqui:
  • Sempre disponibilize /webterminal por HTTPS em ambientes não confiáveis para proteger as credenciais e o tráfego da sessão.
  • Restrinja o acesso no nível da rede (firewall, proxy reverso ou a configuração listen_host) da mesma forma que você restringe o acesso ao protocolo HTTP.
  • O endpoint valida o cabeçalho Origin em relação ao Host para mitigar o sequestro de WebSocket entre origens; configure os proxies reversos adequadamente se você encerrar o TLS externamente.
  • Por trás de um proxy reverso que encerra TLS, a conexão upstream com o ClickHouse usa http simples, embora o navegador use https; por isso, a verificação estrita de mesma origem rejeitaria conexões legítimas. Para essas implantações, defina webterminal_allowed_origins como uma lista, separada por vírgulas, de origens completas autorizadas a abrir sessões WebSocket; quando essa configuração não está vazia, ela substitui a verificação padrão de mesma origem. Exemplo: <webterminal_allowed_origins>https://example.com,https://app.example.com:8443</webterminal_allowed_origins>.
O handler também impõe conformidade com o protocolo WebSocket de acordo com a RFC 6455: frames de cliente sem máscara, opcodes reservados, frames de controle grandes demais ou fragmentados e bits RSV reservados são rejeitados com códigos de fechamento por erro de protocolo.

​
Disponibilidade da plataforma

O handler é compilado em todas as plataformas suportadas pelo ClickHouse. A camada de pseudoterminal usada pelo executor integrado do clickhouse-client é implementada com base em primitivas POSIX portáveis (posix_openpt/grantpt/unlockpt), com uma implementação específica para Linux que usa o ptsname_r, que é seguro para threads. Os links para /webterminal na página inicial do ClickHouse e em /play ficam ocultos automaticamente quando o endpoint não está disponível (por exemplo, quando allow_experimental_webterminal não está habilitado).
Última modificação em 10 de junho de 2026