Saltar al contenido principal
En este ejemplo, aprenderás a configurar un clúster sencillo de ClickHouse que puede escalar. Hay cinco servidores configurados. Dos se utilizan para segmentar los datos. Los otros tres servidores se utilizan para la coordinación.
La arquitectura del clúster que configurarás se muestra a continuación:
Aunque es posible ejecutar ClickHouse Server y ClickHouse Keeper juntos en el mismo servidor, recomendamos encarecidamente usar hosts dedicados para ClickHouse Keeper en entornos de producción, que es el enfoque que mostraremos en este ejemplo.Los servidores Keeper pueden ser más pequeños, y 4 GB de RAM suele ser suficiente para cada servidor Keeper hasta que los servidores ClickHouse alcancen un tamaño considerable.

​
Requisitos previos

1

​
Configurar la estructura de directorios y el entorno de prueba

Archivos de ejemploLos siguientes pasos le guiarán en la configuración del clúster desde cero. Si prefiere omitir estos pasos e ir directamente a ejecutar el clúster, puede obtener los archivos de ejemplo del repositorio examples, en el directorio ‘docker-compose-recipes’.
En este tutorial, utilizará Docker compose para configurar el clúster de ClickHouse. Esta configuración puede adaptarse para funcionar también con máquinas locales independientes, máquinas virtuales o instancias en la nube.Ejecute los siguientes comandos para configurar la estructura de directorios de este ejemplo:
Añade el siguiente archivo docker-compose.yml al directorio cluster_2S_1R:
docker-compose.yml
Cree los siguientes subdirectorios y archivos:
  • El directorio config.d contiene el archivo de configuración del servidor ClickHouse config.xml, en el que se define la configuración personalizada de cada nodo de ClickHouse. Esta configuración se combina con el archivo de configuración predeterminado config.xml de ClickHouse, incluido en cada instalación de ClickHouse.
  • El directorio users.d contiene el archivo de configuración de usuarios users.xml, en el que se define la configuración personalizada para los usuarios. Esta configuración se combina con el archivo de configuración predeterminado users.xml de ClickHouse, incluido en cada instalación de ClickHouse.
Directorios de configuración personalizadosSe recomienda usar los directorios config.d y users.d al crear su propia configuración, en lugar de modificar directamente la configuración predeterminada en /etc/clickhouse-server/config.xml y etc/clickhouse-server/users.xml.La línea
garantiza que las secciones de configuración definidas en los directorios config.d y users.d sobrescriban las secciones de configuración predeterminadas definidas en los archivos predeterminados config.xml y users.xml.
2

​
Configurar nodos de ClickHouse

​
Configuración del servidor

Ahora modifique cada archivo de configuración vacío config.xml ubicado en fs/volumes/clickhouse-{}/etc/clickhouse-server/config.d. Las líneas resaltadas a continuación deben cambiarse para que sean específicas de cada nodo:
Cada sección del archivo de configuración anterior se explica con más detalle a continuación.

​
Redes y registro

La comunicación externa a través de la interfaz de red se habilita al activar la configuración de listen host. Esto garantiza que el host del servidor ClickHouse sea accesible desde otros hosts:
El puerto de la API HTTP está configurado como 8123:
El puerto TCP para la comunicación mediante el protocolo nativo de ClickHouse entre clickhouse-client y otras herramientas nativas de ClickHouse, y clickhouse-server y otros clickhouse-servers está configurado en 9000:
El registro se define en el bloque <logger>. Esta configuración de ejemplo genera un log de depuración que rotará cada 1000M un máximo de tres veces:
Para obtener más información sobre la configuración de logging, consulte los comentarios incluidos en el archivo de configuración predeterminado de ClickHouse.

​
Configuración del clúster

La configuración del clúster se establece en el bloque <remote_servers>. Aquí se define el nombre del clúster cluster_2S_1R.El bloque <cluster_2S_1R></cluster_2S_1R> define el layout del clúster mediante las configuraciones <shard></shard> y <replica></replica>, y actúa como plantilla para las consultas de DDL distribuido, es decir, consultas que se ejecutan en todo el clúster mediante la cláusula ON CLUSTER. De forma predeterminada, las consultas de DDL distribuido están permitidas, pero también pueden desactivarse con la configuración allow_distributed_ddl_queries.internal_replication se deja en false de forma predeterminada, ya que solo hay una réplica por segmento.
Para cada servidor, se especifican los siguientes parámetros:

​
Configuración de Keeper

La sección <ZooKeeper> indica a ClickHouse dónde se está ejecutando ClickHouse Keeper (o ZooKeeper). Como estamos utilizando un cluster de ClickHouse Keeper, es necesario especificar cada <node> del cluster, junto con su hostname y número de puerto mediante las etiquetas <host> y <port> respectivamente.La configuración de ClickHouse Keeper se explica en el siguiente paso del tutorial.
Aunque es posible ejecutar ClickHouse Keeper en el mismo servidor que ClickHouse Server, en entornos de producción recomendamos encarecidamente que ClickHouse Keeper se ejecute en servidores dedicados.

​
Configuración de macros

Además, la sección <macros> se utiliza para definir sustituciones de parámetros para tablas replicadas. Estas se listan en system.macros y permiten usar sustituciones como {shard} y {replica} en las consultas.
Estos se definirán específicamente según la configuración del clúster.

​
Configuración de usuario

Ahora modifique cada archivo de configuración vacío users.xml ubicado en fs/volumes/clickhouse-{}/etc/clickhouse-server/users.d con el siguiente contenido:
/users.d/users.xml
En este ejemplo, el usuario predeterminado se configura sin contraseña por motivos de simplicidad. En la práctica, esto no es recomendable.
En este ejemplo, cada archivo users.xml es idéntico para todos los nodos del clúster.
3

​
Configurar ClickHouse Keeper

​
Configuración de ClickHouse Keeper

Para que la replicación funcione, es necesario configurar un clúster de ClickHouse Keeper. ClickHouse Keeper proporciona el sistema de coordinación para la replicación de datos y actúa como reemplazo directo de ZooKeeper, que también podría utilizarse. No obstante, se recomienda ClickHouse Keeper, ya que ofrece mejores garantías y fiabilidad, además de utilizar menos recursos que ZooKeeper. Para lograr alta disponibilidad y mantener el quorum, se recomienda ejecutar al menos tres nodos de ClickHouse Keeper.
ClickHouse Keeper puede ejecutarse en cualquier nodo del clúster junto con ClickHouse, aunque se recomienda hacerlo en un nodo dedicado, lo que permite escalar y administrar el clúster de ClickHouse Keeper de forma independiente del clúster de base de datos.
Cree los archivos keeper_config.xml para cada nodo de ClickHouse Keeper con el siguiente comando desde la raíz de la carpeta de ejemplo:
Modifique los archivos de configuración vacíos que se crearon en el directorio de cada nodo fs/volumes/clickhouse-keeper-{}/etc/clickhouse-keeper. Las líneas resaltadas a continuación deben modificarse para que sean específicas de cada nodo:
/clickhouse-keeper/keeper_config.xml
Cada archivo de configuración contendrá la siguiente configuración única (que se muestra a continuación). El server_id utilizado debe ser único para ese nodo específico de ClickHouse Keeper en el clúster y coincidir con el <id> del servidor definido en la sección <raft_configuration>. tcp_port es el puerto que utilizan los clientes de ClickHouse Keeper.
La siguiente sección se utiliza para configurar los servidores que participan en el quórum del algoritmo de consenso Raft:
ClickHouse Cloud simplifica la gestiónClickHouse Cloud elimina la carga operativa asociada a la gestión de segmentos y réplicas. La plataforma se encarga automáticamente de la alta disponibilidad, la replicación y el escalado. La capacidad de cómputo y el almacenamiento son independientes y escalan según la demanda, sin requerir configuración manual ni mantenimiento continuo.Leer más
4

​
Prueba la configuración

Asegúrate de que Docker se esté ejecutando en tu máquina. Inicia el clúster con el comando docker-compose up desde la raíz del directorio cluster_2S_1R:
Deberías ver que Docker empieza a descargar las imágenes de ClickHouse y Keeper, y luego inicia los contenedores:
Para verificar que el clúster esté en ejecución, conéctese a clickhouse-01 o clickhouse-02 y ejecute la siguiente consulta. A continuación, se muestra el comando para conectarse al primer nodo:
Si todo ha ido bien, verás el prompt del cliente de ClickHouse:
Ejecute la siguiente consulta para comprobar qué topologías de clúster están definidas en qué hosts:
Query
Response
Ejecute la siguiente consulta para comprobar el estado del cluster de ClickHouse Keeper:
Query
Response
El comando mntr también se usa habitualmente para verificar que ClickHouse Keeper está en ejecución y para obtener información sobre el estado de la relación entre los tres nodos de Keeper. En la configuración utilizada en este ejemplo, hay tres nodos que trabajan juntos. Los nodos elegirán un líder y los nodos restantes serán followers.El comando mntr proporciona información relacionada con el rendimiento y con si un nodo determinado es follower o leader.
Es posible que necesite instalar netcat para enviar el comando mntr a Keeper. Consulte la página de nmap.org para obtener información sobre la descarga.
Ejecute el siguiente comando desde un shell en clickhouse-keeper-01, clickhouse-keeper-02 y clickhouse-keeper-03 para comprobar el estado de cada nodo de Keeper. El comando para clickhouse-keeper-01 se muestra a continuación:
A continuación se muestra un ejemplo de respuesta de un nodo seguidor:
Response
A continuación se muestra un ejemplo de respuesta de un nodo líder:
Response
Con esto, has configurado correctamente un clúster de ClickHouse con dos segmentos y una réplica por segmento. En el siguiente paso, crearás una tabla en el clúster.
5

​
Crear una base de datos

Ahora que ha verificado que el clúster está correctamente configurado y en ejecución, volverá a crear la misma tabla que se utiliza en el tutorial del conjunto de datos de ejemplo UK property prices. Consta de alrededor de 30 millones de filas con precios pagados por propiedades inmobiliarias en Inglaterra y Gales desde 1995.Conéctese al cliente de cada host ejecutando cada uno de los siguientes comandos en pestañas o ventanas de terminal independientes:
Puede ejecutar la consulta siguiente desde clickhouse-client en cada host para confirmar que aún no se ha creado ninguna base de datos, aparte de las predeterminadas:
Query
Response
Desde el cliente clickhouse-01, ejecute la siguiente consulta DDL distribuida con la cláusula ON CLUSTER para crear una nueva base de datos llamada uk:
Puedes volver a ejecutar la misma consulta que antes desde el cliente de cada host para confirmar que la base de datos se ha creado en todo el clúster, a pesar de haber ejecutado la consulta solo en clickhouse-01:
6

​
Crear una tabla en el clúster

Ahora que ya se ha creado la base de datos, cree una tabla. Ejecute la siguiente consulta desde cualquiera de los clientes del host:
Tenga en cuenta que es idéntica a la consulta utilizada en la sentencia CREATE original del tutorial del conjunto de datos de ejemplo UK property prices, excepto por la cláusula ON CLUSTER.La cláusula ON CLUSTER está diseñada para la ejecución distribuida de consultas DDL (Data Definition Language) como CREATE, DROP, ALTER y RENAME, lo que garantiza que estos cambios de esquema se apliquen en todos los nodos de un clúster.Puede ejecutar la siguiente consulta desde el cliente de cada host para confirmar que la tabla se ha creado en todo el clúster:
Query
Response
Antes de insertar los datos de precios pagados del Reino Unido, hagamos un experimento rápido para ver qué ocurre cuando insertamos datos en una tabla normal desde cualquiera de los hosts.Cree una base de datos y una tabla de prueba con la siguiente consulta desde cualquiera de los hosts:
Ahora, ejecute desde clickhouse-01 la siguiente consulta INSERT:
Pasa a clickhouse-02 y ejecuta la siguiente consulta INSERT:
Query
Ahora, desde clickhouse-01 o clickhouse-02, ejecute la siguiente consulta:
Notarás que, a diferencia de una tabla ReplicatedMergeTree, solo se devuelve la fila que se insertó en la tabla de ese host concreto, y no ambas filas.Para leer los datos de los dos segmentos, necesitamos una interfaz que pueda gestionar consultas en todos los segmentos, combinando los datos de ambos segmentos cuando ejecutamos consultas SELECT sobre ella o insertando datos en ambos segmentos cuando ejecutamos consultas INSERT.En ClickHouse, esta interfaz se denomina tabla distribuida, y la creamos con el motor de tabla Distributed. Veamos cómo funciona.
7

​
Crear una tabla distribuida

Cree una tabla distribuida con la consulta siguiente:
En este ejemplo, se usa la función rand() como clave de sharding para que las inserciones se distribuyan aleatoriamente entre los segmentos.Ahora consulta la tabla distribuida desde cualquiera de los hosts y obtendrás ambas filas insertadas en los dos hosts, a diferencia del ejemplo anterior:
Hagamos lo mismo con nuestros datos de precios de propiedades del Reino Unido. Desde cualquiera de los hosts cliente, ejecute la siguiente consulta para crear una tabla distribuida usando la tabla existente que creamos previamente con ON CLUSTER:
8

​
Insertar datos en una tabla distribuida

Ahora conéctese a cualquiera de los hosts e inserte los datos:
Una vez insertados los datos, puede verificar el número de filas usando la tabla distribuida:
Query
Response
Si ejecuta la siguiente consulta en cualquiera de los hosts, verá que los datos se han distribuido de forma más o menos uniforme entre los segmentos (tenga en cuenta que el segmento de destino se determinó con rand(), por lo que los resultados pueden variar):
¿Qué ocurrirá si uno de los hosts falla? Simulemos esto apagando clickhouse-01:
Verifique que el host está caído ejecutando:
Response
Ahora desde clickhouse-02, ejecuta la misma consulta SELECT que ejecutamos antes en la tabla distribuida:
Response
Lamentablemente, nuestro clúster no es tolerante a fallos. Si uno de los hosts falla, el clúster se considera no saludable y la consulta falla, a diferencia de la tabla replicada que vimos en el ejemplo anterior, con la que pudimos insertar datos incluso cuando uno de los hosts falló.

​
Conclusión

La ventaja de esta topología de clúster es que los datos se distribuyen entre hosts independientes y utilizan la mitad del almacenamiento por nodo. Más importante aún, las consultas se procesan en ambos segmentos, lo que mejora la eficiencia en el uso de la memoria y reduce la E/S por host. La principal desventaja de esta topología de clúster es, por supuesto, que la pérdida de uno de los hosts nos impide atender consultas. En el siguiente ejemplo, veremos cómo configurar un clúster con dos segmentos y dos réplicas que ofrece tanto escalabilidad como tolerancia a fallos.
Última modificación el 12 de junio de 2026