메인 콘텐츠로 건너뛰기

​
개요

Composable protocols를 사용하면 ClickHouse 서버에 대한 TCP 액세스를 더 유연하게 구성할 수 있습니다. 이 구성은 기존 구성과 함께 사용할 수도 있고, 이를 대체할 수도 있습니다.

​
Composable protocols 구성하기

Composable protocols는 XML 설정 파일에서 구성할 수 있습니다. 프로토콜 섹션은 XML 설정 파일에서 protocols 태그로 지정됩니다: 
<protocols>

</protocols>

​
프로토콜 레이어 구성

기본 모듈을 사용해 프로토콜 레이어를 정의할 수 있습니다. 예를 들어 HTTP 레이어를 정의하려면 protocols 섹션에 새 기본 모듈을 추가하면 됩니다: 
<protocols>

  <!-- plain_http 모듈 -->
  <plain_http>
    <type>http</type>
  </plain_http>

</protocols>
모듈은 다음과 같이 구성할 수 있습니다.
  • plain_http - 다른 레이어에서 참조할 수 있는 이름
  • type - 데이터를 처리하기 위해 인스턴스화되는 프로토콜 처리기를 나타냅니다. 다음과 같은 미리 정의된 프로토콜 처리기가 있습니다:
    • tcp - 네이티브 ClickHouse 프로토콜 처리기
    • http - HTTP ClickHouse 프로토콜 처리기
    • tls - TLS 암호화 레이어
    • proxy1 - PROXYv1 레이어
    • mysql - MySQL 호환 프로토콜 처리기
    • postgres - PostgreSQL 호환 프로토콜 처리기
    • prometheus - Prometheus 프로토콜 처리기
    • interserver - ClickHouse interserver 처리기
gRPC 프로토콜 처리기는 Composable protocols에 구현되어 있지 않습니다

​
엔드포인트 구성

엔드포인트(수신 포트)는 <port>와 선택적 <host> 태그로 표시합니다. 예를 들어, 앞서 추가한 HTTP 레이어에서 엔드포인트를 구성하려면 구성을 다음과 같이 수정할 수 있습니다. 
<protocols>

  <plain_http>

    <type>http</type>
    <!-- 엔드포인트 -->
    <host>127.0.0.1</host>
    <port>8123</port>

  </plain_http>

</protocols>
<host> 태그가 생략되면 최상위 config의 <listen_host>가 사용됩니다.

​
레이어 시퀀스 구성

레이어 시퀀스는 <impl> 태그를 사용해 다른 모듈을 참조하는 방식으로 정의합니다. 예를 들어, plain_http 모듈 위에 TLS 레이어를 구성하려면 구성을 다음과 같이 더 수정할 수 있습니다: 
<protocols>

  <!-- http 모듈 -->
  <plain_http>
    <type>http</type>
  </plain_http>

  <!-- plain_http 모듈 위에 TLS 레이어로 구성된 https 모듈 -->
  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
  </https>

</protocols>

​
레이어에 엔드포인트 추가하기

엔드포인트는 모든 레이어에 추가할 수 있습니다. 예를 들어, HTTP(포트 8123)와 HTTPS(포트 8443)용 엔드포인트를 정의할 수 있습니다. 
<protocols>

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
  </https>

</protocols>

​
추가 엔드포인트 정의

추가 엔드포인트는 임의의 모듈을 참조하고 <type> 태그를 생략해 정의할 수 있습니다. 예를 들어, plain_http 모듈에 대해 다음과 같이 another_http 엔드포인트를 정의할 수 있습니다: 
<protocols>

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
  </https>

  <another_http>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8223</port>
  </another_http>

</protocols>

​
엔드포인트별 사용자 지정 HTTP handler

기본적으로 모든 type=http 프로토콜 항목은 동일한 <http_handlers> 구성을 사용합니다. <handlers> 태그를 추가해 다른 구성 섹션을 가리키도록 설정하면 이를 재정의할 수 있습니다. 이렇게 하면 각 HTTP 포트가 서로 다른 HTTP 라우팅 규칙 집합을 제공할 수 있습니다. 예를 들어, 포트 8124에서 자체 handler를 사용하는 대체 HTTP API를 실행하려면: 
<protocols>

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <alt_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8124</port>
    <handlers>http_handlers_alt</handlers>
  </alt_http>

</protocols>

<!-- plain_http(포트 8123)에서 사용하는 기본 핸들러 -->
<http_handlers>
    <defaults/>
</http_handlers>

<!-- alt_http(포트 8124)에서 사용하는 대체 핸들러 -->
<http_handlers_alt>
    <rule>
        <url>/custom</url>
        <handler>
            <type>predefined_query_handler</type>
            <query>SELECT 'custom_endpoint'</query>
        </handler>
    </rule>
    <defaults/>
</http_handlers_alt>
이 예시에서는 포트 8123에 대한 요청이 표준 <http_handlers> 규칙을 사용하고, 포트 8124에 대한 요청은 <http_handlers_alt> 규칙을 사용합니다. <handlers>를 생략하면 엔드포인트는 기본 <http_handlers>로 대체됩니다. 사용자 지정 핸들러 섹션은 <http_handlers>와 동일한 포맷을 따릅니다. 사용자 지정 핸들러 섹션의 변경 사항은 구성 다시 로드 시 감지되며, 해당 엔드포인트는 자동으로 다시 시작됩니다.

​
추가 레이어 매개변수 지정

일부 모듈에는 추가 레이어 매개변수가 있을 수 있습니다. 예를 들어, TLS 레이어에서는 개인 키(privateKeyFile)와 인증서 파일(certificateFile)을 다음과 같이 지정할 수 있습니다: 
<protocols>

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
    <privateKeyFile>another_server.key</privateKeyFile>
    <certificateFile>another_server.crt</certificateFile>
  </https>

</protocols>
마지막 수정일 2026년 6월 10일