웹 터미널

웹 터미널 (Web Terminal)

웹 터미널은 WebSocket을 통해 대화형 clickhouse-client 세션을 제공하는 브라우저 내 인터페이스예요. ClickHouse HTTP 포트의 /webterminal 경로에서 제공돼요.

출처: 문서

본문

웹 터미널은 WebSocket을 통해 대화형 clickhouse-client 세션을 제공하는 브라우저 내 인터페이스예요. ClickHouse HTTP 포트의 /webterminal 경로에서 제공돼요.

어떤 ClickHouse HTTP 포트의 /webterminal로 이동하면(예: http://localhost:8123/webterminal) 터미널을 열 수 있어요.

기능 활성화/비활성화 (Enabling and disabling the feature)

/webterminal 엔드포인트는 기본적으로 활성화되어 있으며 enable_webterminal 서버 설정으로 제어돼요. 비활성화하려면 설정을 false로 설정하세요. 그러면 /webterminal에 대한 요청이 HTTP 상태 403 Forbidden을 반환해요.

<clickhouse>
    <enable_webterminal>false</enable_webterminal>
</clickhouse>

참고: enable_webterminal은 이전의 allow_experimental_webterminal 설정을 대체해요. enable_webterminal이 설정되지 않았을 때 이전 이름은 역호환성을 위해 여전히 인정돼요.

인증 (Authentication)

웹 터미널은 HTTP 프로토콜과 동일한 Session 및 접근 제어 검사로 사용자를 인증하지만, 자격 증명은 HTTP 업그레이드 요청이 아니라 확립된 WebSocket 연결을 통해 대역 내(in-band)로 교환돼요. WebSocket 핸드셰이크가 완료된 후 브라우저는 첫 번째 메시지를 JSON으로 보내요:

{"type": "auth", "user": "<user>", "password": "<password>"}

user 필드는 선택 사항이에요. 생략되거나 비어 있으면 사용자 이름이 default_session_user 서버 설정(또는 컴포저블 프로토콜 구성에서의 엔드포인트별 재정의)으로 폴백하고, 달리 구성되지 않으면 default가 돼요. default_session_user가 빈 문자열로 설정되면 사용자 이름이 없는 연결은 금지돼요. user가 생략되거나 비어 있는 auth 메시지는 인증에 실패하고, 서버는 코드 1008로 WebSocket을 닫으며, 서버 설정에 session_log 섹션이 활성화되어 있으면 그 거부가 user가 비어 있는 LoginFailure 이벤트로 system.session_log에 기록돼요.

이렇게 하면 URL 쿼리 파라미터나 업그레이드 요청에 붙은 Authorization 헤더에 자격 증명을 두는 것을 피할 수 있어요. 그렇게 두면 브라우저 기록, 서버 접근 로그, 리버스 프록시 로그에 남을 수 있거든요. URL 파라미터, HTTP Basic, 업그레이드 요청의 X-ClickHouse-User/X-ClickHouse-Key 헤더는 /webterminal이 의도적으로 참조하지 않아요.

잘못된 자격 증명은 서버가 코드 1008로 WebSocket을 닫게 하고, 브라우저 UI가 자격 증명을 다시 요청해요.

세션이 어떻게 보이는가 (What the session looks like)

인증되면 서버는 슈도 터미널에 연결된 clickhouse-client를 실행하고 그 입출력을 WebSocket으로 브리징해요. 세션은 다음을 포함한 완전한 clickhouse-client 경험을 지원해요:

구문 강조.
자동 완성.
여러 줄 쿼리.
명령 기록(세션 기간 동안 서버 측에 저장).

터미널은 렌더링에 xterm.js를 사용해요. 모든 에셋은 ClickHouse 바이너리 자체에서 제공되며, 서드파티 CDN은 로드되지 않아요.

`/play`와의 통합 (Integration with `/play`)

/play Web SQL UI는 웹 터미널을 도킹 가능한 패널로 임베드해요. 사이드바의 터미널 아이콘으로 토글하거나 쿼리 편집기가 비어 있을 때 ~ 키를 누르면 돼요. /play 페이지는 로드 시 /webterminal 사용 가능 여부를 감지하고, 엔드포인트를 사용할 수 없을 때(예: enable_webterminal이 false로 설정된 경우) 터미널 컨트롤을 숨겨요.

문서 웹사이트와의 통합 (Integration with the documentation website)

이 문서 웹사이트는 페이지 하단의 좁은 개발자 트레이에 같은 터미널을 임베드해요. 읽기 전용 play 사용자로 ClickHouse playground에 연결되므로, 어떤 페이지의 예시든 그 페이지를 떠나지 않고 시도해 볼 수 있어요. 고정된 트레이는 페이지 끝에 적절한 공간을 예약해 두어 푸터 컨트롤을 가리지 않아요. 터미널이 열려 있는 동안 문서 페이지는 잠기고 스크롤바는 숨겨져요. 터미널 위를 스크롤하면 그 스크롤백 안에만 포함되며 뒤의 문서 페이지는 움직이지 않아요. "ClickHouse terminal" 바를 클릭하거나 ~ 키를 눌러 바 위의 패딩된 패널을 열어요. 바를 다시 클릭하거나, 셰브론을 사용하거나, ~ 또는 Escape를 누르거나, 패널 상단 가장자리를 아래로 드래그하면 접혀요. 그 상단 가장자리는 크기도 조정해요. 세션 종료 — exit 또는 Ctrl+D — 도 패널을 접어요.

패널을 닫아도 세션과 그 스크롤백은 유지돼요. 터미널을 다시 열면 같은 프롬프트로 돌아가요. 세션은 페이지에 살아 있으므로 문서 페이지 사이의 탐색은 견디지만, 브라우저 탭의 리로드는 견디지 못해요. 리로드 후에는 패널이 새 세션으로 돌아와요.

터미널 트레이는 웹사이트의 데스크톱 레이아웃의 일부이며 좁은 뷰포트에서는 사용할 수 없어요.

보안 고려 사항 (Security considerations)

웹 터미널은 ClickHouse HTTP 엔드포인트에 대해 인증할 수 있는 누구에게나 대화형 셸 같은 세션을 노출하므로, HTTP 프로토콜에 적용되는 것과 같은 주의 사항이 여기에도 적용돼요:

신뢰할 수 없는 환경에서는 자격 증명과 세션 트래픽을 보호하기 위해 항상 HTTPS로 /webterminal을 제공하세요.
HTTP 프로토콜에 대한 접근을 제한하는 것과 같은 방식으로 네트워크 레벨(방화벽, 리버스 프록시 또는 listen_host 설정)에서 접근을 제한하세요.
엔드포인트는 크로스 오리진 WebSocket 하이재킹을 완화하기 위해 Origin 헤더를 Host와 대조해 검증해요. TLS를 외부에서 종료한다면 그에 맞게 리버스 프록시를 구성하세요.
TLS 종료 리버스 프록시 뒤에서는 브라우저가 https를 쓰더라도 ClickHouse로의 업스트림 연결은 일반 http이므로, 엄격한 동일 오리진 검사가 합법적인 연결을 거부할 수 있어요. 이러한 배포에서는 webterminal_allowed_origins를 WebSocket 세션을 열도록 허용된 전체 오리진의 쉼표 구분 목록으로 설정하세요. 이 설정이 비어 있지 않으면 기본 동일 오리진 검사를 대체해요. 예: <webterminal_allowed_origins>https://example.com,https://app.example.com:8443</webterminal_allowed_origins>.

또한 핸들러는 RFC 6455에 따른 WebSocket 프로토콜 준수를 강제해요. 마스킹되지 않은 클라이언트 프레임, 예약된 opcode, 과대하거나 조각난 제어 프레임, 예약된 RSV 비트는 프로토콜 오류 종료 코드로 거부돼요.

플랫폼 가용성 (Platform availability)

핸들러는 ClickHouse가 지원하는 모든 플랫폼에서 컴파일돼요. 임베디드 clickhouse-client 러너가 사용하는 슈도 터미널 레이어는 이식 가능한 POSIX 프리미티브(posix_openpt/grantpt/unlockpt) 위에 구현되어 있고, 스레드 안전한 ptsname_r을 사용하는 Linux 특화 경로가 있어요. ClickHouse 시작 페이지와 /play의 /webterminal 링크는 엔드포인트를 사용할 수 없을 때(예: enable_webterminal이 false로 설정된 경우) 자동으로 숨겨져요.