busya
320f82ab95
Introduce a new API key authentication mechanism to support service-to-service communication (e.g., Airflow, CI/CD) without browser-based JWT login. - Add `APIKey` model and `APIKeyPrincipal` dependency for RBAC. - Implement `require_api_key_or_jwt` dependency with environment scoping. - Add admin CRUD endpoints for API key lifecycle management. - Add API key management UI in System Settings. - Update maintenance API to support explicit `environment_id` and API key auth. - Add i18n support for API keys and connection settings. - Include Python and Bash usage examples in the `examples/` directory. - Update technical specifications and documentation.
450 lines
18 KiB
Markdown
Executable File
450 lines
18 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 (для стабильной работы)
|
||
|
||
### Быстрое развертывание бандла (offline)
|
||
|
||
```bash
|
||
# 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>'
|
||
```
|
||
|
||
Команды для сборки бандла:
|
||
```bash
|
||
# Легковесный all-in-one (~104 MB)
|
||
./build.sh bundle:light v1.0.0
|
||
|
||
# Полный релиз (backend + frontend + postgres)
|
||
./build.sh bundle v1.0.0
|
||
```
|
||
|
||
### Установка и запуск
|
||
|
||
#### Вариант 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
|
||
# Скопируйте шаблон переменных окружения
|
||
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`](.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)
|
||
|
||
```bash
|
||
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)
|
||
|
||
```bash
|
||
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 для такого релиза:
|
||
|
||
```bash
|
||
# 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):
|
||
|
||
```bash
|
||
# Сборка
|
||
./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`](backend/src/scripts/create_admin.py) перед стартом API;
|
||
- если администратор уже существует, учётная запись не меняется;
|
||
- теги в [`.env.enterprise-clean.example`](.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.
|
||
|
||
## 📖 Документация
|
||
|
||
- [Установка и настройка](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
|
||
```
|
||
|
||
## 💻 Примеры скриптов
|
||
|
||
Примеры Python и Bash скриптов для вызова API ss-tools из внешних систем (Airflow, CI/CD, cron) находятся в каталоге [`examples/`](./examples/).
|
||
|
||
- **Python** — [`examples/maintenance-api-python.py`](./examples/maintenance-api-python.py)
|
||
- **Bash** — [`examples/maintenance-api-bash.sh`](./examples/maintenance-api-bash.sh)
|
||
|
||
Скрипты демонстрируют аутентификацию через API Key (`X-API-Key`), запуск и завершение maintenance-событий, а также обработку ошибок.
|