Перейти к основному содержанию

​
Обзор

Составные протоколы позволяют более гибко настраивать TCP-доступ к серверу ClickHouse. Такая конфигурация может использоваться наряду с обычной или полностью её заменять.

​
Настройка составных протоколов

Составные протоколы можно настраивать в 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
Обработчик протокола 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> не указан, используется <listen_host> из корневой конфигурации.

​
Настройка последовательностей слоёв

Последовательности слоёв определяются с помощью тега <impl> и ссылки на другой модуль. Например, чтобы настроить слой TLS поверх нашего модуля plain_http, мы можем дополнительно изменить конфигурацию следующим образом: 
<protocols>

  <!-- модуль http -->
  <plain_http>
    <type>http</type>
  </plain_http>

  <!-- модуль https, настроенный как слой tls поверх модуля plain_http -->
  <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>. Например, можно определить конечную точку another_http для модуля plain_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-обработчики для отдельных эндпоинтов

По умолчанию все записи протокола type=http используют одну и ту же конфигурацию <http_handlers>. Это можно переопределить, добавив тег <handlers>, который ссылается на другой раздел конфигурации. Благодаря этому каждый HTTP-порт может обслуживать свой набор правил HTTP-маршрутизации. Например, чтобы запустить альтернативный HTTP API на порту 8124 с собственными обработчиками: 
<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>
Последнее изменение 10 июня 2026 г.