144 lines
4.1 KiB
Markdown
Executable File
144 lines
4.1 KiB
Markdown
Executable File
# ss-tools
|
||
|
||
Инструменты автоматизации для Apache Superset: миграция, маппинг, хранение артефактов, Git-интеграция, отчеты по задачам и LLM-assistant.
|
||
|
||
## Возможности
|
||
- Миграция дашбордов и датасетов между окружениями.
|
||
- Ручной и полуавтоматический маппинг ресурсов.
|
||
- Логи фоновых задач и отчеты о выполнении.
|
||
- Локальное хранилище файлов и бэкапов.
|
||
- Git-операции по Superset-ассетам через UI.
|
||
- Модуль LLM-анализа и assistant API.
|
||
- Многопользовательская авторизация (RBAC).
|
||
|
||
## Стек
|
||
- Backend: Python, FastAPI, SQLAlchemy, APScheduler.
|
||
- Frontend: SvelteKit, Vite, Tailwind CSS.
|
||
- База данных: PostgreSQL (основная конфигурация), поддержка миграции с legacy SQLite.
|
||
|
||
## Структура репозитория
|
||
- `backend/` — API, плагины, сервисы, скрипты миграции и тесты.
|
||
- `frontend/` — SPA-интерфейс (SvelteKit).
|
||
- `docs/` — документация по архитектуре и плагинам.
|
||
- `specs/` — спецификации и планы реализации.
|
||
- `docker/` и `docker-compose.yml` — контейнеризация.
|
||
|
||
## Быстрый старт (локально)
|
||
|
||
### Требования
|
||
- Python 3.9+
|
||
- Node.js 18+
|
||
- npm
|
||
|
||
### Запуск backend + frontend одним скриптом
|
||
```bash
|
||
./run.sh
|
||
```
|
||
|
||
Что делает `run.sh`:
|
||
- проверяет версии Python/npm;
|
||
- создает `backend/.venv` (если нет);
|
||
- устанавливает `backend/requirements.txt` и `frontend` зависимости;
|
||
- запускает backend и frontend параллельно.
|
||
|
||
Опции:
|
||
- `./run.sh --skip-install` — пропустить установку зависимостей.
|
||
- `./run.sh --help` — показать справку.
|
||
|
||
Переменные окружения для локального запуска:
|
||
- `BACKEND_PORT` (по умолчанию `8000`)
|
||
- `FRONTEND_PORT` (по умолчанию `5173`)
|
||
- `POSTGRES_URL`
|
||
- `DATABASE_URL`
|
||
- `TASKS_DATABASE_URL`
|
||
- `AUTH_DATABASE_URL`
|
||
|
||
## Docker
|
||
|
||
### Запуск
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
После старта сервисы доступны по адресам:
|
||
- Frontend: `http://localhost:8000`
|
||
- Backend API: `http://localhost:8001`
|
||
- PostgreSQL: `localhost:5432` (`postgres/postgres`, БД `ss_tools`)
|
||
|
||
### Остановка
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
### Очистка БД-тома
|
||
```bash
|
||
docker compose down -v
|
||
```
|
||
|
||
### Альтернативный образ PostgreSQL
|
||
Если есть проблемы с pull `postgres:16-alpine`:
|
||
```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` занят:
|
||
```bash
|
||
POSTGRES_HOST_PORT=5433 docker compose up -d db
|
||
```
|
||
|
||
## Разработка
|
||
|
||
### Ручной запуск сервисов
|
||
```bash
|
||
cd backend
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install -r requirements.txt
|
||
python3 -m uvicorn src.app:app --reload --port 8000
|
||
```
|
||
|
||
В другом терминале:
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev -- --port 5173
|
||
```
|
||
|
||
### Тесты
|
||
Backend:
|
||
```bash
|
||
cd backend
|
||
source .venv/bin/activate
|
||
pytest
|
||
```
|
||
|
||
Frontend:
|
||
```bash
|
||
cd frontend
|
||
npm run test
|
||
```
|
||
|
||
## Инициализация auth (опционально)
|
||
```bash
|
||
cd backend
|
||
source .venv/bin/activate
|
||
python src/scripts/init_auth_db.py
|
||
python src/scripts/create_admin.py --username admin --password admin
|
||
```
|
||
|
||
## Миграция legacy-данных (опционально)
|
||
```bash
|
||
cd backend
|
||
source .venv/bin/activate
|
||
PYTHONPATH=. python src/scripts/migrate_sqlite_to_postgres.py --sqlite-path tasks.db
|
||
```
|
||
|
||
## Дополнительная документация
|
||
- `docs/plugin_dev.md`
|
||
- `docs/settings.md`
|
||
- `semantic_protocol.md`
|