Версия: 5.2

Конфигурация clickhouse-server

Структура конфигурации ClickHouse

Основные каталоги и файлы

Рекомендуемая структура (используется стандартная раскладка пакета ClickHouse):

Элемент	Путь по умолчанию	Назначение
Основной конфигурационный файл сервера	`/etc/clickhouse-server/config.xml`	Базовые настройки, подключает `config.d`
Дополнительный файл конфигурации сервера	`/etc/clickhouse-server/config.d/*.xml`	Переопределения и добавления к `config.xml`
Конфигурационный файл пользователей	`/etc/clickhouse-server/users.xml`	Базовые пользователи, профили, квоты
Дополнительный файл конфигурации пользователей	`/etc/clickhouse-server/users.d/*.xml`	Дополнительные пользователи, профили, квоты
Конфигурационный файл ClickHouse Keeper	`/etc/clickhouse-keeper/keeper_config.xml`	Настройка процесса Keeper
Дополнительный файл конфигурации Keeper (опционально)	`/etc/clickhouse-keeper/keeper_config.d/*.xml`	Расширение конфигурации Keeper

Ключевой принцип: не изменять базовый config.xml, а добавлять свои настройки в отдельные файлы внутри config.d/. Аналогично для users.xml и users.d/.

Single-node конфигурация `clickhouse-server`

Раздел описывает минимально необходимую конфигурацию для одиночного узла, на базе которой затем строится кластер.

Сетевые порты и `listen_host`

Файл: /etc/clickhouse-server/config.d/network.xml (если SSL не выделяется отдельно)

<clickhouse>
  <!-- HTTP-интерфейс (ClickHouse HTTP API) -->
  <http_port>8123</http_port>

  <!-- Нативный TCP-порт для clickhouse-client и драйверов -->
  <tcp_port>9000</tcp_port>

  <!-- Межсерверный HTTP-порт (репликация, Distributed) -->
  <interserver_http_port>9009</interserver_http_port>

  <!-- Разрешения подключений со всех интерфейсов.
       Для боевой среды рекомендуется ограничить список адресов/сетей. -->
  <listen_host>0.0.0.0</listen_host>
</clickhouse>

Стратегии настройки TLS:

оставить незашифрованные порты только во внутренней сети
полностью перейти на защищенные порты и удалить http_port/tcp_port

Пользователи и профили

Базовый пользователь default создается автоматически. Для прикладного доступа рекомендуется завести отдельного пользователя в users.d.

Файл: /etc/clickhouse-server/users.d/app_user.xml

<clickhouse>
  <users>
    <app_user>
      <!-- Рекомендуется использовать SHA-256 хэш, вместо plain-пароля -->
      <!-- Пример: password_sha256_hex>...</password_sha256_hex> -->
      <password>StrongAppUserPass</password>

      <!-- Профиль (набор настроек по умолчанию) -->
      <profile>default</profile>

      <!-- Сетевые ограничения (пример – доступ из любой сети) -->
      <networks>
        <ip>::/0</ip>
      </networks>

      <!-- Квота (опционально, можно оставить default) -->
      <quota>default</quota>
    </app_user>
  </users>
</clickhouse>

Детальная настройка TLS/SSL

Для обеспечения шифрования как клиентских, так и межсерверных соединений используется отдельный конфигурационный файл ssl.xml.

Файл: /etc/clickhouse-server/config.d/ssl.xml

<clickhouse>
    <!-- Безопасные порты -->
    <tcp_port_secure>9440</tcp_port_secure>
    <!-- <http_port>8123</http_port> -->
    <https_port>8443</https_port>              <!-- HTTPS API -->
    <interserver_https_port>9010</interserver_https_port>
    <interserver_https_host>hostname-1</interserver_https_host>

    <!-- Отключаем небезопасные порты (если нужно полное ограничение) -->
    <http_port remove="1"/>
    <tcp_port remove="1"/>
    <interserver_http_port remove="1"/>

    <!-- Включаем доступ по всем IP, если нужно внешнее подключение -->
    <listen_host>::</listen_host>

    <!-- TLS/SSL настройки -->
    <openSSL>
        <server>
            <!-- Сертификат сервера -->
            <certificateFile>/etc/clickhouse-server/ssl/clickhouse-node-1.crt</certificateFile>

            <!-- Приватный ключ сервера -->
            <privateKeyFile>/etc/clickhouse-server/ssl/clickhouse-node-1.key</privateKeyFile>

            <!-- CA, который подписал сертификат сервера -->
            <caConfig>/etc/clickhouse-server/ssl/ca-cert.pem</caConfig>

            <!-- strict: клиент должен иметь доверенный CA,
            relaxed - «мягкий» режим проверки TLS-сертификатов? который не требует сертификат клиента,
            none: валидация клиента не требуется -->
            <verificationMode>relaxed</verificationMode>

            <!-- Использовать кэш TLS-сессий (повышает производительность) -->
            <cacheSessions>true</cacheSessions>

            <!-- Поддержка TLS 1.2 и выше -->
            <disableProtocols>SSLv2,SSLv3,TLSv1,TLSv1.1</disableProtocols>
        </server>

        <client>
            <!-- Используем тот же CA для валидации серверов, если ClickHouse будет клиентом -->
            <caConfig>/etc/clickhouse-server/ssl/ca-cert.pem</caConfig>

            <!-- Не загружать системные CA -->
            <loadDefaultCAFile>false</loadDefaultCAFile>

            <!-- strict — требуется проверка; none — можно без валидации -->
            <verificationMode>none</verificationMode>
        </client>
    </openSSL>

    <!-- Настройка интерсерверного взаимодействия -->
    <interserver_scheme>https</interserver_scheme>
</clickhouse>

Порты и схема interserver HTTPS

Для доступности портов внешним клиентом используйте следующие команды:

для систем на базе Debian, использующих ufw:

sudo ufw allow 9000/tcp  # Открыть порт для TCP соединений ClickHouse
sudo ufw allow 8123/tcp  # Открыть порт для HTTP интерфейса ClickHouse
sudo ufw reload          # Применить изменения

для систем на базе RHEL, использующих firewalld:

sudo firewall-cmd --zone=public --add-port=9000/tcp --permanent  # Открыть порт для TCP соединений ClickHouse
sudo firewall-cmd --zone=public --add-port=8123/tcp --permanent  # Открыть порт для HTTP интерфейса ClickHouse
sudo firewall-cmd --reload  # Применить изменения

Полный список портов, используемых clickhouse:

Порт	Описание
8123	Стандартный HTTP-порт.
8443	Стандартный HTTP SSL/TLS-порт.
9000	Порт нативного протокола (также известен как ClickHouse TCP-протокол). Используется приложениями и процессами ClickHouse, такими как `clickhouse-server`, `clickhouse-client` и родные инструменты ClickHouse. Используется для межсерверной коммуникации для распределенных запросов.
9004	Порт эмуляции MySQL.
9005	Порт эмуляции PostgreSQL (также используется для безопасного соединения, если включен SSL для ClickHouse).
9009	Порт межсерверной коммуникации для низкоуровневого доступа к данным. Используется для обмена данными, репликации и межсерверной коммуникации.
9010	SSL/TLS для межсерверной коммуникации.
9011	Порт нативного протокола PROXYv1.
9019	Порт JDBC моста.
9100	Порт gRPC.
9181	Рекомендуемый порт ClickHouse Keeper.
9234	Рекомендуемый порт ClickHouse Keeper Raft (также используется для безопасной коммуникации, если `<secure>1</secure>` включен).
9363	Стандартный порт для метрик Prometheus.
9281	Рекомендуемый порт Secure SSL для ClickHouse Keeper.
9440	SSL/TLS порт нативного протокола.
42000	Стандартный порт для Graphite.

<tcp_port_secure>9440</tcp_port_secure> — защищенный TCP-порт для нативного протокола ClickHouse (аналог tcp_port, но поверх TLS). На него подключается clickhouse-client с флагом --secure и драйверы, работающие по TLS
<https_port>8443</https_port> — HTTPS-вариант HTTP API. Все REST-запросы и внешние интеграции, использующие HTTPS, должны использовать этот порт
<interserver_https_port>9010</interserver_https_port> — порт для межсерверного HTTPS (репликация, внутренний HTTP-протокол между узлами). Это TLS-аналог interserver_http_port
<interserver_https_host>hostname-1</interserver_https_host> — имя хоста, по которому другие узлы обращаются к данному серверу. Оно должно:
- корректно разрешаться в IP-адрес данного сервера
- быть включено в поле SubjectAltName (SAN) сертификата сервера clickhouse-node-1.crt (рекомендуется, чтобы CN совпадал/был согласован)
Блоки с remove="1" отключают незашифрованные порты:
- <http_port remove="1"/> — запрет HTTP на 8123
- <tcp_port remove="1"/> — запрет незашифрованного TCP (обычно 9000)
- <interserver_http_port remove="1"/> — запрет незашифрованного межсерверного HTTP (обычно 9009)
В результате сервер принимает только TLS-соединения — как от клиентов, так и от других узлов кластера.
<listen_host>::</listen_host> — прослушивание на всех сетевых интерфейсах (IPv6 any + IPv4). Обязательно ограничьте сетевой доступ к ClickHouse с помощью firewall/ACL. Сервер должен быть доступен только из доверенных сетей
<interserver_scheme>https</interserver_scheme> — указание ClickHouse использовать HTTPS-схему для межсерверных запросов и репликации, что обеспечивает согласованную работу с портом, указанным в interserver_https_port

Серверные SSL-настройки

Секция <server> описывает, какие сертификаты и параметры используются, когда ClickHouse выступает в роли TLS-сервера (принимает подключения):

<certificateFile> — путь к X.509-сертификату сервера в формате PEM:
- содержит открытый ключ
- подписан внутренним CA (ca-cert.pem)
- должен содержать корректные SAN (DNS-имена) и/или CN для хоста
<privateKeyFile> — путь к приватному ключу сервера:
- уникален для каждого узла
- не должен копироваться на другие машины
- права доступа должны ограничивать чтение только пользователю, от которого запущен clickhouse-server
<caConfig> — сертификат (или цепочка сертификатов) центра сертификации (CA), которым подписан серверный сертификат:
- используется при проверке клиентских сертификатов в случае verificationMode=relaxed
- может использоваться при клиентских подключениях (если этот же CA задан в <client>)
<verificationMode>relaxed</verificationMode> — сервер не проверяет сертификат клиента. Это означает:
- соединение шифруется
- но TLS не используется для аутентификации клиента (клиент идентифицируется только по логину/паролю, настройкам пользователя и сетям)
<cacheSessions>true</cacheSessions> — включает кэширование TLS-сессий, что уменьшает накладные расходы на установку большого числа краткоживущих соединений
<disableProtocols>SSLv2,SSLv3,TLSv1,TLSv1.1</disableProtocols> — отключает устаревшие и небезопасные протоколы, оставляя только TLSv1.2+

Режимы проверки TLS в ClickHouse (verificationMode)

Поддерживаемые режимы:

none — сертификаты не проверяются. Соединение шифруется, но допускаются самоподписанные, просроченные или не совпадающие по имени сертификаты
relaxed — проверка сертификатов выполняется, но клиентский сертификат не обязателен. Если сторона прислала сертификат, он проверяется по CA и сроку; если сертификата нет — соединение разрешается
strict — строгая проверка. Наличие валидного сертификата обязательно (для стороны, которая должна его представлять). В контексте mTLS: клиент должен предоставить валидный сертификат, иначе соединение не будет установлено

Клиентские SSL-настройки

Раздел <client> описывает параметры, которые ClickHouse использует, когда сам инициирует исходящие TLS-подключения (например, к другим узлам кластера по secure-портам или к внешним HTTPS-ресурсам):

<caConfig>/etc/clickhouse-server/ssl/ca-cert.pem</caConfig> — тот же CA, которым подписаны сертификаты всех узлов кластера. Это позволяет ClickHouse:
- проверить подлинность сертификатов других узлов
- убедиться, что соединение установлено именно с тем сервером, которому он доверяет
<loadDefaultCAFile>false</loadDefaultCAFile> — запрет использовать системный набор доверенных CA. Это повышает безопасность, так как доверяются только внутренние сертификаты
<verificationMode>none</verificationMode> — ClickHouse не проверяет валидность сертификатов удаленных серверов. Снова: шифрование есть, но подлинность удаленного сервера не подтверждается. Рекомендуется переключить в relaxed и проверить соответствие CN/SAN во всех сертификатах

Набор сертификатов и ключей на каждом узле

Для корректной работы такой конфигурации на каждом узле кластера должны быть:

CA-сертификат (/etc/clickhouse-server/ssl/ca-cert.pem):
- единый для всех узлов
- публичная часть внутреннего центра сертификации
- используется как для проверки серверных сертификатов, так и (опционально) клиентских
Сертификат узла (clickhouse-node-1.crt, clickhouse-node-2.crt и т.д.):
- уникальный для каждого сервера
- подписан вышеупомянутым CA
Приватный ключ узла (clickhouse-node-1.key, clickhouse-node-2.key и т.д.):
- уникальный для каждого сервера
- запрещено копировать на другие серверы
- запрещено хранить в системах контроля версий

Типичный сценарий генерации:

создается приватный ключ CA
генерируется самоподписанный CA-сертификат (ca-cert.pem)
для каждого узла:
- создается уникальный приватный ключ узла
- формируется запрос на подпись сертификата (CSR) с указанием CN и SAN
- CSR подписывается приватным ключом CA, в результате чего создается узловой сертификат

Переход к кластерному режиму

Подключение `clickhouse-server` к Keeper

На каждом сервере ClickHouse нужно описать подключение к Keeper через раздел <zookeeper>. Файл можно назвать, например, /etc/clickhouse-server/config.d/keeper.xml.

Файл: /etc/clickhouse-server/config.d/keeper.xml

<clickhouse>
  <zookeeper>
    <!-- В dev-окружении подключаемся к одному Keeper-узлу -->
    <node>
      <host>hostname-1</host>
      <port>9181</port> <!-- клиентский порт Keeper -->
    </node>

    <session_timeout_ms>30000</session_timeout_ms>
    <operation_timeout_ms>10000</operation_timeout_ms>
  </zookeeper>
</clickhouse>

При добавлении новых Keeper-узлов добавляются дополнительные <node>:

<zookeeper>
  <node>
    <host>keeper1.local</host>
    <port>9181</port>
  </node>
  <node>
    <host>keeper2.local</host>
    <port>9181</port>
  </node>
  <node>
    <host>keeper3.local</host>
    <port>9181</port>
  </node>
</zookeeper>

Конфигурация кластера

Базовая конфигурация remote_servers для кластера с одним шардом и двумя репликами.

Файл: /etc/clickhouse-server/config.d/cluster.xml

<clickhouse>
  <remote_servers>
    <cluster_name>
      <!-- Секрет должен быть одинаковым на всех узлах кластера -->
      <secret>cluster_name_shared_secret</secret>

      <shard>
        <replica>
          <host>hostname-1</host>
          <port>9440</port>
          <secure>1</secure>
        </replica>
        <replica>
          <host>hostname-2</host>
          <port>9440</port>
          <secure>1</secure>
        </replica>
      </shard>
    </cluster_name>
  </remote_servers>
</clickhouse>

подзапросы на шарды выполняются от имени того же пользователя, который инициировал исходный запрос на входном узле
легитимность запросов подтверждается с помощью общего криптографического секрета secret, а не паролей пользователей
отсутствует необходимость хранить пароли пользователей в конфигурационном файле cluster.xml

Макросы кластера (`macros.xml`)

Макросы позволяют использовать {cluster}, {shard}, {replica} в определениях таблиц и запросах. Настройки должны отличаться между узлами только значением replica.

Пример конфигурации

Файл: /etc/clickhouse-server/config.d/macros.xml

<clickhouse>
  <macros>
    <cluster>cluster_name</cluster>
    <shard>1</shard>
    <replica>hostname-1</replica>
  </macros>
</clickhouse>

Межсерверные учетные данные

Для обеспечения безопасного обмена данными между репликами (Replicated*) рекомендуется настроить interserver_http_credentials. Конфигурация должна быть идентичной на всех узлах кластера.

Файл: /etc/clickhouse-server/config.d/interserver.xml

<clickhouse>
  <interserver_http_credentials>
    <user>interserver</user>
    <password>InterServerStrongPass</password>
    <!-- Рекомендуется отключить пустой пароль -->
    <allow_empty>false</allow_empty>
  </interserver_http_credentials>
</clickhouse>

Учетные данные используются для аутентификации в следующих сценариях:

межсерверная репликация — защита HTTP-соединений между репликами
внутренние операции — аутентификация служебных HTTP-запросов между узлами кластера

Преимущества схемы разделения прав:

обычные пользователи (default, app_user) не требуют и не получают прав на выполнение системных операций репликации
пароль interserver для клиентских подключений и не должен присутствовать в клиентских конфигурациях

Проверка работоспособности кластера

После настройки всех файлов:

Перезапустить Keeper и ClickHouse на всех узлах с помощью следующих команд:

systemctl restart clickhouse-keeper
systemctl restart clickhouse-server

Проверить, что кластер виден:

SELECT *
FROM system.clusters
WHERE cluster = 'cluster_name';

Проверить подключение к Keeper:

SELECT *
FROM system.zookeeper
LIMIT 10;

Успешное выполнение запроса с возвратом данных или списка директорий свидетельствует о работоспособности соединения с Keeper.

Структура конфигурации ClickHouse​

Основные каталоги и файлы​

Single-node конфигурация clickhouse-server​

Сетевые порты и listen_host​

Пользователи и профили​

Детальная настройка TLS/SSL​

Порты и схема interserver HTTPS​

Серверные SSL-настройки​

Клиентские SSL-настройки​

Набор сертификатов и ключей на каждом узле​

Переход к кластерному режиму​

Подключение clickhouse-server к Keeper​

Конфигурация кластера​

Макросы кластера (macros.xml)​

Пример конфигурации​

Межсерверные учетные данные​

Проверка работоспособности кластера​