277 lines
9.5 KiB
Markdown
Executable File
277 lines
9.5 KiB
Markdown
Executable File
# 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 (рекомендуется)
|
||
|
||
```bash
|
||
# Клонирование репозитория
|
||
git clone <repository-url>
|
||
cd ss-tools
|
||
|
||
# Запуск всех сервисов
|
||
docker compose up --build
|
||
|
||
# После запуска:
|
||
# Frontend: http://localhost:8000
|
||
# Backend API: http://localhost:8001
|
||
# PostgreSQL: localhost:5432
|
||
```
|
||
|
||
#### Вариант 2: Локально
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
### Первичная настройка
|
||
|
||
```bash
|
||
# Инициализация БД
|
||
cd backend
|
||
source .venv/bin/activate
|
||
python src/scripts/init_auth_db.py
|
||
|
||
# Создание администратора
|
||
python src/scripts/create_admin.py --username admin --password admin
|
||
```
|
||
|
||
## 🏢 Enterprise Clean Deployment (internal-only)
|
||
|
||
Для разворота в корпоративной сети используйте профиль enterprise clean:
|
||
|
||
- очищенный дистрибутив без test/demo/load-test данных;
|
||
- запрет внешних интернет-источников;
|
||
- загрузка ресурсов только с внутренних серверов компании;
|
||
- обязательная блокирующая проверка clean/compliance перед выпуском.
|
||
|
||
Быстрый запуск TUI-проверки:
|
||
|
||
```bash
|
||
cd /home/busya/dev/ss-tools
|
||
./backend/.venv/bin/python3 -m backend.src.scripts.clean_release_tui
|
||
```
|
||
|
||
Типовые внутренние источники:
|
||
- `repo.intra.company.local`
|
||
- `artifacts.intra.company.local`
|
||
- `pypi.intra.company.local`
|
||
|
||
Если найден внешний endpoint, выпуск получает статус `BLOCKED` до исправления.
|
||
|
||
## 📖 Документация
|
||
|
||
- [Установка и настройка](docs/installation.md)
|
||
- [Архитектура системы](docs/architecture.md)
|
||
- [Разработка плагинов](docs/plugin_dev.md)
|
||
- [API документация](http://localhost:8001/docs)
|
||
- [Настройка окружений](docs/settings.md)
|
||
|
||
## 🧪 Тестирование
|
||
|
||
```bash
|
||
# 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)
|
||
|
||
### Управление пользователями и ролями
|
||
|
||
```bash
|
||
# Получение списка пользователей
|
||
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"]
|
||
}
|
||
```
|
||
|
||
## 📊 Мониторинг
|
||
|
||
### Отчеты о задачах
|
||
|
||
```bash
|
||
# Список всех отчетов
|
||
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** — унифицированные отчеты по всем типам задач
|
||
|
||
## 🔄 Обновление системы
|
||
|
||
```bash
|
||
# Обновление 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
|
||
```
|
||
|
||
|