ss-tools

Инструменты автоматизации для Apache Superset: миграция, версионирование, аналитика и управление данными

📋 О проекте

ss-tools — это комплексная платформа для автоматизации работы с Apache Superset, предоставляющая инструменты для миграции дашбордов, управления версиями через Git, LLM-анализа данных и многопользовательского контроля доступа. Система построена на модульной архитектуре с плагинной системой расширений.

🎯 Ключевые возможности

🔄 Миграция данных

• Миграция дашбордов и датасетов между окружениями (dev/staging/prod)
• Dry-run режим с детальным анализом рисков и предпросмотром изменений
• Автоматическое маппинг баз данных и ресурсов между окружениями
• Поддержка legacy-данных с миграцией из SQLite в PostgreSQL

🌿 Git-интеграция

• Версионирование дашбордов через Git-репозитории
• Управление ветками и коммитами с помощью LLM
• Деплой дашбордов из Git в целевые окружения
• История изменений с детальным diff

🤖 LLM-аналитика

• Автоматическая валидация дашбордов с помощью ИИ
• Генерация документации для датасетов
• Assistant API для natural language команд
• Интеллектуальное коммитинг с подсказками сообщений

📊 Управление и мониторинг

• Многопользовательская авторизация (RBAC)
• Фоновые задачи с реальным логированием через WebSocket
• Унифицированные отчеты по выполненным задачам
• Хранение артефактов с политиками retention
• Аудит логирование всех действий

🔌 Плагины

• MigrationPlugin — миграция дашбордов
• BackupPlugin — резервное копирование
• GitPlugin — управление версиями
• LLMAnalysisPlugin — аналитика и документация
• MapperPlugin — маппинг колонок
• DebugPlugin — диагностика системы
• SearchPlugin — поиск по датасетам

🏗️ Архитектура

Технологический стек

Backend:

• Python 3.9+ (FastAPI, SQLAlchemy, APScheduler)
• PostgreSQL (основная БД)
• GitPython для Git-операций
• OpenAI API для LLM-функций
• Playwright для скриншотов

Frontend:

• SvelteKit (Svelte 5.x)
• Vite
• Tailwind CSS
• WebSocket для реального логирования

DevOps:

• Docker & Docker Compose
• PostgreSQL 16

Модульная структура

ss-tools/
├── backend/                    # Backend API
│   ├── src/
│   │   ├── api/               # API маршруты
│   │   ├── core/              # Ядро системы
│   │   │   ├── task_manager/  # Управление задачами
│   │   │   ├── auth/          # Авторизация
│   │   │   ├── migration/     # Миграция данных
│   │   │   └── plugins/       # Плагины
│   │   ├── models/            # Модели данных
│   │   ├── services/          # Бизнес-логика
│   │   └── schemas/           # Pydantic схемы
│   └── tests/                 # Тесты
├── frontend/                   # SvelteKit приложение
│   ├── src/
│   │   ├── routes/            # Страницы
│   │   ├── lib/
│   │   │   ├── components/    # UI компоненты
│   │   │   ├── stores/        # Svelte stores
│   │   │   └── api/           # API клиент
│   │   └── i18n/              # Мультиязычность
│   └── tests/
├── docker/                     # Docker конфигурация
├── docs/                       # Документация
└── specs/                      # Спецификации

🚀 Быстрый старт

Требования

Локальная разработка:

• Python 3.9+
• Node.js 18+
• npm
• 2 GB RAM (минимум)
• 5 GB свободного места

Docker (рекомендуется):

• Docker Engine 24+
• Docker Compose v2
• 4 GB RAM (для стабильной работы)

Быстрое развертывание бандла (offline)

# 1. Загрузить образ из бандла
xz -dc dist/docker/ss-tools.20260517.tar.xz | docker load

# 2. Подготовить пароль для PostgreSQL
export POSTGRES_PASSWORD="my-strong-password"

# 3. Запустить
docker compose -f dist/docker/docker-compose.light.yml up -d

# 4. Создать администратора (первый запуск)
docker exec -it ss-tools-app-1 python src/scripts/create_admin.py \
  --username admin --password '<temporary-secret>'

Команды для сборки бандла:

# Легковесный all-in-one (~104 MB)
./build.sh bundle:light v1.0.0

# Полный релиз (backend + frontend + postgres)
./build.sh bundle v1.0.0

Установка и запуск

Вариант 1: Docker (рекомендуется)

# Клонирование репозитория
git clone <repository-url>
cd ss-tools

# Запуск всех сервисов
docker compose up --build

# После запуска:
# Frontend: http://localhost:8000
# Backend API: http://localhost:8001
# PostgreSQL: localhost:5432

Вариант 2: Локально

# Backend
cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 -m uvicorn src.app:app --reload --port 8000

# Frontend (в новом терминале)
cd frontend
npm install
npm run dev -- --port 5173

Первичная настройка

# Скопируйте шаблон переменных окружения
cp .env.example backend/.env.bak   # или используйте backend/.env напрямую

# Инициализация БД
cd backend
source .venv/bin/activate
python src/scripts/init_auth_db.py

# При первом запуске будет создан backend/.env с ENCRYPTION_KEY

# Создание администратора
python src/scripts/create_admin.py --username admin --password '<strong-temporary-secret>'

Полный каталог переменных окружения — в .env.example в корне проекта.

🏢 Enterprise Clean Deployment (internal-only)

Для разворота в корпоративной сети используйте профиль enterprise clean:

• очищенный дистрибутив без test/demo/load-test данных;
• запрет внешних интернет-источников;
• загрузка ресурсов только с внутренних серверов компании;
• обязательная блокирующая проверка clean/compliance перед выпуском.

Операционный workflow (CLI/API/TUI)

1) Headless flow через CLI (рекомендуется для CI/CD)

cd backend

# 1. Регистрация кандидата
.venv/bin/python3 -m src.scripts.clean_release_cli candidate-register \
  --candidate-id 2026.03.09-rc1 \
  --version 1.0.0 \
  --source-snapshot-ref git:release/2026.03.09-rc1 \
  --created-by release-operator

# 2. Импорт артефактов
.venv/bin/python3 -m src.scripts.clean_release_cli artifact-import \
  --candidate-id 2026.03.09-rc1 \
  --artifact-id artifact-001 \
  --path backend/dist/package.tar.gz \
  --sha256 deadbeef \
  --size 1024

# 3. Сборка манифеста
.venv/bin/python3 -m src.scripts.clean_release_cli manifest-build \
  --candidate-id 2026.03.09-rc1 \
  --created-by release-operator

# 4. Запуск compliance
.venv/bin/python3 -m src.scripts.clean_release_cli compliance-run \
  --candidate-id 2026.03.09-rc1 \
  --actor release-operator

2) API flow (автоматизация через сервисы)

• V2 candidate/artifact/manifest API:
  • POST /api/clean-release/candidates
  • POST /api/clean-release/candidates/{candidate_id}/artifacts
  • POST /api/clean-release/candidates/{candidate_id}/manifests
  • GET /api/clean-release/candidates/{candidate_id}/overview
• Legacy compatibility API (оставлены для миграции клиентов):
  • POST /api/clean-release/candidates/prepare
  • POST /api/clean-release/checks
  • GET /api/clean-release/checks/{check_run_id}

3) TUI flow (тонкий клиент поверх facade)

cd /home/busya/dev/ss-tools
./run_clean_tui.sh 2026.03.09-rc1

Горячие клавиши:

• F5: Run Compliance
• F6: Build Manifest
• F7: Reset Draft
• F8: Approve
• F9: Publish
• F10: Refresh Overview

Важно: TUI требует валидный TTY. Без TTY запуск отклоняется с инструкцией использовать CLI/API.

Типовые внутренние источники:

• repo.intra.company.local
• artifacts.intra.company.local
• pypi.intra.company.local

Если найден внешний endpoint, выпуск получает статус BLOCKED до исправления.

Docker release для изолированного контура

Текущий enterprise clean профиль уже задаёт policy-level ограничения для внутреннего контура. Следующий логичный шаг для релизного процесса — выпускать не только application artifacts, но и готовый Docker bundle для разворота без доступа в интернет.

Целевой состав offline release-пакета:

• backend image с уже установленными Python-зависимостями;
• frontend image с уже собранным SvelteKit bundle;
• postgres image или внутренний pinned base image;
• docker-compose.enterprise-clean.yml для запуска в air-gapped окружении;
• .env.enterprise-clean.example с обязательными переменными;
• manifest с версиями, sha256 и перечнем образов;
• инструкции по docker load / docker compose up без обращения к внешним registry.

Рекомендуемый workflow для такого релиза:

# 1. Собрать образы в подключённом контуре
./build.sh bundle v1.0.0-rc2-docker

# Результат: dist/docker/
#   backend.v1.0.0-rc2-docker.tar.xz
#   frontend.v1.0.0-rc2-docker.tar.xz
#   postgres.v1.0.0-rc2-docker.tar.xz
#   manifest + sha256sums + docker-compose.enterprise-clean.yml + .env.enterprise-clean.example

# 2. Передать dist/docker/* в изолированный контур
# 3. Импортировать образы локально (распаковка на лету)
xz -dc dist/docker/backend.v1.0.0-rc2-docker.tar.xz | docker load
xz -dc dist/docker/frontend.v1.0.0-rc2-docker.tar.xz | docker load
xz -dc dist/docker/postgres.v1.0.0-rc2-docker.tar.xz | docker load

# 4. Подготовить env из шаблона
cp dist/docker/.env.enterprise-clean.example .env.enterprise-clean

# 4a. Для первого запуска задать bootstrap администратора
# INITIAL_ADMIN_CREATE=true
# INITIAL_ADMIN_USERNAME=<org-admin-login>
# INITIAL_ADMIN_PASSWORD=<temporary-strong-secret>

# 5. Запустить только локальные образы
docker compose --env-file .env.enterprise-clean -f dist/docker/docker-compose.enterprise-clean.yml up -d

Для легковесного all-in-one образа (без Playwright, ~104 MB вместо 575 MB):

# Сборка
./build.sh bundle:light v1.0.0

# Результат:
#   dist/docker/ss-tools.v1.0.0.tar.xz  (×5.5 меньше за счёт xz -9)
#   dist/docker/docker-compose.light.yml
#   dist/docker/manifest-light.v1.0.0.txt
#   dist/docker/sha256sums-light.v1.0.0.txt

# Загрузка и запуск:
xz -dc dist/docker/ss-tools.v1.0.0.tar.xz | docker load
docker compose -f dist/docker/docker-compose.light.yml up

Bootstrap администратора выполняется entrypoint-скриптом внутри backend container:

• если INITIAL_ADMIN_CREATE=true, контейнер вызывает create_admin.py перед стартом API;
• если администратор уже существует, учётная запись не меняется;
• теги в .env.enterprise-clean.example должны совпадать с фактически загруженными образами ss-tools-backend:v1.0.0-rc2-docker и ss-tools-frontend:v1.0.0-rc2-docker;
• после первого входа пароль должен быть ротирован, а INITIAL_ADMIN_CREATE возвращён в false.

Ограничения для production-grade offline release:

• build не должен тянуть зависимости в изолированном контуре;
• все base images должны быть заранее зеркалированы во внутренний registry или поставляться как tar;
• runtime-конфигурация не должна ссылаться на внешние API/registry/telemetry endpoints;
• clean/compliance manifest должен включать docker image digests как часть evidence package.

Практический план внедрения:

• pinned Docker image tags и отдельный enterprise-clean compose profile добавлены;
• unified build.sh bundle <tag> добавлен для build -> save -> checksum (заменил scripts/build_offline_docker_bundle.sh);
• следующим шагом стоит включить docker image digests в clean-release manifest;
• следующим шагом стоит добавить smoke-check, что compose-файлы не содержат внешних registry references вне allowlist.

📖 Документация

• Установка и настройка
• Архитектура системы
• Разработка плагинов
• API документация
• Настройка окружений

🧪 Тестирование

# Backend тесты
cd backend
source .venv/bin/activate
pytest

# Frontend тесты
cd frontend
npm run test

# Запуск конкретного теста
pytest tests/test_auth.py::test_create_user

🔐 Авторизация

Система поддерживает два метода аутентификации:

1. Локальная аутентификация (username/password)
2. ADFS SSO (Active Directory Federation Services)

Управление пользователями и ролями

# Получение списка пользователей
GET /api/admin/users

# Создание пользователя
POST /api/admin/users
{
  "username": "newuser",
  "email": "user@example.com",
  "password": "password123",
  "roles": ["analyst"]
}

# Создание роли
POST /api/admin/roles
{
  "name": "analyst",
  "permissions": ["dashboards:read", "dashboards:write"]
}

📊 Мониторинг

Отчеты о задачах

# Список всех отчетов
GET /api/reports?page=1&page_size=20

# Детали отчета
GET /api/reports/{report_id}

# Фильтры
GET /api/reports?status=failed&task_type=validation&date_from=2024-01-01

Активность

• Dashboard Hub — управление дашбордами с Git-статусом
• Dataset Hub — управление датасетами с прогрессом маппинга
• Task Drawer — мониторинг выполнения фоновых задач
• Unified Reports — унифицированные отчеты по всем типам задач

🔄 Обновление системы

# Обновление Docker контейнеров
docker compose pull
docker compose up -d

# Обновление зависимостей Python
cd backend
source .venv/bin/activate
pip install -r requirements.txt --upgrade

# Обновление зависимостей Node.js
cd frontend
npm install

💻 Примеры скриптов

Примеры Python и Bash скриптов для вызова API ss-tools из внешних систем (Airflow, CI/CD, cron) находятся в каталоге examples/.

• Python — examples/maintenance-api-python.py
• Bash — examples/maintenance-api-bash.sh

Скрипты демонстрируют аутентификацию через API Key (X-API-Key), запуск и завершение maintenance-событий, а также обработку ошибок.