busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
master
ss-tools/README.md

15 KiB
Executable File
Raw Permalink Blame History

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 (для стабильной работы)

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

Вариант 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

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

# Инициализация БД
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>'

🏢 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. Собрать образы в подключённом контуре
./scripts/build_offline_docker_bundle.sh v1.0.0-rc2-docker

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

# 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

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 добавлены;
  • shell script scripts/build_offline_docker_bundle.sh добавлен для build -> save -> checksum;
  • следующим шагом стоит включить docker image digests в clean-release manifest;
  • следующим шагом стоит добавить smoke-check, что compose-файлы не содержат внешних registry references вне allowlist.

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

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

# 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