clickstream-data-platform/README.md

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

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

Статус

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

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

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

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

make up
make smoke

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

cp .env.example .env
make up
make smoke

Учётные данные 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 проверяет согласованность .env.example с Compose, зависимости машины, здоровье контейнеров, Kafka через порт машины, три цели Prometheus, источник Grafana, компоненты Airflow, ручной запуск пробников test_clickhouse и test_kafka, метаданные и подключение Superset. Первый пробник создаёт таблицы на обеих нодах и читает через Distributed на ноде 2 строку из локальной таблицы ноды 1. Второй пишет в Kafka и читает свой маркер. В конце проверка ждёт 20 секунд покоя, печатает общую память контейнеров и падает при превышении 3,4 ГБ. Временный топик проверки с машины и запуски DAG удаляются; постоянный топик пробника сохраняется, а старые записи чистит Kafka.

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

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

make smoke-guards сначала проверяет аварийную семантику кластерной проверки, а затем удаляет служебную таблицу пробника только на второй ноде и останавливает Prometheus с Kafka. Общая проверка должна назвать Prometheus и оба пробника, после чего завершиться с ошибкой. В конце стенд восстанавливается.

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

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

• 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/research/ — исследования; сейчас это формат кликстрима Яндекса, по которому строится модель события.
• AGENTS.md — контракт работы в репозитории.