Chproxy

Chproxy — это HTTP-прокси и балансировщик нагрузки с открытым исходным кодом, специально разработанный для базы данных ClickHouse^®. Это проект сообщества с открытым исходным кодом, который предоставляет мощные возможности для управления трафиком и обеспечения безопасности при работе с кластерами ClickHouse^®.

Chproxy представляет собой надежное и функциональное решение для организации безопасного и эффективного доступа к кластерам ClickHouse^® в производственных средах.

Маршрутизация и балансировка нагрузки

• Проксирование запросов к различным кластерам ClickHouse^® в зависимости от входящего пользователя.
• Равномерное распределение запросов между репликами и узлами с использованием техники least loaded + round robin.
• Мониторинг состояния узлов и предотвращение отправки запросов на неисправные узлы.

Управление пользователями и безопасность

• Сопоставление входящих пользователей с пользователями кластеров, что предотвращает раскрытие реальных имен пользователей и паролей.
• Возможность сопоставления нескольких различных входящих пользователей с одним пользователем ClickHouse^®.
• Ограничение HTTP- и HTTPS-доступа по спискам IP/IP-масок.
• Ограничение доступа для каждого пользователя по спискам IP/IP-масок.

Контроль ресурсов и производительности

• Ограничение продолжительности запросов для каждого пользователя с принудительной остановкой через KILL QUERY.
• Ограничение частоты запросов для каждого пользователя.
• Ограничение количества одновременных запросов для каждого пользователя.
• Задержка выполнения запросов до соответствия пользовательским ограничениям.
• Независимая настройка всех ограничений для каждого входящего пользователя и каждого пользователя кластера.

Кеширование и оптимизация

• Настраиваемое кеширование ответов для каждого пользователя.
• Встроенная защита кешей ответов от проблемы thundering herd.

Безопасность соединений

• Поддержка входящих запросов через HTTP и HTTPS.
• Автоматическое получение и обновление HTTPS-сертификатов через Let’s Encrypt^®.
• Проксирование запросов к каждому настроенному кластеру через HTTP или HTTPS.

Мониторинг и управление

• Предоставление полезных метрик в формате Prometheus.
• Добавление информации о пользователях и адресах в заголовок User-Agent для возможности запроса из system.query_log.http_user_agent.
• Обновление конфигурации без перезапуска через сигнал SIGHUP.
• Простое управление и запуск — достаточно передать путь к файлу конфигурации единственному бинарному файлу chproxy.

1. Создайте облачную сеть и подсеть, в которой будет находиться виртуальная машина (ВМ).

2. Создайте группу безопасности для ВМ vm-proxy в созданной облачной сети и настройте правила:

   Направление трафика	Описание	Диапазон портов	Протокол	Источник / Назначение	CIDR-блоки
   Входящий	ClickHouse	8123	TCP	CIDR	0.0.0.0/0
   Входящий	HTTP	8080	TCP	CIDR	0.0.0.0/0
   Входящий	SSH	22	TCP	CIDR	0.0.0.0/0
   Исходящий	Any Egress	0-65535	Any	CIDR	0.0.0.0/0

3. Создайте группу безопасности для ВМ vm-test в той же сети и настройте правила:

   Направление трафика	Описание	Диапазон портов	Протокол	Источник / Назначение	CIDR-блоки
   Входящий	ClickHouse	8123	TCP	CIDR	0.0.0.0/0
   Входящий	HTTP	80	TCP	CIDR	0.0.0.0/0
   Входящий	SSH	22	TCP	CIDR	0.0.0.0/0
   Исходящий	Any Egress	0-65535	Any	CIDR	0.0.0.0/0

4. Получите пару SSH-ключей для подключения к ВМ.

5. Создайте и настройте ВМ для тестирования работы приложения:

   1. При создании ВМ укажите параметры:

      1. В блоке Образ загрузочного диска на вкладке Marketplace выберите образ Ubuntu или Debian, например Ubuntu 24.04.
      2. В блоке Сетевые настройки укажите облачную сеть, подсеть и группу безопасности для ВМ vm-test, созданные ранее.
      3. В блоке Доступ укажите имя пользователя и публичный SSH-ключ для подключения к ВМ.
      4. В блоке Общая информация укажите имя ВМ — vm-test.

   2. Узнайте публичный IP-адрес ВМ vm-test.

   3. Подключитесь к ВМ vm-test по SSH. Для этого используйте имя пользователя, которое вы задали при создании ВМ, и закрытый SSH-ключ, созданный ранее.

   4. Установите ClickHouse Server, ClickHouse Client и ClickHouse Keeper, выполнив инструкцию Install ClickHouse on Debian/Ubuntu.

   5. Добавьте в файл /etc/clickhouse-server/config.xml сразу после строки <clickhouse>:

          <listen_host>0.0.0.0</listen_host>
      

      В продакшн-среде не рекомендуется использовать адрес 0.0.0.0.

   6. Добавьте правило, разрешающее входящее соединение к порту 8123:

      sudo iptables -I INPUT -p tcp --dport 8123 -j ACCEPT
      sudo apt-get update && sudo apt-get install -y netfilter-persistent
      sudo netfilter-persistent save
      

   7. Перезапустите ClickHouse Server:

      sudo systemctl restart clickhouse-server
      

6. Установите и настройте приложение:

   1. В Marketplace найдите продукт Chproxy и нажмите Создать ВМ.

      1. В блоке Сетевые настройки укажите облачную сеть, подсеть и группу безопасности для ВМ vm-proxy, созданные ранее.

      2. В блоке Доступ укажите имя пользователя и публичный SSH-ключ для подключения к ВМ.

      3. В блоке Общая информация укажите имя ВМ — vm-proxy.

      4. Завершите создание ВМ и нажмите Создать ВМ.

         Дождитесь создания ВМ и установки приложения — это может занять 10 минут.

   2. Узнайте публичный IP-адрес ВМ vm-proxy.

   3. Подключитесь к ВМ vm-proxy по SSH. Для этого используйте имя пользователя, которое вы задали при создании ВМ, и закрытый SSH-ключ, созданный ранее.

   4. Замените содержимое файла /etc/chproxy/chproxy.yml на следующее:

      hack_me_please: true
      
      server:
        http:
            listen_addr: ":8123"
      
      users:
        - name: "default"
          to_cluster: "default"
          to_user: "default"
      
      # by default each cluster has `default` user which can be overridden by section `users`
      clusters:
      - name: "default"
        nodes: ["<публичный_IP-адрес_ВМ>:8123"]
      

      В поле nodes укажите публичный IP-адрес ВМ vm-test.

      В продакшн-среде рекомендуется использовать hack_me_please: false.

   5. Добавьте правило, разрешающее входящее соединение к порту 8123:

      sudo iptables -I INPUT -p tcp --dport 8123 -j ACCEPT
      sudo apt-get update && sudo apt-get install -y netfilter-persistent
      sudo netfilter-persistent save
      

   6. Перезапустите Chproxy и проверьте его статус:

      sudo systemctl restart chproxy
      sudo systemctl status chproxy
      

      Результат:

      ● chproxy.service - Chproxy
          Loaded: loaded (/etc/systemd/system/chproxy.service; enabled; preset: enabled)
          Active: active (running) since Thu 2026-03-05 23:10:11 UTC; 7s ago
            Docs: https://www.chproxy.org/
      ...
      Mar 05 23:10:11 vm-proxy chproxy[1046]: INFO: 2026/03/05 23:10:11 main.go:190: Serving http on ":8123"
      

7. Проверьте соединение:

   1. Подключитесь к ВМ vm-test по SSH.

   2. Выполните команду, указав публичный IP-адрес ВМ vm-proxy:

      curl "http://<публичный_IP-адрес_ВМ>:8123/?query=SELECT%201"
      

      Результат:

      1
      

      Успешное выполнение команды означает, что ваш ClickHouse^® на vm-test подключен к Chproxy на vm-proxy.

• Балансировка нагрузки между несколькими кластерами ClickHouse^®.
• Ограничение доступа пользователей к определенным кластерам по IP-адресам.
• Кеширование ответов для повышения производительности запросов.
• Мониторинг состояния узлов ClickHouse^® и автоматическое переключение трафика.
• Контроль частоты запросов и времени выполнения для каждого пользователя.
• Автоматическое получение и обновление SSL-сертификатов через Let’s Encrypt^®.
• Сокрытие реальных учетных данных ClickHouse^® от клиентских приложений.

Служба технической поддержки Yandex Cloud отвечает на запросы 24 часа в сутки, 7 дней в неделю. Доступные виды запросов и срок их обработки зависят от тарифного плана. Подключить платную поддержку можно в консоли управления. Подробнее о порядке оказания технической поддержки.