Saltar al contenido principal

​
Descripción general

Los protocolos componibles permiten una configuración más flexible del acceso TCP al servidor de ClickHouse. Esta configuración puede coexistir con la configuración convencional o reemplazarla.

​
Configuración de protocolos componibles

Los protocolos componibles se pueden configurar en un archivo de configuración XML. La sección de protocolos se indica con etiquetas protocols en el archivo de configuración XML: 
<protocols>

</protocols>

​
Configuración de las capas de protocolo

Puede definir capas de protocolo con módulos básicos. Por ejemplo, para definir una capa HTTP, puede añadir un módulo básico nuevo a la sección protocols: 
<protocols>

  <!-- módulo plain_http -->
  <plain_http>
    <type>http</type>
  </plain_http>

</protocols>
Los módulos se pueden configurar de la siguiente manera:
  • plain_http - nombre al que puede hacer referencia otra capa
  • type - indica el manejador de protocolo que se instanciará para procesar datos. Tiene el siguiente conjunto de manejadores de protocolo predefinidos:
    • tcp - manejador del protocolo nativo de ClickHouse
    • http - manejador del protocolo HTTP de ClickHouse
    • tls - capa de cifrado TLS
    • proxy1 - capa PROXYv1
    • mysql - manejador del protocolo de compatibilidad con MySQL
    • postgres - manejador del protocolo de compatibilidad con Postgres
    • prometheus - manejador del protocolo Prometheus
    • interserver - manejador interserver de ClickHouse
El manejador del protocolo gRPC no está implementado para protocolos componibles

​
Configuración de los endpoints

Los endpoints (puertos de escucha) se indican con las etiquetas <port> y, opcionalmente, <host>. Por ejemplo, para configurar un endpoint en la capa HTTP añadida anteriormente, podríamos modificar la configuración de la siguiente manera: 
<protocols>

  <plain_http>

    <type>http</type>
    <!-- endpoint -->
    <host>127.0.0.1</host>
    <port>8123</port>

  </plain_http>

</protocols>
Si se omite la etiqueta <host>, se usa <listen_host> de la configuración principal.

​
Configuración de secuencias de capas

Las secuencias de capas se definen con la etiqueta <impl> y haciendo referencia a otro módulo. Por ejemplo, para configurar una capa TLS sobre nuestro módulo plain_http, podríamos seguir modificando nuestra configuración de la siguiente manera: 
<protocols>

  <!-- módulo http -->
  <plain_http>
    <type>http</type>
  </plain_http>

  <!-- módulo https configurado como una capa TLS sobre el módulo plain_http -->
  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
  </https>

</protocols>

​
Asociar endpoints a las capas

Los endpoints se pueden asociar a cualquier capa. Por ejemplo, podemos definir endpoints para HTTP (puerto 8123) y HTTPS (puerto 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>

​
Definición de endpoints adicionales

Los endpoints adicionales pueden definirse haciendo referencia a cualquier módulo y omitiendo la etiqueta <type>. Por ejemplo, podemos definir el endpoint another_http para el módulo plain_http de la siguiente manera: 
<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>

​
Manejadores HTTP personalizados por endpoint

De forma predeterminada, todas las entradas de protocolo type=http comparten la misma configuración <http_handlers>. Puede cambiar esto añadiendo una etiqueta <handlers> que apunte a una sección de configuración distinta. Esto permite que cada puerto HTTP sirva un conjunto diferente de reglas de enrutamiento HTTP. Por ejemplo, para ejecutar una API HTTP alternativa en el puerto 8124 con sus propios manejadores: 
<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>

<!-- Handlers predeterminados usados por plain_http (puerto 8123) -->
<http_handlers>
    <defaults/>
</http_handlers>

<!-- Handlers alternativos usados por alt_http (puerto 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>
En este ejemplo, las solicitudes al puerto 8123 usan las reglas estándar de <http_handlers>, mientras que las solicitudes al puerto 8124 usan las reglas de <http_handlers_alt>. Si se omite <handlers>, el endpoint vuelve al valor predeterminado <http_handlers>. La sección de handlers personalizados sigue el mismo formato que <http_handlers>. Los cambios en la sección de handlers personalizados se detectan durante la recarga de la configuración, y el endpoint correspondiente se reinicia automáticamente.

​
Especificar parámetros adicionales de la capa

Algunos módulos pueden incluir parámetros adicionales de la capa. Por ejemplo, la capa TLS permite especificar una clave privada (privateKeyFile) y archivos de certificado (certificateFile) de la siguiente manera: 
<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>
Última modificación el 10 de junio de 2026