ddadminandClaude Fable 5.1
7108cd4af3
Зачем: README был складом сведений, осевших там, где писались. По раскладке резолюции #211 он становится лицом репозитория: промо-блок, «куда я попал», типовые действия, ссылки. Слово «менти» уходит из README и путеводителя, хвосты #212 и #214 закрываются. Что: промо-цитата со ссылкой на план обучения и ментора; шапка с нейтральной адресацией и одной фразой о составе и пути данных; «Быстрый старт» сжат до двух команд по решению владельца — проверки остаются роботам, в README одна ссылка на карту проверок; разделы «Адреса и пароли», «Сдвинуть мир вперед», «Вернуть мир к началу», «Выключить или сбросить целиком», «Подключиться из DBeaver»; «Документация» называет все семь справочников вложенным списком. Умерли «Статус», «Что здесь будет», «Чем отличается от предшественника» и три заголовка-якоря. В world.md снята устаревшая фраза о «даге этапа 5», stand.md и ADR 0007 ведут на новый раздел «Адреса и пароли», в путеводителе снято слово «менти». Проверка: скрипт ссылок пуст, grep «менти» по README и путеводителю пуст, make config-test зеленый. Саморевью Sol 1/1; слепое ревью Opus — 0 блокеров, 2 minor, 3 nit, все закрыты; вычитка прозы ai-text-lint и оптикой литературного русского — 15 находок, 9 внесены, 6 отклонены как слова владельца и термины. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
137 lines
9.9 KiB
Markdown
137 lines
9.9 KiB
Markdown
# Учебная дата-платформа кликстрима
|
||
|
||
> Этим стендом можно пользоваться самостоятельно. Он также входит в
|
||
> [план обучения 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).
|
||
|
||
В стенде подняты кластер ClickHouse из двух шардов, отдельный keeper, Kafka,
|
||
Airflow, Superset, Prometheus и Grafana; события кликстрима и заказы бэкенда
|
||
приезжают из генератора и идут по слоям STG → ODS → DDS → DM. `make up`
|
||
наполняет стенд стартовым миром — первой неделей модельного времени. Чтобы
|
||
разобраться в устройстве, начните с [путеводителя](docs/handbook/README.md), а
|
||
учиться — с [уроков](docs/labs/README.md).
|
||
|
||
## Быстрый старт
|
||
|
||
Нужны Docker с Compose и около 8 ГБ памяти, доступной Docker. Это не объём
|
||
ноутбука, а то, что отдано самому Docker: в Docker Desktop и WSL2 он живёт
|
||
внутри виртуальной машины и получает лишь часть памяти хозяина. Сколько выдано
|
||
сейчас, в байтах, покажет `docker info --format '{{.MemTotal}}'`. В WSL2 это
|
||
поднимается параметром `memory` в файле `.wslconfig` домашнего каталога
|
||
пользователя Windows; после правки нужен `wsl --shutdown`. Если своей машины не
|
||
хватает, стенд одинаково хорошо живёт на недорогом VPS.
|
||
|
||
`make up` нужны `curl` и `jq`: первым он ходит в Airflow, вторым читает
|
||
паспорт мира, по которому ждет заливки. По умолчанию должны быть свободны
|
||
порты `23000`, `28080`, `28088`, `28123`, `28124`, `29000`, `29001`, `29090`
|
||
и `29092`. Всем целям генератора в `generator/` нужен `uv`.
|
||
|
||
Сначала скопируйте настройки стенда:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
make up
|
||
```
|
||
|
||
`make up` сам ждет заливки стартового мира; что он делает по шагам и какие
|
||
проверки есть у стенда, описано в [карте
|
||
проверок](docs/architecture/testing.md).
|
||
|
||
`.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` создаст их с новыми
|
||
значениями.
|
||
|
||
## Адреса и пароли
|
||
|
||
С настройками из `.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).
|
||
|
||
## Сдвинуть мир вперед
|
||
|
||
В Airflow запустите даг `world_next_day`: по умолчанию он сыграет один день, а
|
||
в форме запуска можно задать другое число дней. Снимите с паузы `world_live`,
|
||
и мир поедет сам в темпе модельного времени. Подробности — в [справочнике
|
||
мира](docs/architecture/world.md#даги-модельного-времени).
|
||
|
||
## Вернуть мир к началу
|
||
|
||
`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).
|
||
|
||
## Документация
|
||
|
||
- [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/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/) — описания форматов источников: по ним
|
||
пишется сторона хранилища. Собираются из кода командой `make docs` в
|
||
`generator/`, руками не правятся.
|
||
- [AGENTS.md](AGENTS.md) — контракт работы в репозитории.
|