웹 터미널은 WebSocket을 통해 대화형 clickhouse-client 세션을 제공하는 브라우저 기반 인터페이스입니다. 모든 ClickHouse HTTP 포트의 /webterminal 경로에서 제공됩니다.
터미널을 열려면 ClickHouse HTTP 포트의 /webterminal로 이동하십시오(예: http://localhost:8123/webterminal).
/webterminal 엔드포인트는 기본적으로 활성화되어 있으며 enable_webterminal 서버 설정(server setting)으로 제어됩니다. 이를 비활성화하려면 해당 설정을 false로 지정하십시오. 그러면 /webterminal 요청에 대해 HTTP 상태 403 Forbidden이 반환됩니다.
enable_webterminal은 기존 allow_experimental_webterminal 설정을 대체합니다. enable_webterminal이 설정되지 않은 경우에는 하위 호환성을 위해 기존 이름도 계속 사용할 수 있습니다.
Session 및 접근 제어 확인 절차를 사용해 사용자를 인증하지만, 자격 증명은 HTTP 업그레이드 요청을 통해 전달되는 것이 아니라 이미 설정된 WebSocket 연결 내에서 인밴드 방식으로 교환됩니다. WebSocket 핸드셰이크가 완료되면 브라우저는 첫 번째 메시지를 JSON으로 전송합니다:
user 필드는 선택 사항입니다. 생략되거나 비어 있으면 사용자 이름은 default_session_user 서버 설정(또는 composable protocols 구성의 엔드포인트별 재정의)에 지정된 값으로 사용되며, 별도로 구성하지 않은 경우 default입니다. default_session_user가 빈 문자열로 설정되면 사용자 이름이 없는 연결은 허용되지 않습니다. 생략되거나 비어 있는 user가 포함된 auth 메시지는 인증에 실패하고, server는 코드 1008로 WebSocket 연결을 종료하며, 서버 구성에서 session_log 섹션이 활성화된 경우 거부 내역은 빈 user를 가진 LoginFailure 이벤트로 system.session_log에 기록됩니다.
이렇게 하면 업그레이드 요청에 포함된 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 Web SQL UI에는 웹 터미널이 도킹 가능한 패널로 내장되어 있습니다. 사이드바의 터미널 아이콘으로 표시하거나 숨길 수 있으며, 쿼리 편집기가 비어 있을 때는 ~ 키를 누르십시오. /play 페이지는 로드 시점에 /webterminal의 사용 가능 여부를 감지하며, 엔드포인트를 사용할 수 없으면(예를 들어 enable_webterminal이 false로 설정된 경우) 터미널 컨트롤을 숨깁니다.
이 문서 웹사이트는 페이지 하단의 좁은 개발자 트레이에 동일한 터미널을 내장하고 있으며, 읽기 전용 play 사용자로 ClickHouse playground에 연결됩니다. 따라서 어느 페이지에서나 페이지를 벗어나지 않고 예시를 실행해 볼 수 있습니다. 고정 트레이는 푸터 컨트롤을 가리지 않도록 페이지 하단에 그에 맞는 공간을 확보합니다. 터미널이 열려 있는 동안 문서 페이지는 잠기고 스크롤바는 숨겨집니다. 터미널 위에서 스크롤해도 터미널의 스크롤백 내에서만 스크롤되며, 뒤의 문서 페이지는 이동하지 않습니다. “ClickHouse terminal” 바를 클릭하거나 ~ 키를 눌러 바 위의 여백이 있는 패널을 여십시오. 바를 다시 클릭하거나 셰브론을 사용하거나 ~ 또는 Escape를 누르거나 패널의 상단 가장자리를 아래로 끌어 패널을 접을 수 있습니다. 이 상단 가장자리로 패널 크기도 조정할 수 있습니다. exit 또는 Ctrl+D로 세션을 종료하면 패널도 접힙니다.
패널을 닫아도 세션과 스크롤백은 유지됩니다. 터미널을 다시 열면 동일한 프롬프트로 돌아갑니다. 세션은 페이지에 유지되므로 문서 페이지 간 이동 후에도 유지되지만, 브라우저 탭을 새로고침하면 유지되지 않습니다. 새로고침 후에는 새 세션으로 패널이 다시 표시됩니다.
터미널 트레이는 웹사이트의 데스크톱 레이아웃에 포함되며, 좁은 뷰포트에서는 사용할 수 없습니다.
웹 터미널은 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를 사용합니다. 엔드포인트를 사용할 수 없으면(예: enable_webterminal이 false로 설정된 경우) ClickHouse 시작 페이지와 /play의 /webterminal 링크가 자동으로 숨겨집니다. 
