129 lines
7.4 KiB
Markdown
Executable File
129 lines
7.4 KiB
Markdown
Executable File
# Инструменты автоматизации Superset (ss-tools)
|
||
|
||
## Обзор
|
||
**ss-tools** — это современная платформа для автоматизации и управления экосистемой Apache Superset. Проект перешел от набора CLI-скриптов к полноценному веб-приложению с архитектурой Backend (FastAPI) + Frontend (SvelteKit), обеспечивая удобный интерфейс для сложных операций.
|
||
|
||
## Основные возможности
|
||
|
||
### 🚀 Миграция и управление дашбордами
|
||
- **Dashboard Grid**: Удобный просмотр всех дашбордов во всех окружениях (Dev, Sandbox, Prod) в едином интерфейсе.
|
||
- **Интеллектуальный маппинг**: Автоматическое и ручное сопоставление датасетов, таблиц и схем при переносе между окружениями.
|
||
- **Проверка зависимостей**: Валидация наличия всех необходимых компонентов перед миграцией.
|
||
|
||
### 📦 Резервное копирование
|
||
- **Планировщик (Scheduler)**: Автоматическое создание резервных копий дашбордов и датасетов по расписанию.
|
||
- **Хранилище**: Локальное хранение артефактов с возможностью управления через UI.
|
||
|
||
### 🛠 Git Интеграция
|
||
- **Version Control**: Возможность версионирования ассетов Superset.
|
||
- **Git Dashboard**: Управление ветками, коммитами и деплоем изменений напрямую из интерфейса.
|
||
- **Conflict Resolution**: Встроенные инструменты для разрешения конфликтов в YAML-конфигурациях.
|
||
|
||
### 🤖 LLM Анализ (AI Plugin)
|
||
- **Автоматический аудит**: Анализ состояния дашбордов на основе скриншотов и метаданных.
|
||
- **Генерация документации**: Автоматическое описание датасетов и колонок с помощью LLM (OpenAI, OpenRouter и др.).
|
||
- **Smart Validation**: Поиск аномалий и ошибок в визуализациях.
|
||
|
||
### 🔐 Безопасность и администрирование
|
||
- **Multi-user Auth**: Многопользовательский доступ с ролевой моделью (RBAC).
|
||
- **Управление подключениями**: Централизованная настройка доступов к различным инстансам Superset.
|
||
- **Логирование**: Подробная история выполнения всех фоновых задач.
|
||
|
||
## Технологический стек
|
||
- **Backend**: Python 3.9+, FastAPI, SQLAlchemy, APScheduler, Pydantic.
|
||
- **Frontend**: Node.js 18+, SvelteKit, Tailwind CSS.
|
||
- **Database**: PostgreSQL (для хранения метаданных, задач, логов и конфигурации).
|
||
|
||
## Структура проекта
|
||
- `backend/` — Серверная часть, API и логика плагинов.
|
||
- `frontend/` — Клиентская часть (SvelteKit приложение).
|
||
- `specs/` — Спецификации функций и планы реализации.
|
||
- `docs/` — Дополнительная документация по маппингу и разработке плагинов.
|
||
|
||
## Быстрый старт
|
||
|
||
### Требования
|
||
- Python 3.9+
|
||
- Node.js 18+
|
||
- Настроенный доступ к API Superset
|
||
|
||
### Запуск
|
||
Для автоматической настройки окружений и запуска обоих серверов (Backend & Frontend) используйте скрипт:
|
||
```bash
|
||
./run.sh
|
||
```
|
||
*Скрипт создаст виртуальное окружение Python, установит зависимости `pip` и `npm`, и запустит сервисы.*
|
||
|
||
Опции:
|
||
- `--skip-install`: Пропустить установку зависимостей.
|
||
- `--help`: Показать справку.
|
||
|
||
Переменные окружения:
|
||
- `BACKEND_PORT`: Порт API (по умолчанию 8000).
|
||
- `FRONTEND_PORT`: Порт UI (по умолчанию 5173).
|
||
- `POSTGRES_URL`: Базовый URL PostgreSQL по умолчанию для всех подсистем.
|
||
- `DATABASE_URL`: URL основной БД (если не задан, используется `POSTGRES_URL`).
|
||
- `TASKS_DATABASE_URL`: URL БД задач/логов (если не задан, используется `DATABASE_URL`).
|
||
- `AUTH_DATABASE_URL`: URL БД авторизации (если не задан, используется PostgreSQL дефолт).
|
||
|
||
## Разработка
|
||
Проект следует строгим правилам разработки:
|
||
1. **Semantic Code Generation**: Использование протокола `.ai/standards/semantics.md` для обеспечения надежности кода.
|
||
2. **Design by Contract (DbC)**: Определение предусловий и постусловий для ключевых функций.
|
||
3. **Constitution**: Соблюдение правил, описанных в конституции проекта в папке `.specify/`.
|
||
|
||
### Полезные команды
|
||
- **Backend**: `cd backend && .venv/bin/python3 -m uvicorn src.app:app --reload`
|
||
- **Frontend**: `cd frontend && npm run dev`
|
||
- **Тесты**: `cd backend && .venv/bin/pytest`
|
||
|
||
## Docker и CI/CD
|
||
### Локальный запуск в Docker (приложение + PostgreSQL)
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
После старта:
|
||
- UI/API: `http://localhost:8000`
|
||
- PostgreSQL: `localhost:5432` (`postgres/postgres`, DB `ss_tools`)
|
||
|
||
Остановить:
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
Полная очистка тома БД:
|
||
```bash
|
||
docker compose down -v
|
||
```
|
||
|
||
Если `postgres:16-alpine` не тянется из Docker Hub (TLS timeout), используйте fallback image:
|
||
```bash
|
||
POSTGRES_IMAGE=mirror.gcr.io/library/postgres:16-alpine docker compose up -d db
|
||
```
|
||
или:
|
||
```bash
|
||
POSTGRES_IMAGE=bitnami/postgresql:latest docker compose up -d db
|
||
```
|
||
Если на хосте уже занят `5432`, поднимайте Postgres на другом порту:
|
||
```bash
|
||
POSTGRES_HOST_PORT=5433 docker compose up -d db
|
||
```
|
||
|
||
### Миграция legacy-данных в PostgreSQL
|
||
Если нужно перенести старые данные из `tasks.db`/`config.json`:
|
||
```bash
|
||
cd backend
|
||
PYTHONPATH=. .venv/bin/python src/scripts/migrate_sqlite_to_postgres.py --sqlite-path tasks.db
|
||
```
|
||
|
||
### CI/CD
|
||
Добавлен workflow: `.github/workflows/ci-cd.yml`
|
||
- backend smoke tests
|
||
- frontend build
|
||
- docker build
|
||
- push образа в GHCR на `main/master`
|
||
|
||
## Контакты и вклад
|
||
Для добавления новых функций или исправления ошибок, пожалуйста, ознакомьтесь с `docs/plugin_dev.md` и создайте соответствующую спецификацию в `specs/`.
|