Описание проекта
This commit is contained in:
@@ -1,4 +1,21 @@
|
|||||||
Creative Commons Legal Code
|
MIT License
|
||||||
|
|
||||||
CC BY 4.0 licence
|
Copyright (c) 2024 clickhouse-learning-cluster
|
||||||
https://creativecommons.org/licenses/by/4.0/
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
@@ -1 +1,301 @@
|
|||||||
# clickhouse-learning-cluster
|
# Учебный кластер ClickHouse на Docker Compose
|
||||||
|
|
||||||
|
Готовый к использованию стенд для изучения кластерных возможностей ClickHouse. Проект создан для быстрого развертывания учебного кластера на любой машине с Docker.
|
||||||
|
|
||||||
|
## 🎯 Зачем это нужно
|
||||||
|
|
||||||
|
- **Быстрый старт**: поднять кластер ClickHouse на ноутбуке за 5 минут
|
||||||
|
- **Практическое изучение**: пощупать репликацию, шардинг, балансировку и отказоустойчивость
|
||||||
|
- **Безопасность**: всё в Docker Compose, сломалось — пересобрали без риска для продакшена
|
||||||
|
- **Наглядность**: прозрачная структура конфигураций для понимания принципов работы
|
||||||
|
|
||||||
|
## 🏗️ Архитектура стенда
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────┐
|
||||||
|
│ HAProxy │
|
||||||
|
│ :8124/:9001 │
|
||||||
|
└──────┬──────┘
|
||||||
|
│
|
||||||
|
┌────────────────┼────────────────┐
|
||||||
|
│ │ │
|
||||||
|
┌──────▼──┐ ┌──────▼──┐ ┌──────▼──┐ ┌──────▼──┐
|
||||||
|
│ click1 │ │ click2 │ │ click3 │ │ click4 │
|
||||||
|
│ :9123 │ │ :9124 │ │ :9125 │ │ :9126 │
|
||||||
|
│ :8002 │ │ :8003 │ │ :8004 │ │ :8005 │
|
||||||
|
└─────────┘ └─────────┘ └─────────┘ └─────────┘
|
||||||
|
│ │ │ │
|
||||||
|
└────────────────┼────────────────┘ │
|
||||||
|
│ │
|
||||||
|
┌──────▼──┐ │
|
||||||
|
│ZooKeeper│ ◄─────────────────────────────┘
|
||||||
|
│ :2182 │
|
||||||
|
└─────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### Состав инфраструктуры
|
||||||
|
|
||||||
|
- **4× ClickHouse Server** (версия 25.1) — основные узлы кластера
|
||||||
|
- **1× ZooKeeper** (3.9.3) — координатор для репликации
|
||||||
|
- **1× HAProxy** (3.1.7) — балансировщик нагрузки
|
||||||
|
- **3 типа кластерных конфигураций**: 1×4, 2×2, 4×1 (шарды×реплики)
|
||||||
|
|
||||||
|
## 🚀 Быстрый старт
|
||||||
|
|
||||||
|
### Предварительные требования
|
||||||
|
|
||||||
|
- Docker и Docker Compose
|
||||||
|
- Минимум 4GB RAM
|
||||||
|
- Свободные порты: 8124, 9001, 8002-8005, 9123-9126, 2182
|
||||||
|
|
||||||
|
### Запуск
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Клонируем репозиторий
|
||||||
|
git clone https://github.com/dementev-dev/clickhouse-learning-cluster
|
||||||
|
cd clickhouse-learning-cluster
|
||||||
|
|
||||||
|
# Запускаем кластер
|
||||||
|
docker compose up -d
|
||||||
|
|
||||||
|
# Проверяем статус
|
||||||
|
docker compose ps
|
||||||
|
```
|
||||||
|
|
||||||
|
### Проверка работоспособности
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Через HAProxy (рекомендуемый способ)
|
||||||
|
curl "http://default:123456@localhost:8124" -d "SELECT version()"
|
||||||
|
|
||||||
|
# Или через прямое подключение к узлу
|
||||||
|
curl "http://default:123456@localhost:9123" -d "SELECT version()"
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🔧 Конфигурация кластера
|
||||||
|
|
||||||
|
### Доступные кластерные топологии
|
||||||
|
|
||||||
|
| Кластер | Шарды | Реплики | Назначение |
|
||||||
|
|---------|-------|---------|------------|
|
||||||
|
| `c1sh4rep` | 1 | 4 | Максимальная отказоустойчивость |
|
||||||
|
| `c2sh2rep` | 2 | 2 | Сбалансированное решение |
|
||||||
|
| `c4sh1rep` | 4 | 1 | Максимальная производительность |
|
||||||
|
|
||||||
|
### Порты и доступ
|
||||||
|
|
||||||
|
| Сервис | HTTP | Native | Назначение |
|
||||||
|
|--------|------|--------|------------|
|
||||||
|
| HAProxy | 8124 | 9001 | Балансировка (основной доступ) |
|
||||||
|
| click1 | 9123 | 8002 | Прямой доступ для отладки |
|
||||||
|
| click2 | 9124 | 8003 | Прямой доступ для отладки |
|
||||||
|
| click3 | 9125 | 8004 | Прямой доступ для отладки |
|
||||||
|
| click4 | 9126 | 8005 | Прямой доступ для отладки |
|
||||||
|
| ZooKeeper | - | 2182 | Координация кластера |
|
||||||
|
|
||||||
|
### Аутентификация
|
||||||
|
|
||||||
|
- **Пользователь**: `default`
|
||||||
|
- **Пароль**: `123456`
|
||||||
|
|
||||||
|
## 📊 Примеры работы с кластером
|
||||||
|
|
||||||
|
### Проверка кластерной конфигурации
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- Список доступных кластеров
|
||||||
|
SHOW CLUSTERS;
|
||||||
|
|
||||||
|
-- Детальная информация о узлах
|
||||||
|
SELECT cluster, groupArray(concat(host_name,':',toString(port))) AS hosts
|
||||||
|
FROM system.clusters
|
||||||
|
GROUP BY cluster
|
||||||
|
ORDER BY cluster;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Создание реплицируемых таблиц
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- Создаем локальную реплицируемую таблицу на всех узлах
|
||||||
|
CREATE TABLE user_scores_local ON CLUSTER c2sh2rep (
|
||||||
|
user_id UInt32,
|
||||||
|
avg_score Float32,
|
||||||
|
created_at DateTime
|
||||||
|
)
|
||||||
|
ENGINE = ReplicatedMergeTree(
|
||||||
|
'/clickhouse/shard_{shard_c2sh2rep}/{database}/{table}',
|
||||||
|
'{replica_c2sh2rep}'
|
||||||
|
)
|
||||||
|
ORDER BY (user_id);
|
||||||
|
|
||||||
|
-- Создаем Distributed таблицу для прозрачного доступа
|
||||||
|
CREATE TABLE user_scores ON CLUSTER c2sh2rep
|
||||||
|
AS user_scores_local
|
||||||
|
ENGINE = Distributed(c2sh2rep, default, user_scores_local, user_id);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Тестирование с данными
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- Генерируем тестовые данные
|
||||||
|
INSERT INTO user_scores
|
||||||
|
SELECT
|
||||||
|
number % 100000 + 1 AS user_id,
|
||||||
|
toFloat32(rand() % 50 + rand() % 50) / 10 AS avg_score,
|
||||||
|
now() - (number * 86400 / 1000) AS created_at
|
||||||
|
FROM numbers(100000);
|
||||||
|
|
||||||
|
-- Проверяем распределение данных по шардам
|
||||||
|
SELECT
|
||||||
|
_shard_num AS shard_num,
|
||||||
|
hostName() AS host,
|
||||||
|
count() AS rows
|
||||||
|
FROM clusterAllReplicas('c2sh2rep', 'default', 'user_scores_local')
|
||||||
|
GROUP BY _shard_num, host
|
||||||
|
ORDER BY _shard_num, host;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Мониторинг репликации
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- Состояние репликационных очередей
|
||||||
|
SELECT
|
||||||
|
database,
|
||||||
|
table,
|
||||||
|
replica_name,
|
||||||
|
total_replicas,
|
||||||
|
active_replicas
|
||||||
|
FROM system.replicas;
|
||||||
|
|
||||||
|
-- Лог репликации
|
||||||
|
SELECT * FROM system.replication_queue LIMIT 10;
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🛠️ Структура проекта
|
||||||
|
|
||||||
|
```
|
||||||
|
clickhouse-learning-cluster/
|
||||||
|
├── docker-compose.yml # Основная конфигурация сервисов
|
||||||
|
├── configs/
|
||||||
|
│ ├── default_user.xml # Настройки пользователя default
|
||||||
|
│ ├── z_config.xml # Конфигурация кластеров и ZooKeeper
|
||||||
|
│ ├── macros_ch1.xml # Макросы для узла click1
|
||||||
|
│ ├── macros_ch2.xml # Макросы для узла click2
|
||||||
|
│ ├── macros_ch3.xml # Макросы для узла click3
|
||||||
|
│ ├── macros_ch4.xml # Макросы для узла click4
|
||||||
|
│ └── haproxy/
|
||||||
|
│ └── haproxy.cfg # Конфигурация балансировщика
|
||||||
|
├── sql/
|
||||||
|
│ └── sample_queries.sql # Примеры запросов для тестирования
|
||||||
|
└── data/ # Директория для пользовательских файлов
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🔍 Отладка и мониторинг
|
||||||
|
|
||||||
|
### Логи сервисов
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Логи всех сервисов
|
||||||
|
docker compose logs -f
|
||||||
|
|
||||||
|
# Логи конкретного узла
|
||||||
|
docker compose logs -f click1
|
||||||
|
|
||||||
|
# Логи балансировщика
|
||||||
|
docker compose logs -f haproxy
|
||||||
|
```
|
||||||
|
|
||||||
|
### Проверка состояния
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Статус контейнеров
|
||||||
|
docker compose ps
|
||||||
|
|
||||||
|
# Использование ресурсов
|
||||||
|
docker stats
|
||||||
|
```
|
||||||
|
|
||||||
|
### Подключение к узлам напрямую
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# ClickHouse client к первому узлу
|
||||||
|
docker exec -it clickhouse-learning-cluster-click1-1 clickhouse-client --user default --password 123456
|
||||||
|
|
||||||
|
# Или через внешний клиент
|
||||||
|
clickhouse-client --host localhost --port 8002 --user default --password 123456
|
||||||
|
```
|
||||||
|
|
||||||
|
## ⚠️ Важные особенности
|
||||||
|
|
||||||
|
### Уникальность путей в ZooKeeper
|
||||||
|
|
||||||
|
Каждая реплицируемая таблица должна иметь уникальный путь в ZooKeeper. Используйте макросы:
|
||||||
|
- `{shard_c2sh2rep}` — имя шарда
|
||||||
|
- `{replica_c2sh2rep}` — имя реплики
|
||||||
|
- `{database}`, `{table}` — имя базы и таблицы
|
||||||
|
|
||||||
|
### Лимиты ресурсов
|
||||||
|
|
||||||
|
Настроены оптимальные ulimits для ClickHouse:
|
||||||
|
- `nofile: 262144` — файловые дескрипторы
|
||||||
|
- `nproc: 65535` — процессы/потоки
|
||||||
|
|
||||||
|
### Сети
|
||||||
|
|
||||||
|
Все сервисы изолированы в сети `ch_learning_net` для безопасности.
|
||||||
|
|
||||||
|
## 🧪 Сценарии для экспериментов
|
||||||
|
|
||||||
|
### Тестирование отказоустойчивости
|
||||||
|
Подразумевается, что создана Distributed таблица user_scores из примеров.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Остановим одну реплику шарда 2
|
||||||
|
docker compose stop click3
|
||||||
|
|
||||||
|
# Прроверим чтение распределенной таблицы
|
||||||
|
curl "http://default:123456@localhost:8124" -d "SELECT count() FROM user_scores"
|
||||||
|
|
||||||
|
# Остановим вторую реплику шарда 2
|
||||||
|
docker compose stop click4
|
||||||
|
|
||||||
|
# Снова проверим чтение распределенной таблицы
|
||||||
|
curl "http://default:123456@localhost:8124" -d "SELECT count() FROM user_scores"
|
||||||
|
|
||||||
|
# Восстановим узлы узлы
|
||||||
|
docker compose start click3
|
||||||
|
docker compose start click4
|
||||||
|
```
|
||||||
|
|
||||||
|
### Проверка балансировки
|
||||||
|
|
||||||
|
```bash
|
||||||
|
for i in {1..8}; do
|
||||||
|
echo "Запрос $i:"
|
||||||
|
curl -s "http://default:123456@localhost:8124" -d "SELECT hostName() AS current_node, now() AS request_time"
|
||||||
|
echo ""
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
## 📚 Полезные ссылки
|
||||||
|
|
||||||
|
- [Официальная документация ClickHouse](https://clickhouse.com/docs/)
|
||||||
|
- [Репликация в ClickHouse](https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/replication)
|
||||||
|
- [Масштабирование и кластеры](https://clickhouse.com/docs/en/architecture/cluster-deployment)
|
||||||
|
- [ClickHouse Keeper](https://clickhouse.com/docs/en/guides/sre/keeper/clickhouse-keeper)
|
||||||
|
|
||||||
|
## 📝 Лицензия
|
||||||
|
|
||||||
|
MIT License — используйте свободно в учебных и коммерческих целях.
|
||||||
|
|
||||||
|
## 🤝 Вклад в проект
|
||||||
|
|
||||||
|
Приветствуются pull requests с улучшениями:
|
||||||
|
- Дополнительные примеры запросов
|
||||||
|
- Новые конфигурации кластеров
|
||||||
|
- Улучшения документации
|
||||||
|
- Скрипты автоматизации
|
||||||
|
|
||||||
|
## 📞 Поддержка
|
||||||
|
|
||||||
|
При возникновении вопросов создавайте issue в репозитории или обращайтесь к официальной документации ClickHouse.
|
||||||
Reference in New Issue
Block a user