Add DAG and migration_reporter module

2026-10-29 16:14:13 +03:00
parent d89623b013
commit 16ee4d41e4
4 changed files with 6674 additions and 0 deletions
@@ -0,0 +1,117 @@
+# Airflow: настройка пайплайна отчетов по миграциям
+
+DAG: `dags/migration_reporter_dag.py` — расписание **Пн / Ср / Пт 08:00** (`0 8 * * 1,3,5`).
+
+Граф задач:
+
+```
+pull_repo → generate_excel → generate_html
+```
+
+Скрипт пайплайна: `migration_reporter.py` (лежит в корне репозитория миграций).
+
+---
+
+## 1. Установка Airflow 3 (docker-compose)
+
+В каталоге проекта Airflow (например, `/projects/airflow-docker`) — по официальной документации
+https://airflow.apache.org/docs/apache-airflow/stable/howto/docker-compose/index.html
+
+Файл `.env` там же:
+
+```env
+_AIP_UID=..
+# дополнительные пакеты в контейнерах (быстрый способ для теста)
+_PIP_ADDITIONAL_REQUIREMENTS=openpyxl
+```
+
+> Для постоянной работы лучше свой Dockerfile:
+> ```dockerfile
+> FROM apache/airflow:3.3.2
+> RUN pip install openpyxl
+> ```
+> и в `docker-compose.yaml` в `image:` указать имя собранного образа
+> (`docker build -t airflow-with-pydeps .`).
+
+## 2. Volume-монтирования (репозиторий + папка отчетов)
+
+В `docker-compose.yaml` в общий блок `x-airflow-common`:
+
+```yaml
+x-airflow-common: &airflow-common
+  volumes:
+    - ./dags:/opt/airflow/dags
+    - ./config:/opt/airflow/config
+    - ./logs:/opt/airflow/logs
+    - ./plugins:/opt/airflow/plugins
+    # путь на хосте (Windows) : путь в контейнере
+    - C:/Users/veremeytsev_dg/Desktop/migrations_tool:/opt/airflow/migrations_tool    # репозиторий миграций
+    - C:/Users/veremeytsev_dg/Desktop/migrations_reports:/opt/airflow/reports         # общая папка отчетов
+```
+
+После этого перезапустить: `docker compose up -d`.
+
+Дагфайл кладется в `./dags/migration_reporter_dag.py` (папка dags уже смонтирована).
+
+## 3. Git-доступ из контейнера
+
+На хосте Windows аутентификация работает через credential-manager — в контейнере его нет.
+Два варианта (один раз, внутри контейнера):
+
+```bash
+# а) Токен в remote-url (быстро; хранить токен в Airflow Variable и клонировать им)
+docker compose exec airflow-worker git clone \
+  https://<user>:<token>@seedvault.coderocket.ru/SZA_analytics/migrations.git \
+  /opt/airflow/migrations_tool
+
+# б) SSH-deploy key в volume (надежнее для продакшена)
+# смонтировать ключ и: git -c core.sshCommand="ssh -i /opt/airflow/ssh/key" clone ...
+```
+
+Проверка: `docker compose exec airflow-worker git -C /opt/airflow/migrations_tool pull --ff-only`
+
+## 4. Airflow Variables (пути)
+
+В UI: Admin → Variables, либо CLI:
+
+```bash
+docker compose exec airflow-scheduler airflow variables set migrations_repo_dir /opt/airflow/migrations_tool
+docker compose exec airflow-scheduler airflow variables set migrations_reports_dir /opt/airflow/reports
+```
+
+Можно не задавать — в DAG есть env-fallback (`MIGRATIONS_REPO_DIR`, `MIGRATIONS_REPORTS_DIR`).
+
+## 5. Запуск и проверка
+
+```bash
+docker compose exec airflow-scheduler airflow dags list
+docker compose exec airflow-scheduler airflow dags trigger migration_reporter_pipeline
+docker compose exec airflow-scheduler airflow tasks states-for-run migration_reporter_pipeline <run_id>
+```
+
+Артефакты прогона (в общей папке `/opt/airflow/reports` ↔ хост):
+
+```
+migration_report_YYYYMMDD_HHMMSS.xlsx   # Excel (11 листов)
+migration_report_YYYYMMDD_HHMMSS.changes.json  # кэш изменений (между задачами DAG)
+migration_report_YYYYMMDD_HHMMSS.html   # HTML-отчет (батчи по дате загрузки)
+latest.xlsx / latest.html               # фиксированные имена последнего отчета
+```
+
+## 6. Локальный запуск без Airflow
+
+```bash
+cd migrations_tool
+python migration_reporter.py run --dir pgsql --skip-pull          # без git pull
+python migration_reporter.py run --dir pgsql                      # с git pull
+python migration_reporter.py excel --dir pgsql --output r.xlsx    # только Excel
+python migration_reporter.py html --cache r.changes.json --output r.html  # только HTML
+```
+
+## 7. Ручная генерация отдельного шага
+
+| Команда | Что делает |
+|---|---|
+| `excel` | анализ + Excel-отчет + `.changes.json` кэш |
+| `html`  | HTML из кэша (быстро, без повторного анализа) |
+| `run`   | полный цикл (для локального запуска / восстановления) |