La instalación descrita aquí presenta un despliegue de ClickHouse en un clúster distribuido utilizanod Docker, con una arquitectura de un solo shard y tres réplicas. El entorno consta de tres nodos: bigdata1, bigdata2 y bigdata3. Se asume que ZooKeeper ya está configurado y disponible.

Se utiliza la imagen oficial de ClickHouse: clickhouse/clickhouse-server:22.9.7.34.

Antes de comenzar, es necesario crear los directorios de trabajo necesarios en cada nodo:

mkdir -p /data/clickhouse/data
mkdir -p /data/clickhouse/logs
mkdir -p /data/clickhouse/conf

Archivo de configuración principal

En cada nodo, el archivo config.xml debe colocarse en /data/clickhouse/conf. Este archivo define los puertos, rutas de archivos, límites de memoria y otros parámetros clave del servidor. A continuación se muestra un ejemplo de configuración ajustada para entornos de producción:

<?xml version="1.0"?>
<clickhouse>
    <logger>
        <level>trace</level>
        <log>/var/log/clickhouse-server/clickhouse-server.log</log>
        <errorlog>/var/log/clickhouse-server/clickhouse-server.err.log</errorlog>
        <size>1000M</size>
        <count>10</count>
    </logger>

    <!-- Puertos de servicio -->
    <http_port>8123</http_port>
    <tcp_port>10000</tcp_port>
    <mysql_port>9004</mysql_port>
    <postgresql_port>9005</postgresql_port>
    <interserver_http_port>9009</interserver_http_port>

    <!-- Escucha en todas las interfaces -->
    <listen_host>0.0.0.0</listen_host>

    <!-- Límites de conexión y memoria -->
    <max_connections>4096</max_connections>
    <max_concurrent_queries>100</max_concurrent_queries>
    <max_server_memory_usage_to_ram_ratio>0.9</max_server_memory_usage_to_ram_ratio>
    <max_server_memory_usage>0</max_server_memory_usage>

    <!-- Caches -->
    <uncompressed_cache_size>8589934592</uncompressed_cache_size>
    <mark_cache_size>5368709120</mark_cache_size>
    <mmap_cache_size>1000</mmap_cache_size>
    <compiled_expression_cache_size>134217728</compiled_expression_cache_size>
    <compiled_expression_cache_elements_size>10000</compiled_expression_cache_elements_size>

    <!-- Rutas de datos -->
    <path>/var/lib/clickhouse/</path>
    <tmp_path>/var/lib/clickhouse/tmp/</tmp_path>
    <user_files_path>/var/lib/clickhouse/user_files/</user_files_path>

    <!-- Incluir metadatos externos -->
    <include_from>/etc/clickhouse-server/config.d/metrika.xml</include_from>

    <!-- Configuración de usuarios y permisos -->
    <default_profile>default</default_profile>
    <default_database>default</default_database>

    <!-- Registro de consultas y métricas -->
    <query_log>
        <database>system</database>
        
        <partition_by>toYYYYMM(event_date)</partition_by>
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    </query_log>

    <!-- Logs adicionales -->
    <trace_log>
        <database>system</database>
        
        <partition_by>toYYYYMM(event_date)</partition_by>
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    </trace_log>

    <!-- Habilitar prometheus -->
    <prometheus>
        <endpoint>/metrics</endpoint>
        <port>9363</port>
        <metrics>true</metrics>
        <events>true</events>
        <asynchronous_metrics>true</asynchronous_metrics>
        <status_info>true</status_info>
    </prometheus>

    <!-- Distribución DDL mediante ZooKeeper -->
    <distributed_ddl>
        <path>/clickhouse/task_queue/ddl</path>
    </distributed_ddl>

    <!-- Macro variables para identificación del nodo -->
    <macros>
        <shard>single</shard>
        <replica>r1</replica>
    </macros>
</clickhouse>

Archivo de metadatos del clúster

El archivo metrika.xml debe ubicarse en /data/clickhouse/conf en cada nodo. Contiene la configuración del clúster, acceso a ZooKeeper y definición de macros para diferenciar cada réplica.

<?xml version="1.0"?>
<yandex>
    <remote_servers>
        <clickhouse_cluster>
            <shard>
                <internal_replication>true</internal_replication>
                <replica>
                    <host>bigdata1</host>
                    <port>10000</port>
                    <user>clickhouse</user>
                    <password>clickhouse</password>
                </replica>
                <replica>
                    <host>bigdata2</host>
                    <port>10000</port>
                    <user>clickhouse</user>
                    <password>clickhouse</password>
                </replica>
                <replica>
                    <host>bigdata3</host>
                    <port>10000</port>
                    <user>clickhouse</user>
                    <password>clickhouse</password>
                </replica>
            </shard>
        </clickhouse_cluster>
    </remote_servers>

    <zookeeper>
        <node index="1">
            <host>bigdata1</host>
            <port>2181</port>
        </node>
        <node index="2">
            <host>bigdata2</host>
            <port>2181</port>
        </node>
        <node index="3">
            <host>bigdata3</host>
            <port>2181</port>
        </node>
    </zookeeper>

    <macros>
        <shard>single</shard>
        <replica>r1</replica>
    </macros>
</yandex>

Nota: En nodos diferentes, el valor de <replica> debe cambiar (por ejemplo, r2, r3) para evitar conflictos.

Archivo de usuarios

El archivo users.xml define perfiles, contraseñas y accesos para los usuarios. Debe colocarse en el mismo directorio.

<clickhouse>
    <profiles>
        <default>
            <max_memory_usage>10000000000</max_memory_usage>
            <max_execution_time>300</max_execution_time>
            <max_bytes_before_external_group_by>5000000000</max_bytes_before_external_group_by>
        </default>
        <readonly>
            <readonly>1</readonly>
        </readonly>
    </profiles>

    <users>
        <default>
            <password></password>
            <networks>
                <ip>::/0</ip>
            </networks>
            <profile>default</profile>
            <quota>default</quota>
        </default>
    </users>

    <quotas>
        <default>
            <interval>
                <duration>3600</duration>
                <queries>0</queries>
                <errors>0</errors>
                <result_rows>0</result_rows>
                <read_rows>0</read_rows>
                <execution_time>0</execution_time>
            </interval>
        </default>
    </quotas>
</clickhouse>

Despliegue con Docker Comppose

Cada nodo ejecuta el siguiente archivo docker-compose.yml:

version: '3.8'
services:
  clickhouse:
    container_name: clickhouse
    image: clickhouse/clickhouse-server:22.9.7.34
    restart: always
    privileged: true
    environment:
      - TZ=Asia/Shanghai
      - CLICKHOUSE_USER=clickhouse
      - CLICKHOUSE_PASSWORD=clickhouse
      - CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1
    volumes:
      - /data/clickhouse/data:/var/lib/clickhouse
      - /data/clickhouse/logs:/var/log/clickhouse-server
      - /data/clickhouse/conf/config.xml:/etc/clickhouse-server/config.xml
      - /data/clickhouse/conf/users.xml:/etc/clickhouse-server/users.xml
      - /data/clickhouse/conf/metrika.xml:/etc/clickhouse-server/config.d/metrika.xml
      - /etc/hosts:/etc/hosts
    hostname: bigdata1
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
    network_mode: 'host'

Importante: Cambiar el valor de hostname según el nodo actual (bigdata1, bigdata2, bigdata3).

Consideraciones de rendimiento

• Para evitar que ClickHouse consuma toda la RAM durante operaciones JOIN grandes, se recomienda limitar el uso de memoria:

<max_server_memory_usage_to_ram_ratio>0.6</max_server_memory_usage_to_ram_ratio>

• Evitar valores muy bajos para <max_concurrent_queries>, ya que puede interrumpir consultas simultáneas.
• Ajustar max_memory_usage si se requiere control más estricto sobre recursos del sistema.