ddadminandClaude Fable 5.1
7a3542d933
Зачем: ревью владельца по PR #213. Сверка конфигурации в stand.md приехала из README одним абзацем на двадцать строк, а Superset был приклеен к Airflow без пустой строки. Три места в world.md читались калькой с английского. Что: ледгер «Что проверено» разбит на записи по темам — ClickHouse, Kafka, метрики и Grafana, Airflow, Superset. В world.md заголовок «Как позвать генератор» стал «Как запустить генератор» (якоря в README и generator/README.md обновлены), переписаны абзацы про значения по умолчанию и про сокет Docker. Смысл не менялся. Словарь проекта («пульт мира», «опись мира», «работник», «сырье») не трогался: это термины CONTEXT.md и ADR, их пересмотр — отдельная развилка. Проверка: скрипт ссылок из тикета — пустой вывод; make config-test — ЗЕЛЁНО; старый якорь «как-позвать-генератор» в репозитории не встречается. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014QBCtU38qSHg5DvgtnKXcW
155 lines
11 KiB
Markdown
155 lines
11 KiB
Markdown
# Учебная дата-платформа кликстрима
|
||
|
||
Этот стенд — для менти, который видит такую систему впервые и хочет
|
||
проследить весь путь данных: от кликстрима и заказов до витрин, проверок и
|
||
графиков. Преемник учебного стенда
|
||
[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` наполняет стенд стартовым миром — первой неделей
|
||
модельного времени.
|
||
|
||
## Быстрый старт
|
||
|
||
Нужны 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`. `jq` нужен и самому `make up`: им
|
||
читается опись мира, по которой он ждёт заливки. По умолчанию должны быть свободны
|
||
порты `23000`, `28080`, `28088`, `28123`, `28124`, `29000`, `29001`, `29090`
|
||
и `29092`. Проверкам без стенда — `make config-test` и `make lint` в корне,
|
||
всем целям генератора в `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`.
|
||
|
||
`.env.example` — образец обязательной локальной настройки. В нём живут имя
|
||
экземпляра, внешние порты, учебные учётные данные и ключи. Одно значение образца
|
||
верно не везде — `DOCKER_GID`: у группы `docker` на каждой машине свой номер, и
|
||
свой подскажет `getent group docker`. Пока он не сойдётся, стенд работает весь,
|
||
кроме [пульта мира](docs/architecture/world.md#пульт-мира). `compose.yaml` не
|
||
дублирует их умолчаниями: если значения нет в `.env`, Compose сразу предложит
|
||
скопировать образец. Внутренние адреса, имена топиков и версии образов описывают
|
||
сам стенд, поэтому записаны литералами в `compose.yaml` и Dockerfile.
|
||
|
||
Учётные данные Postgres и Grafana применяются при создании их томов.
|
||
После первого запуска меняйте их только вместе с `make clean`: команда удалит
|
||
все локальные данные стенда, а следующий `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` порты доступны только с локальной машины:
|
||
|
||
- нода 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`.
|
||
|
||
Службы, пользователи и роли, применение настроек и результаты сверки
|
||
конфигурации описаны в [справочнике стенда](docs/architecture/stand.md).
|
||
|
||
## Что здесь будет
|
||
|
||
- одно широкое событие кликстрима по образцу выгрузки Яндекс Метрики вместо
|
||
четырёх топиков;
|
||
- второй источник — заказы бэкенда, ежедневным слепком в ту же Kafka;
|
||
- сверка клиентской покупки с заказом бэкенда: деньги считаем по бэкенду,
|
||
поведение и атрибуцию — по трекеру;
|
||
- анонимный кликстрим и склейка кука↔пользователь через покупки;
|
||
- ClickHouse кластером как единственным режимом.
|
||
|
||
## Чем отличается от предшественника
|
||
|
||
Предшественник остаётся стабильным учебным стендом и заморожен для новых фич:
|
||
там событие разрезано на четыре топика, есть только просмотры страниц,
|
||
посетители опознаны по email, ClickHouse — одна нода. Развитие идёт здесь.
|
||
|
||
## Документация
|
||
|
||
- [docs/handbook/](docs/handbook/) — путеводитель по стенду и порядок чтения.
|
||
- [docs/labs/](docs/labs/) — учебные задания с порядком прохождения и
|
||
самопроверкой.
|
||
- [docs/specs/](docs/specs/) — спеки: источник истины о задуманном.
|
||
- [docs/adr/](docs/adr/) — принятые решения с доводами и отвергнутыми
|
||
вариантами: почему сделано так, а не иначе.
|
||
- [docs/architecture/](docs/architecture/) — рабочие справочники по зонам
|
||
ответственности: [хранилище](docs/architecture/storage.md) — конвенции имён,
|
||
раскладка по шардам, приём событий, карта таблиц;
|
||
[проверки](docs/architecture/testing.md) — что утверждает каждая цель `make`
|
||
и куда класть новую проверку.
|
||
- [docs/research/](docs/research/) — исследования; сейчас это формат
|
||
кликстрима Яндекса, по которому строится модель события.
|
||
- [docs/formats/](docs/formats/) — описания форматов источников: по ним
|
||
пишется сторона хранилища. Собираются из кода командой `make docs` в
|
||
`generator/`, руками не правятся.
|
||
- [AGENTS.md](AGENTS.md) — контракт работы в репозитории.
|