ddadminandClaude Fable 5
dda4f3aeb5
- Зачем:
- исполнение спеки «Боевой реализм стенда» идёт в новом репозитории;
читатель v1 должен сразу видеть, где продолжение, а спека — где её
актуальная версия.
- Что:
- README: блок-указатель у начала — стенд заморожен для новых фич,
остаётся учебным, развитие в clickstream-data-platform.
- docs/specs/2026-07-30-stand-v2-realism.md: строка «Источник истины
переехал в v2» со ссылкой на копию спеки в новом репозитории.
- Проверка:
- ссылки открываются, содержание спеки не менялось.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
188 lines
10 KiB
Markdown
188 lines
10 KiB
Markdown
# Учебный стенд DWH кликстрима
|
||
|
||
[](./docker-compose.yml)
|
||
[](./docs/ARCHITECTURE.md)
|
||
|
||
> **Стенд заморожен для новых фич.** Он остаётся стабильным учебным стендом:
|
||
> что здесь работает, то работает и дальше — курс и лабы живут тут.
|
||
> Развитие переехало в
|
||
> [clickstream-data-platform](https://git.dementev.space/ddmitry/clickstream-data-platform):
|
||
> там одно широкое событие кликстрима вместо четырёх топиков, заказы бэкенда
|
||
> вторым источником и ClickHouse кластером.
|
||
|
||
Живой стек для работы с кликстримом: Kafka, ClickHouse, Airflow, Superset и мониторинг
|
||
(Prometheus с Grafana) поднимаются в Docker одной командой. На этом стенде можно учиться
|
||
по курсу или просто поднять его у себя и поэкспериментировать с потоковой загрузкой и
|
||
витринами.
|
||
|
||
Поток данных коротко:
|
||
- **стартовая история**: `world_init → Kafka → ClickHouse (STG) →
|
||
batch STG → ODS → DDS → DM → Superset`.
|
||
- **живое продолжение**: `generator live → Kafka → ClickHouse (STG) → batch ETL
|
||
→ Superset`.
|
||
|
||
Файлы `data/*.jsonl` больше не основной источник аналитики. Пока они остаются
|
||
архивной кладовкой значений для генератора: браузеры, страны, устройства и UTM.
|
||
|
||
## Куда дальше
|
||
|
||
- **Хочешь учиться** — открой [курс «Кликстрим на ClickHouse»](./docs/course/README.md).
|
||
Это продвинутый курс «со звёздочкой»: основные приёмы инженерии данных проходишь прямо
|
||
на этом стенде.
|
||
- **Хочешь поднять и попробовать** — следуй быстрому старту ниже.
|
||
- **Хочешь разобраться в устройстве** — смотри [архитектуру слоёв](./docs/ARCHITECTURE.md),
|
||
[запуск и эксплуатацию](./docs/OPERATIONS.md) и [карту репозитория](./docs/REPO_MAP.md).
|
||
|
||
## Быстрый старт
|
||
|
||
Перед первой командой нужны `Docker` с `docker compose`, `make`, `bash`, `curl`,
|
||
`git` и `uv`. `uv` нужен для локальных Python-проверок и команд разработки.
|
||
|
||
Для ручной работы поднимите стенд:
|
||
|
||
```bash
|
||
make up
|
||
docker compose ps
|
||
```
|
||
|
||
Дальше всё делается в Airflow: `http://localhost:8080` (`admin/admin`).
|
||
Список DAG'ов читается лесенкой сверху вниз; на свежем стенде все DAG'и
|
||
создаются на паузе, поэтому перед запуском снимайте паузу переключателем
|
||
слева от имени.
|
||
|
||
1. `ddl_init` — снимите паузу и запустите: DAG создаст схему ClickHouse
|
||
(отдельная команда в терминале не нужна).
|
||
2. `etl_pipeline` — только снимите паузу: его запустит следующий шаг.
|
||
3. `world_init` — снимите паузу и запустите с пустой формой: DAG импортирует
|
||
эталонный мир, запустит ETL и сверит витрины.
|
||
4. `world_next_day` — когда захотите добавить ровно один модельный день,
|
||
запустите его с пустой формой. Расписание задано каждые 30 минут, но по
|
||
умолчанию DAG стоит на паузе.
|
||
|
||
`make up` не запускает live-генератор; live включается отдельно командой
|
||
`make generator-continue`.
|
||
|
||
После обновления репозитория снова выполните `make up`: команда пересобирает
|
||
Airflow-образ и подтягивает новые зависимости и DAG-и. Superset-дэшборд
|
||
собирается позже, когда DM уже готов: через `make generated-history-analytics`
|
||
или `make superset-init`.
|
||
|
||
Для полностью автоматического чистого прогона из консоли есть команда — это
|
||
тот же путь, что выше через Airflow UI, но одной командой и без ручных шагов
|
||
(схему ClickHouse она применяет сама):
|
||
|
||
```bash
|
||
make generated-history-analytics
|
||
```
|
||
|
||
По умолчанию используется учебный профиль `daily-wave`: 3 суток с суточной
|
||
волной. В live-продолжении он идёт с ×60: модельные сутки проходят примерно
|
||
за 24 настенные минуты. Плоский профиль `ci` на 6 часов остаётся служебным
|
||
для автоматических тестов.
|
||
|
||
Разовую длительность можно задать без ручного расчёта правой границы:
|
||
|
||
```bash
|
||
GEN_HISTORY_DURATION=2d make generated-history-analytics
|
||
```
|
||
|
||
Повторить техническую проверку после такого прогона только стартовой истории:
|
||
|
||
```bash
|
||
CHECK_LIVE_SEAM=0 make generated-history-check
|
||
```
|
||
|
||
Стык backfill/live проверяйте отдельным коротким сценарием:
|
||
|
||
```bash
|
||
make generated-history-runtime-check
|
||
```
|
||
|
||
Перед коммитом используйте быстрые проверки:
|
||
|
||
```bash
|
||
make test
|
||
make lint
|
||
```
|
||
|
||
Они не чистят volumes и не запускают долгие стендовые сценарии. Полная проверка
|
||
стыка backfill/live остаётся отдельной командой `make generated-history-runtime-check`.
|
||
|
||
Сохранить стартовую историю в файл и восстановить её без новой генерации можно
|
||
по [runbook стартовой истории](./docs/runbooks/startup-history.md).
|
||
|
||
Проверить, что данные дошли до витрин:
|
||
|
||
```bash
|
||
docker compose exec -T clickhouse clickhouse-client --user=default --password=123456 \
|
||
--query "SELECT count() FROM dm.v_events_enriched"
|
||
```
|
||
|
||
Подробный сценарий запуска, параметры DAG-ов и разбор частых проблем — в
|
||
[OPERATIONS](./docs/OPERATIONS.md).
|
||
|
||
## Сервисы и доступы
|
||
|
||
| Сервис | Адрес | Назначение | Логин/пароль |
|
||
|--------|-------|------------|--------------|
|
||
| Airflow | `http://localhost:8080` | оркестрация ETL | admin/admin |
|
||
| ClickHouse | `http://localhost:9123/play` | SQL-запросы | default/123456 |
|
||
| Kafka UI | `http://localhost:8082` | просмотр топиков | — |
|
||
| Superset | `http://localhost:8088` | дашборды | admin/admin |
|
||
| Prometheus | `http://localhost:9090` | метрики | — |
|
||
| Grafana | `http://localhost:3000` | графики метрик | admin/admin |
|
||
|
||
Готовый дашборд в Superset:
|
||
`http://localhost:8088/superset/dashboard/ecommerce-analytics/` — он создаётся
|
||
во время `make generated-history-analytics`. Состав и настройка дашборда описаны в
|
||
[SUPERSET_DASHBOARD](./docs/SUPERSET_DASHBOARD.md).
|
||
|
||
## Как устроен поток данных
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph GEN["Generator"]
|
||
BF["backfill"]
|
||
LIVE["live"]
|
||
end
|
||
|
||
subgraph Kafka["Kafka"]
|
||
Topics[4 топика]
|
||
end
|
||
|
||
subgraph CH["ClickHouse"]
|
||
STG["STG: сырые данные"]
|
||
ODS["ODS: типизация + DQ"]
|
||
DDS["DDS: сущности"]
|
||
DM["DM: витрины VIEW"]
|
||
end
|
||
|
||
BF -->|стартовая история| Kafka
|
||
LIVE -->|продолжение| Kafka
|
||
Kafka -->|Kafka MV| STG
|
||
STG -->|batch| ODS -->|batch| DDS -->|VIEW| DM
|
||
|
||
DDL["DDL"] -.-> CH
|
||
```
|
||
|
||
«Грязные» записи не роняют пайплайн: ошибки разбора складываются в `ods.*_errors` и в
|
||
поле `parse_errors`, а обработка продолжается.
|
||
|
||
Подробное описание слоёв STG/ODS/DDS/DM, диаграммы и обоснование решений —
|
||
в [ARCHITECTURE](./docs/ARCHITECTURE.md).
|
||
|
||
## Документация
|
||
|
||
- [Архитектура и слои](./docs/ARCHITECTURE.md) — устройство STG/ODS/DDS/DM, диаграммы,
|
||
обоснование решений.
|
||
- [Запуск и эксплуатация](./docs/OPERATIONS.md) — сценарий запуска, параметры DAG-ов,
|
||
мониторинг, частые проблемы.
|
||
- [Runbook стартовой истории](./docs/runbooks/startup-history.md) — экспорт,
|
||
импорт эталонного мира из Git по умолчанию и live-продолжение.
|
||
- [Карта репозитория](./docs/REPO_MAP.md) — где какие файлы и что менять.
|
||
- [Реализм генератора](./docs/generator-realism.md) — что в потоке как в бою,
|
||
а что учебная условность.
|
||
- [Курс «Кликстрим на ClickHouse»](./docs/course/README.md) — учебная программа на этом
|
||
стенде.
|
||
- [DE-task.md](./docs/DE-task.md) — задание, из которого вырос стенд.
|