메인 콘텐츠로 건너뛰기
웹 터미널은 WebSocket을 통해 대화형 clickhouse-client 세션을 제공하는 실험적인 브라우저 기반 인터페이스입니다. 모든 ClickHouse HTTP 포트의 /webterminal 경로에서 제공됩니다.
웹 터미널은 실험적 기능이며 기본적으로 비활성화되어 있습니다. 자세한 내용은 아래의 기능 활성화를 참조하십시오.

​
기능 활성화

/webterminal endpoint는 allow_experimental_webterminal server setting으로 제어됩니다. 이 설정이 false(기본값)이면 /webterminal에 대한 요청은 HTTP 상태 403 Forbidden을 반환합니다. 활성화하려면 서버 구성에 다음 내용을 추가하세요: 
<clickhouse>
    <allow_experimental_webterminal>true</allow_experimental_webterminal>
</clickhouse>
활성화한 후 터미널을 열려면 아무 ClickHouse HTTP 포트에서나 /webterminal로 이동하십시오(예: http://localhost:8123/webterminal).

​
인증

웹 터미널은 HTTP 프로토콜과 동일한 Session 및 접근 제어 확인 절차를 사용해 사용자를 인증하지만, 자격 증명은 HTTP 업그레이드 요청을 통해 전달되는 것이 아니라 이미 설정된 WebSocket 연결 내에서 인밴드 방식으로 교환됩니다. WebSocket 핸드셰이크가 완료되면 브라우저는 첫 번째 메시지를 JSON으로 전송합니다: 
{"type": "auth", "user": "<user>", "password": "<password>"}
이렇게 하면 업그레이드 요청에 포함된 URL 쿼리 매개변수나 Authorization 헤더에 자격 증명을 넣지 않아도 되므로, 자격 증명이 브라우저 이력, 서버 액세스 로그, 리버스 프록시 로그에 남을 수 있는 위험을 피할 수 있습니다. /webterminal은 업그레이드 요청의 URL 매개변수, HTTP Basic, X-ClickHouse-User/X-ClickHouse-Key 헤더를 의도적으로 확인하지 않습니다. 잘못된 자격 증명이 제공되면 server가 코드 1008로 WebSocket 연결을 종료하고, 브라우저 UI는 자격 증명을 다시 입력하라는 메시지를 표시합니다.

​
세션 화면

인증이 완료되면 서버는 의사 터미널에 연결된 clickhouse-client를 실행하고, 해당 입출력을 WebSocket을 통해 중계합니다. 이 세션은 다음을 포함해 clickhouse-client의 전체 기능을 지원합니다.
  • 구문 강조.
  • 자동 완성.
  • 여러 줄 쿼리.
  • 명령 이력(세션이 유지되는 동안 서버 측에 저장됨).
터미널 렌더링에는 xterm.js를 사용합니다. 모든 리소스는 ClickHouse 바이너리 자체에서 제공되며, 서드파티 CDN은 로드되지 않습니다.

​
/play과의 통합

/play Web SQL UI에는 웹 터미널이 도킹 가능한 패널로 내장되어 있습니다. 사이드바의 터미널 아이콘으로 표시하거나 숨길 수 있으며, 쿼리 편집기가 비어 있을 때는 ~ 키를 누르십시오. /play 페이지는 로드 시점에 /webterminal의 사용 가능 여부를 감지하며, endpoint를 사용할 수 없으면(예를 들어 experimental 설정이 활성화되어 있지 않은 경우) 터미널 컨트롤을 숨깁니다.

​
보안 고려 사항

웹 터미널은 ClickHouse HTTP 엔드포인트에 인증할 수 있는 모든 사용자에게 대화형 셸 형태의 세션을 노출하므로, HTTP 프로토콜에 적용되는 동일한 주의 사항이 여기에도 적용됩니다.
  • 자격 증명과 세션 트래픽을 보호하려면 신뢰할 수 없는 환경에서 /webterminal은 항상 HTTPS로 제공하십시오.
  • HTTP 프로토콜에 대한 접근을 제한하는 것과 동일한 방식으로 네트워크 수준에서 접근을 제한하십시오(방화벽, 리버스 프록시 또는 listen_host 구성).
  • 이 엔드포인트는 교차 출처 WebSocket 하이재킹을 완화하기 위해 Origin 헤더를 Host와 대조하여 검증합니다. 외부에서 TLS를 종료하는 경우 이에 맞게 리버스 프록시를 구성하십시오.
  • TLS를 종료하는 리버스 프록시 뒤에서는 브라우저가 https를 사용하더라도 ClickHouse로의 업스트림 연결은 일반 http이므로, 엄격한 동일 출처 검사가 정상적인 연결을 거부하게 됩니다. 이러한 배포에서는 WebSocket 세션을 열 수 있도록 허용할 전체 origin 목록을 쉼표로 구분해 webterminal_allowed_origins에 설정하십시오. 이 설정이 비어 있지 않으면 기본 동일 출처 검사를 대체합니다. 예시: <webterminal_allowed_origins>https://example.com,https://app.example.com:8443</webterminal_allowed_origins>.
이 handler는 또한 RFC 6455에 따라 WebSocket 프로토콜 준수 여부를 강제합니다. 마스킹되지 않은 클라이언트 frame, 예약된 opcode, 과도하게 크거나 조각난 control frame, 그리고 예약된 RSV bit는 모두 프로토콜 오류 close code와 함께 거부됩니다.

​
플랫폼 지원

이 핸들러는 ClickHouse가 지원하는 모든 플랫폼에서 컴파일됩니다. 내장된 clickhouse-client 실행기에 사용되는 의사 터미널 계층은 이식 가능한 POSIX 기본 요소(posix_openpt/grantpt/unlockpt)를 기반으로 구현되며, Linux 전용 경로에서는 스레드 안전한 ptsname_r를 사용합니다. endpoint를 사용할 수 없으면(예: allow_experimental_webterminal이 enabled 상태가 아닌 경우) ClickHouse 시작 페이지와 /play의 /webterminal 링크가 자동으로 숨겨집니다.
마지막 수정일 2026년 6월 10일