@@ -1,29 +1,21 @@
# Учебная дата-платформа кликстрима
Этот стенд — для менти, который видит такую систему впервые и хочет
проследить весь путь данных: от кликстрима и заказов до витрин, проверок и
графиков. Преемник учебного стенда
> Этим стендом можно пользоваться самостоятельно. Он также входит в
> [план обучения Data Engineering Roadmap](https://de.dementev.space) как
> курсовая работа. Если вам нужна помощь, обратитесь к автору материалов —
> ментору [@dementev_dev](https://t.me/dementev_dev).
Этот стенд — для изучения и экспериментов с кликстримом и ClickHouse. Здесь
можно проследить весь путь данных: от кликстрима и заказов до витрин, проверок
и графиков. Это преемник учебного стенда
[clickstream-ch-kafka-superset-demo ](https://git.dementev.space/ddmitry/clickstream-ch-kafka-superset-demo ).
Поднять стенд поможет [ «Быстрый старт» ]( #быстрый-старт ), выключить —
`make down` . Чтобы разобраться в устройстве, начните с
[путеводителя ](docs/handbook/README.md ), а с
[уроков ](docs/labs/README.md ).
## Статус
Репозиторий строится по спеке
[«Боевой реализм стенда (v2)» ](docs/specs/2026-07-30-stand-v2-realism.md ).
Сейчас работают кластер ClickHouse из двух шардов, отдельный
clickhouse-keeper, односерверная Kafka в режиме KRaft, Airflow 3.3, Superset,
Prometheus, Grafana, экспортёр метрик Kafka и общая база Postgres для
метаданных. Генератор кликстрима в [`generator/` ](generator/ ) собран
целиком со стороны клиента: у него есть контракт схемы события, из которого
собрано [описание выгрузки ](docs/formats/clickstream-event.md ), модельный мир и
проигрыватель, отправляющий дни в Kafka или в файл. События доезжают до
типизированного `ods.event` , а `dds.event_v` отдаёт их на языке бизнес-модели
без копии данных. `make up` наполняет стенд стартовым миром — первой неделей
модельного времени.
В е дняты кластер ClickHouse из двух шардов, отдельный keeper, Kafka,
Airflow, Superset, Prometheus и Grafana; события кликстрима и заказы бэкенда
приезжают из генератора и идут по слоям STG → ODS → DDS → DM. `make up`
наполняет стенд стартовым миром — первой неделей модельного времени. Чтобы
разобраться в устройстве, начните с [путеводителя ](docs/handbook/README.md ), а
учиться — с уроков ](docs/labs/README.md ).
## Быстрый старт
@@ -35,27 +27,21 @@ Prometheus, Grafana, экспортёр метрик Kafka и общая баз
пользователя Windows; после правки нужен `wsl --shutdown` . Если своей машины не
хватает, стенд одинаково хорошо живёт на недорогом VPS.
Проверкам на поднятом стенде также нужны `curl` , `jq` , `awk` , `grep` , `sed` ,
`tail` , `sleep` и `timeout` . `jq` нужен и самому `make up` : им читается паспорт
мира, по которому он ждёт заливки. По умолчанию должны быть свободны порты
`23000` , `28080` , `28088` , `28123` , `28124` , `29000` , `29001` , `29090` и
`29092` . Проверкам без стенда — `make config-test` и `make lint` в корне, всем
целям генератора в `generator/` — нужен `uv` .
`make up` `curl` и `jq` : первым он ходит в Airflow, вторым читает
паспорт мира, по которому ждет заливки. По умолчанию должны быть свободны
порты `23000` , `28080` , `28088` , `28123` , `28124` , `29000` , `29001` , `29090`
и `29092` . Всем целям генератора в `generator/` нужен `uv` .
Сначала скопируйте настройки стенда:
``` bash
cp .env.example .env
make up
make smoke
make check-clickhouse
make check-services
```
Первому знакомству нужны все три проверки на стенде: `make smoke` говорит, что
стенд собран, `make check-clickhouse` — что кластер работает кластером, а
`make check-services` — что Airflow запускает DAG, а Superset ходит в базу .
Дальше, в рабочей петле, обычно хватает `make smoke` .
`make up` сам ждет заливки стартового мира; что он делает по шагам и какие
проверки есть у стенда, описано в [карте
проверок ]( docs/architecture/testing.md ) .
`.env.example` — образец обязательной локальной настройки. В нём живут имя
экземпляра, внешние порты, учебные учётные данные и ключи. Одно значение образца
@@ -72,38 +58,7 @@ make check-services
все локальные данные стенда, а следующий `make up` создаст их с новыми
значениями.
Что делает `make up` , кого спрашивает каждая проверка и как устроен смоук,
описано в [карте проверок ](docs/architecture/testing.md ).
Обычный рабочий цикл — `make config-test` и `make smoke` ; остальные цели гоняют
тогда, когда правка их касается. Что утверждает каждая проверка, нужен ли ей
поднятый стенд, сколько стоит прогон и куда класть новую — в
[карте проверок ](docs/architecture/testing.md ).
Остановить контейнеры без удаления данных можно командой `make down` . Если нужно
вернуть прикладной мир к началу, `make rebuild-storage` запустит в Airflow его
явную пересборку: удалит прикладные базы ClickHouse, топики и позиции
потребителей Kafka, затем создаст схему и данные заново. Службы и их тома
останутся на месте. `make clean` удаляет весь стенд вместе с именованными томами
и для обычной разработки не нужен. Перед пересборкой поставьте `world_live` на
паузу и дайте уже начатому шаговому дагу закончить день.
## Стартовый мир
Стартовый мир и его паспорт описаны в [справочнике
мира ](docs/architecture/world.md ).
## Как позвать генератор
Режимы и команды запуска генератора описаны в
[справочнике мира ](docs/architecture/world.md#как-запустить-генератор ).
### Даги модельного времени
Даги времени, позиция мира и форма запуска описаны в [справочнике
мира ](docs/architecture/world.md#даги-модельного-времени ).
## Состав и доступ
## Адреса и пароли
С `.env.example` порты доступны только с локальной машины:
@@ -118,21 +73,37 @@ make check-services
Службы, пользователи и роли, применение настроек и результаты сверки
конфигурации описаны в [справочнике стенда ](docs/architecture/stand.md ).
## Что здесь будет
## Сдвинуть мир вперед
- одно широкое собыкликстрима по образцу выгрузки Яндекс Метрики вместо
четырёх топиков;
- второй источник — заказы бэкенда, ежедневным слепком в ту же Kafka;
- сверка клиентской покупки с заказом бэкенда: деньги считаем по бэкенду,
поведение и атрибуцию — по трекеру;
- анонимный кликстрим и склейка кука↔пользователь через покупки;
- ClickHouse кластером как единственным режимом.
В т е даг `world_next_day` : по умолчанию он сыграет один день, а
в форме запуска можно задать другое число дней. Снимите с паузы `world_live` ,
и мир поедет сам в темпе модельного времени. Подробности — в [справочнике
мира ](docs/architecture/world.md#даги-модельного-времени ).
## Чем отличается от предшественника
## Вернуть мир к началу
Предшественник остаётся стабильным учебным стендом и заморожен для новых фич:
там событие разрезано на четыре топика, есть только просмотры страниц,
посетители опознаны по email, ClickHouse — одна нода. Развитие идёт здесь.
`make rebuild-storage` запустит в Airflow явную пересборку: удалит прикладные
базы ClickHouse, топики и позиции потребителей Kafka, затем создаст схему
и данные заново. Службы и их тома останутся на месте. Перед пересборкой
поставьте `world_live` на паузу и дайте уже начатому шаговому дагу закончить
день.
## Выключить или сбросить целиком
`make down` остановит контейнеры без удаления данных. `make clean` удалит весь
стенд вместе с именованными томами и для обычной работы не нужен.
## Подключиться из DBeaver
Драйвер ClickHouse в DBeaver подключается по JDBC через HTTP-порт. Укажите хост
`127.0.0.1` , порт `28123` , пользователя `analyst` и пароль из переменной
`CLICKHOUSE_ANALYST_PASSWORD` в `.env` ; в образце это `analyst-26-reader` .
Ко второй ноде — порт `28124` .
Пользователь `analyst` читает все слои и справочники. Нативные порты `29000` и
`29001` нужны `clickhouse-client` , но не DBeaver. Остальные пользователи и роли
описаны в [справочнике
стенда ](docs/architecture/stand.md#пользователи-и-роли-clickhouse ).
## Документация
@@ -143,10 +114,20 @@ make check-services
- [docs/adr/ ](docs/adr/ ) — принятые решения с доводами и отвергнутыми
вариантами: почему сделано так, а не иначе.
- [docs/architecture/ ](docs/architecture/ ) — рабочие справочники по зонам
ответственности: [ хранилище ]( docs/architecture/storage.md ) — конвенции имён,
раскладка по шардам, приём событий, карта таблиц;
[проверки ](docs/architecture/testing.md ) — что утверждает каждая цель `make`
и куда класть новую проверку.
ответственности:
- [хранилище ](docs/architecture/storage.md ) — конвенции имён, раскладка по
шардам, приём событий, карта таблиц.
- [конвейер ](docs/architecture/etl.md ) — движение данных между слоями и
работа дагов.
- [мир и модельное время ](docs/architecture/world.md ) — начальные данные,
ход дней и управление генератором.
- [стенд ](docs/architecture/stand.md ) — службы, доступ и настройка.
- [проверки ](docs/architecture/testing.md ) — что утверждает каждая цель
`make` и куда класть новую проверку.
- [мониторинг ](docs/architecture/monitoring/README.md ) — сбор метрик и
устройство дашборда.
- [Superset ](docs/architecture/superset.md ) — подключения, наборы данных и
граница автоматической настройки.
- [docs/research/ ](docs/research/ ) — исследования; сейчас это формат
кликстрима Яндекса, по которому строится модель события.
- [docs/formats/ ](docs/formats/ ) — описания форматов источников: по ним