# Учебная дата-платформа кликстрима Стенд для работы с кликстримом. Преемник учебного стенда [clickstream-ch-kafka-superset-demo](https://git.dementev.space/ddmitry/clickstream-ch-kafka-superset-demo). ## Статус Репозиторий строится по спеке [«Боевой реализм стенда (v2)»](docs/specs/2026-07-30-stand-v2-realism.md). Сейчас работают кластер ClickHouse из двух шардов, отдельный clickhouse-keeper, односерверная Kafka в режиме KRaft, Airflow 3.3, Superset, Prometheus, Grafana и общая база Postgres для метаданных. Начат генератор кликстрима: в [`generator/`](generator/) заведён контракт схемы события, из которого собрано [описание выгрузки](docs/formats/clickstream-event.md). ## Быстрый старт Нужны 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`: ```bash make up make smoke ``` Чтобы изменить образы, порты или учебные учётные данные, скопируйте образец: ```bash 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, ручной запуск пробников `test_clickhouse` и `test_kafka`, метаданные и подключение Superset. Первый пробник создаёт таблицы на обеих нодах и читает через `Distributed` на ноде 2 строку из локальной таблицы ноды 1. Второй пишет в Kafka и читает свой маркер. В конце проверка спрашивает у Docker, не убивало ли ядро что-нибудь в долгоживущих контейнерах за нехватку памяти и не включалась ли политика перезапуска: убитый контейнер Docker поднимает сам, и проверка состояния об этом промолчит. Временный топик проверки с машины и запуски DAG удаляются; постоянный топик пробника сохраняется, а старые записи чистит Kafka. Одиннадцать проверок здоровья сразу после `make up --wait` повторяют то, чего Compose уже дождался: у каждой долгоживущей службы есть своя `healthcheck`. Оставлены они потому, что первый вопрос к стенду всё равно «всё ли живо», а ответ на него стоит меньше секунды. Устройство keeper — другое дело: он должен работать от пользователя `clickhouse`, с пределом в 262144 открытых файла и со своим томом под данные. Всё это объявлено в `compose.yaml`, но здоровым keeper выглядит и без этого, поэтому смоук спрашивает у живого контейнера, дошли ли объявленные настройки до процесса. `make smoke-cluster` запускает отдельную глубокую проверку ClickHouse: описание кластера, макросы, связь с keeper, `ReplicatedMergeTree`, `Distributed`, очередь распределённых DDL и очистку временных таблиц. `make config-test` проверяет Compose, синтаксис Bash и Python и пробельные ошибки в diff без запуска стенда. Правило, которое стоит держать в голове, правя любую из этих проверок: **проверка, которая не умеет краснеть, бесполезна.** Проверка, никогда не видевшая своей поломки, доказывает только то, что она умеет печатать «ЗЕЛЁНО». Убедиться дешевле всего руками: сломайте то, что она стережёт — остановите `prometheus`, удалите служебную таблицу пробника на второй ноде, — и посмотрите, покраснеет ли прогон и назовёт ли виновника. Не покраснел — проверка не работает, и чинить надо её, а не стенд. ### Какую проверку когда запускать Проверки выстроены лесенкой: чем дороже прогон, тем больше связей он трогает. - `make config-test` — секунды, стенд поднимать не нужно. Видит только то, что есть в файлах, и о работоспособности не говорит ничего. Дёшево настолько, что можно гонять перед каждым коммитом. - `make lint` и `make test` — тоже секунды и тоже без стенда, но про другой код: ruff и тесты генератора в `generator/`. Тесты сторожат контракт схемы события и свежесть собранного из него описания выгрузки. - `make smoke` — минута-две на поднятом стенде. Дороже, но проверяет связи между службами, а не отдельные файлы: это интеграционная проверка. - `make smoke-cluster` — около минуты. Одна связь, зато до дна: межнодовое устройство ClickHouse. Обычный рабочий цикл — `make config-test` и `make smoke`. Остановить контейнеры без удаления данных можно командой `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: [настройками сервера](https://clickhouse.com/docs/operations/server-configuration-parameters/settings), [Keeper](https://clickhouse.com/docs/guides/oss/deployment-and-scaling/keeper/), [ReplicatedMergeTree](https://clickhouse.com/docs/engines/table-engines/mergetree-family/replication), [ON CLUSTER](https://clickhouse.com/docs/sql-reference/distributed-ddl) и [Distributed](https://clickhouse.com/docs/engines/table-engines/special/distributed). Описание кластера задаётся через `remote_servers`, макросы — через `macros`, подключение к keeper — через `zookeeper`; путь `ReplicatedMergeTree` содержит `{shard}` и `{replica}`, а `Distributed` получает имя кластера, базу, локальную таблицу и ключ шардирования. Макросы выбраны, чтобы один DDL через `ON CLUSTER` создавал отдельный путь каждого шарда без вписанных вручную значений. Для образа зафиксирован точный текущий [LTS-выпуск 26.3.17.56](https://github.com/ClickHouse/ClickHouse/releases/tag/v26.3.17.56-lts); серверы и keeper используют один образ. Настройки Kafka 4.3.1 сверены с [примером односерверного KRaft](https://github.com/apache/kafka/blob/4.3.1/docker/examples/docker-compose-files/single-node/plaintext/docker-compose.yml). Секция метрик взята из конфигурации закреплённого образа ClickHouse и проверена на серверах и keeper. Подготовка источника Grafana сверена с [официальным описанием автоматической настройки](https://grafana.com/docs/grafana/latest/administration/provisioning/). 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](https://airflow.apache.org/docs/apache-airflow/3.3.0/core-concepts/overview.html), [публичным интерфейсом](https://airflow.apache.org/docs/apache-airflow/3.3.0/public-airflow-interface.html) и [описанием здоровья](https://airflow.apache.org/docs/apache-airflow/3.3.0/administration-and-deployment/logging-monitoring/check-health.html). Для пробников проверены публичный `Connection.get` из `airflow.sdk` и клиент `clickhouse-connect`. Официальный провайдер Kafka сам использует `confluent-kafka`; отдельное подключение и обёртки провайдера здесь не нужны, поэтому прямой клиент оставляет образ и пример короче. Superset закреплён на 6.1.0; драйвер `clickhouse-connect`, форма `clickhousedb://` и драйвер Postgres сверены с [документацией подключений Superset](https://superset.apache.org/user-docs/6.1.0/databases/) и [настройкой базы метаданных](https://superset.apache.org/admin-docs/6.1.0/configuration/configuring-superset/). ## Что здесь будет - одно широкое событие кликстрима по образцу выгрузки Яндекс Метрики вместо четырёх топиков; - второй источник — заказы бэкенда, ежедневным слепком в ту же Kafka; - сверка клиентской покупки с заказом бэкенда: деньги считаем по бэкенду, поведение и атрибуцию — по трекеру; - анонимный кликстрим и склейка кука↔пользователь через покупки; - ClickHouse кластером как единственным режимом. ## Чем отличается от предшественника Предшественник остаётся стабильным учебным стендом и заморожен для новых фич: там событие разрезано на четыре топика, есть только просмотры страниц, посетители опознаны по email, ClickHouse — одна нода. Развитие идёт здесь. ## Документация - [docs/specs/](docs/specs/) — спеки: источник истины о задуманном. - [docs/adr/](docs/adr/) — принятые решения с доводами и отвергнутыми вариантами: почему сделано так, а не иначе. - [docs/architecture/](docs/architecture/) — рабочие справочники по зонам ответственности; сейчас это [хранилище](docs/architecture/storage.md): конвенции имён, раскладка по шардам, приём событий, карта таблиц. - [docs/research/](docs/research/) — исследования; сейчас это формат кликстрима Яндекса, по которому строится модель события. - [docs/formats/](docs/formats/) — описания форматов источников: по ним пишется сторона хранилища. Собираются из кода командой `make docs`, руками не правятся. - [AGENTS.md](AGENTS.md) — контракт работы в репозитории.