Учебная дата-платформа кликстрима

Стенд для работы с кликстримом. Преемник учебного стенда clickstream-ch-kafka-superset-demo.

Статус

Репозиторий строится по спеке «Боевой реализм стенда (v2)». Сейчас работают кластер ClickHouse из двух шардов, отдельный clickhouse-keeper, односерверная Kafka в режиме KRaft, Airflow 3.3, Superset, Prometheus, Grafana и общая база Postgres для метаданных. Генератор кликстрима в generator/ собран целиком со стороны клиента: у него есть контракт схемы события, из которого собрано описание выгрузки, модельный мир и проигрыватель, отправляющий дни в Kafka или в файл.

Быстрый старт

Нужны Docker с Compose и около 8 ГБ памяти, доступной Docker. Это не объём ноутбука, а то, что отдано самому Docker: в Docker Desktop и WSL2 он живёт внутри виртуальной машины и получает лишь часть памяти хозяина. Сколько выдано сейчас, в байтах, покажет docker info --format '{{.MemTotal}}'. В WSL2 это поднимается параметром memory в файле .wslconfig домашнего каталога пользователя Windows; после правки нужен wsl --shutdown. Если своей машины не хватает, стенд одинаково хорошо живёт на недорогом VPS.

Проверкам на поднятом стенде также нужны curl, jq, awk, grep, sed, tail, sleep и timeout. По умолчанию должны быть свободны порты 23000, 28080, 28088, 28123, 28124, 29000, 29001, 29090 и 29092. Проверкам без стенда — make config-test, make lint, make typecheck, make test — и сборке документации make docs нужен uv.

Стенд запускается без .env:

make up
make smoke
make check-clickhouse
make check-services

Первому знакомству нужны все три проверки на стенде: make smoke говорит, что стенд собран, make check-clickhouse — что кластер работает кластером, а make check-services — что Airflow запускает DAG, а Superset ходит в базу. Дальше, в рабочей петле, обычно хватает make smoke.

Чтобы изменить образы, порты или учебные учётные данные, скопируйте образец:

cp .env.example .env
make up
make smoke

.env.example — справочник, а не настройка: в нём перечислены все переменные, которые читает compose.yaml, с теми же значениями по умолчанию. Стенд его не читает и на согласованность не проверяет, поэтому расхождение с compose.yaml обнаружит только читатель. Меняя подстановку ${VAR:-значение} в compose.yaml, поправьте образец тем же коммитом.

Учётные данные Postgres и Grafana применяются при создании их томов. После первого запуска меняйте их только вместе с make clean: команда удалит все локальные данные стенда, а следующий make up создаст их с новыми значениями.

make up собирает локальные образы Airflow и Superset, поднимает весь стенд и ждёт здорового состояния долгоживущих контейнеров. В образ Airflow добавлены закреплённые клиенты ClickHouse и Kafka. Одноразовые airflow-init и superset-init завершаются с кодом 0. Первый обновляет схему Airflow, подготавливает администратора и подключение к clickhouse-01. Второй обновляет Superset, создаёт администратора и импортирует подключение к clickhouse-02.

make smoke за секунды спрашивает, собран ли стенд: зависимости машины, здоровье контейнеров, устройство keeper, ответ Kafka с машины через отображённый порт, три цели Prometheus, источник Grafana, компоненты Airflow и подготовленное подключение к clickhouse-01. В конце проверка спрашивает у Docker, не убивало ли ядро что-нибудь в долгоживущих контейнерах за нехватку памяти и не включалась ли политика перезапуска: убитый контейнер Docker поднимает сам, и проверка состояния об этом промолчит.

Одиннадцать проверок здоровья сразу после make up --wait повторяют то, чего Compose уже дождался: у каждой долгоживущей службы есть своя healthcheck. Оставлены они потому, что первый вопрос к стенду всё равно «всё ли живо», а ответ на него стоит меньше секунды. Устройство keeper — другое дело: он должен работать от пользователя clickhouse, с пределом в 262144 открытых файла и со своим томом под данные. Всё это объявлено в compose.yaml, но здоровым keeper выглядит и без этого, поэтому смоук спрашивает у живого контейнера, дошли ли объявленные настройки до процесса.

Kafka по той же причине спрашивают снаружи. Её healthcheck обращается к брокеру изнутри контейнера и по внутреннему слушателю, поэтому здоровой Kafka остаётся и тогда, когда объявленный наружу адрес ведёт не туда. Клиент с машины в этом случае подключается, получает метаданные и молча виснет на адресе, которого с его стороны не существует. Смоук идёт тем же путём, что и будущий генератор: стучится в отображённый порт и просит список топиков.

make check-services проверяет то, ради чего приходится ждать службу: работу с топиком Kafka с машины — создан, найден, удалён, — ручной запуск пробников test_clickhouse и test_kafka, вход в Superset, его метаданные и подключение к clickhouse-02. Первый пробник создаёт таблицы на обеих нодах и читает через Distributed на ноде 2 строку из локальной таблицы ноды 1. Второй пишет в Kafka и читает свой маркер. Временный топик проверки с машины и запуски DAG удаляются; постоянный топик пробника сохраняется, а старые записи чистит Kafka.

make check-clickhouse запускает отдельную глубокую проверку ClickHouse: описание кластера, макросы, связь с keeper, ReplicatedMergeTree, Distributed, очередь распределённых DDL и очистку временных таблиц.

make config-test проверяет Compose, синтаксис файлов DAG и пробельные ошибки в diff без запуска стенда.

Обычный рабочий цикл — make config-test и make smoke; остальные цели гоняют тогда, когда правка их касается. Что утверждает каждая проверка, нужен ли ей поднятый стенд, сколько стоит прогон и куда класть новую — в карте проверок.

Остановить контейнеры без удаления данных можно командой make down. Для полного сброса с удалением всех именованных томов используйте make clean. Повторный make up безопасен: одноразовая подготовка приложений идемпотентна.

Как позвать генератор

События производит генератор из generator/. Модельный день — функция зерна и номера дня, поэтому один и тот же день всегда даёт те же события: обрыв лечится повтором. Позицию на оси генератор не помнит — какой день играть, решает зовущий.

Режима два, и различаются они темпом. Пакетный гонит день подряд, без пауз: так заливается мир и так переигрывается день после обрыва. Живой держит темп модельного времени — по умолчанию ×60: модельные сутки за 24 реальные минуты, суточная волна разворачивается на глазах, отставание видно в логе.

На стенде генератор ходит своим образом — разовой службой, которую поднимают и убирают на один прогон. На каждый режим по цели:

# день D0 целиком в топик hits
make generate-batch
# первая сотня событий дня D3
make generate-batch GENERATOR_DAY=3 GENERATOR_LIMIT=100
# день D3 живьём, ускорение ×1000
make generate-live GENERATOR_DAY=3 GENERATOR_SPEED=1000

Переменная	Что задаёт	Умолчание
GENERATOR_DAY	номер дня на оси мира (D0 — первый)	0, задано в Makefile
GENERATOR_LIMIT	потолок событий на прогон; только generate-batch	нет: день целиком
GENERATOR_SPEED	ускорение модельного времени; только generate-live	×60, задано в генераторе

Куда отправлять, обе цели берут из .env: KAFKA_BOOTSTRAP_SERVERS (внутри сети Compose это kafka:9092) и KAFKA_TOPIC (hits).

Образ цели не пересобирают: нет образа — Compose соберёт его сам, есть — возьмёт как есть. Пересобрать намеренно, после правки generator/Dockerfile или зависимостей, — отдельной командой:

docker compose --profile generator build generator

Разведено это нарочно: собрать образ и запустить контейнер — разные действия, и цель запуска, молча пересобирающая образ, стирает между ними границу. Что образ устарел, видно по собственному прогону — это обратная связь, а не ловушка.

Посмотреть на события, не поднимая стенд, помогает файловый приёмник: одно событие — одна строка. Флаг --limit берёт начало дня вместо целого дня — тому, кто смотрит на конвейер, ждать полсотни тысяч событий незачем.

uv run --project generator python -m clickstream_generator batch \
  --day 0 --limit 100 --file tmp/day0.jsonl

Несколько дней подряд играет один запуск: --days 8. Всё, что принимается флагами, принимается и переменными окружения — так генератор позовёт даг этапа 5; полный список у --help.

Умолчания есть не у всего, и это нарочно. Зерно, число дней и темп живого дня описывают модель мира — их генератор знает сам. День на оси, приёмник и имя топика описывают стенд, на котором его запустили: не назвали — отказ и ненулевой код возврата, ещё до первого события. Поэтому умолчание дня и живёт в Makefile: день называет тот, кто запускает, а не тот, кого запускают.

Состав и доступ

• clickhouse-01 — инициатор DDL и точка подключения Airflow;
• clickhouse-02 — точка подключения Superset;
• clickhouse-keeper — координатор кластера;
• kafka — один брокер KRaft;
• postgres-metadata — один Postgres с отдельными базами и пользователями airflow и superset;
• airflow-apiserver, airflow-scheduler и airflow-dag-processor — Airflow 3.3 с LocalExecutor, без triggerer;
• superset — интерфейс и подготовленное подключение ClickHouse;
• prometheus и grafana — сбор и просмотр встроенных метрик ClickHouse.

Порты доступны только с локальной машины:

• нода 1 — http://127.0.0.1:28123, нативный порт 29000;
• нода 2 — http://127.0.0.1:28124, нативный порт 29001;
• Kafka — 127.0.0.1:29092;
• Airflow — http://127.0.0.1:28080, пользователь admin, пароль airflow;
• Superset — http://127.0.0.1:28088, пользователь admin, пароль superset;
• Prometheus — http://127.0.0.1:29090;
• Grafana — http://127.0.0.1:23000, пользователь admin, пароль admin.

У локального учебного кластера нет пароля: ноды используют общего пользователя default для запросов Distributed. Порты поэтому привязаны к 127.0.0.1 и не открыты во внешнюю сеть.

Пароли интерфейсов, пароли Postgres, ключи Airflow и Superset, отсутствие пароля ClickHouse и отсутствие проверки доступа у Kafka и Prometheus — намеренно простые и явно ненастоящие настройки локального учебного стенда. Это не пример настройки защиты: не копируйте значения из .env.example в рабочую среду. Все опубликованные порты привязаны только к 127.0.0.1; Postgres наружу не опубликован.

В бою перед репликами ClickHouse обычно был бы балансировщик. Здесь в каждом шарде одна реплика, поэтому балансировать нечего. Балансировщик и топология 2×2 намеренно не входят в стенд.

Конфигурация сверена 30 июля 2026 года с официальной документацией ClickHouse: настройками сервера, Keeper, ReplicatedMergeTree, ON CLUSTER и Distributed. Описание кластера задаётся через remote_servers, макросы — через macros, подключение к keeper — через zookeeper; путь ReplicatedMergeTree содержит {shard} и {replica}, а Distributed получает имя кластера, базу, локальную таблицу и ключ шардирования. Макросы выбраны, чтобы один DDL через ON CLUSTER создавал отдельный путь каждого шарда без вписанных вручную значений. Для образа зафиксирован точный текущий LTS-выпуск 26.3.17.56; серверы и keeper используют один образ. Настройки Kafka 4.3.1 сверены с примером односерверного KRaft. Секция метрик взята из конфигурации закреплённого образа ClickHouse и проверена на серверах и keeper. Подготовка источника Grafana сверена с официальным описанием автоматической настройки. Prometheus собирает только встроенные метрики двух серверов и keeper; внешних сборщиков, панелей и правил оповещения пока нет. После изменения infra/clickhouse/config.d/prometheus.xml выполните docker compose restart clickhouse-01 clickhouse-02: обычный make up не перезапускает уже созданные серверы и они продолжают работать со старой конфигурацией.

Airflow закреплён на 3.3.0. Состав обязательных процессов, LocalExecutor, публичный airflow.sdk, API здоровья и SimpleAuthManager сверены с архитектурой Airflow 3.3, публичным интерфейсом и описанием здоровья. Для пробников проверены публичный Connection.get из airflow.sdk и клиент clickhouse-connect. Официальный провайдер Kafka сам использует confluent-kafka; отдельное подключение и обёртки провайдера здесь не нужны, поэтому прямой клиент оставляет образ и пример короче. Superset закреплён на 6.1.0; драйвер clickhouse-connect, форма clickhousedb:// и драйвер Postgres сверены с документацией подключений Superset и настройкой базы метаданных.

Что здесь будет

• одно широкое событие кликстрима по образцу выгрузки Яндекс Метрики вместо четырёх топиков;
• второй источник — заказы бэкенда, ежедневным слепком в ту же Kafka;
• сверка клиентской покупки с заказом бэкенда: деньги считаем по бэкенду, поведение и атрибуцию — по трекеру;
• анонимный кликстрим и склейка кука↔пользователь через покупки;
• ClickHouse кластером как единственным режимом.

Чем отличается от предшественника

Предшественник остаётся стабильным учебным стендом и заморожен для новых фич: там событие разрезано на четыре топика, есть только просмотры страниц, посетители опознаны по email, ClickHouse — одна нода. Развитие идёт здесь.

Документация

• docs/specs/ — спеки: источник истины о задуманном.
• docs/adr/ — принятые решения с доводами и отвергнутыми вариантами: почему сделано так, а не иначе.
• docs/architecture/ — рабочие справочники по зонам ответственности: хранилище — конвенции имён, раскладка по шардам, приём событий, карта таблиц; проверки — что утверждает каждая цель make и куда класть новую проверку.
• docs/research/ — исследования; сейчас это формат кликстрима Яндекса, по которому строится модель события.
• docs/formats/ — описания форматов источников: по ним пишется сторона хранилища. Собираются из кода командой make docs, руками не правятся.
• AGENTS.md — контракт работы в репозитории.