busya/ss-tools

Fork 0

Files

busya e62735cc06 docs: refresh business overview and installation guide

2026-07-23 12:33:19 +03:00

18 KiB

Raw Permalink Blame History

Установка и настройка superset-tools

Содержание

Требования
Архитектура
Технологический стек
Docker (рекомендуется)
Локальная разработка
Конфигурация
AI-агент
Система сборки
Тестирование
Покрытие кода
SSL/TLS конфигурация
Enterprise Clean Deployment
Спецификации
Утилиты
Исследования

Требования

Docker (рекомендуется): Docker Engine 24+, Docker Compose v2, 4 GB RAM
Локальная разработка: Python 3.9+, Node.js 18+, npm, 2 GB RAM, 5 GB диска

Архитектура

Проект состоит из трёх сервисов:

Сервис	Технологии	Назначение
backend/	Python FastAPI, SQLAlchemy 2.0, APScheduler, PostgreSQL	REST API, бизнес-логика, плагины
frontend/	Svelte 5 (Runes), SvelteKit, Vite, Tailwind CSS	SPA-клиент
agent/	Gradio, LangGraph, LangChain, OpenAI SDK	AI-агент с чат-интерфейсом
shared/	Python package	Общие утилиты (логирование, SSL, LLM HTTP)

superset-tools/
├── backend/                    # REST API (FastAPI)
│   ├── src/
│   │   ├── api/routes/         # 30+ роутов (admin, auth, translate, git, agent...)
│   │   ├── core/
│   │   │   ├── auth/           # JWT, OAuth, API Keys, RBAC
│   │   │   ├── migration/      # Dry-run, risk assessment
│   │   │   ├── task_manager/   # Async jobs, event bus, persistence
│   │   │   ├── superset_client/
│   │   │   ├── logger/         # Structured logging, belief state
│   │   │   └── ...
│   │   ├── models/             # SQLAlchemy модели
│   │   ├── plugins/            # Реализации плагинов
│   │   ├── schemas/            # Pydantic схемы
│   │   ├── services/           # Бизнес-логика
│   │   └── scripts/            # CLI/TUI админ-скрипты
│   └── tests/
├── frontend/                   # SvelteKit SPA
│   ├── src/
│   │   ├── routes/             # 20+ групп страниц
│   │   ├── lib/
│   │   │   ├── api/            # API клиент
│   │   │   ├── auth/           # Auth store, permissions
│   │   │   ├── components/     # UI компоненты
│   │   │   ├── stores/         # Svelte stores
│   │   │   ├── i18n/           # Мультиязычность
│   │   │   └── ...
│   │   └── ...
│   └── tests/
├── agent/                      # Gradio/LangGraph AI-агент
│   ├── src/ss_tools/agent/
│   │   ├── app.py              # Gradio приложение
│   │   ├── langgraph_setup.py  # LangGraph граф
│   │   ├── tools.py            # LangChain инструменты
│   │   ├── document_parser.py  # PDF/XLSX парсер
│   │   └── ...
│   └── tests/
├── shared/                     # Общий Python пакет (ss-tools-shared)
├── docker/                     # Dockerfile, entrypoint, nginx
├── docs/                       # Документация, ADR
├── specs/                      # 40+ feature specifications
├── scripts/                    # Утилиты (coverage, security, build)
├── research/                   # Исследования (mcp-superset)
├── semantics/                  # Семантическая карта кода
├── dist/                       # Релизные бандлы
├── storage/                    # Runtime данные (backups, repos)
├── certs/                      # SSL-сертификаты
└── examples/                   # Примеры интеграции

Технологический стек

Backend: Python 3.9+ (FastAPI 0.126, SQLAlchemy 2.0, APScheduler 3.11), PostgreSQL 16, Authlib, JWT, OpenAI API, GitPython, Playwright, lingua-language-detector

Frontend: Svelte 5 (Runes), SvelteKit 2.49, Vite 7, Tailwind CSS 3, Vitest 4.1, Playwright 1.60

Agent: Gradio 5.50+, LangChain Core 0.3+, LangGraph 0.2+, LangGraph Checkpoint Postgres, pdfplumber, sentence-transformers (optional)

DevOps: Docker & Docker Compose (3 профиля + E2E), GitHub Actions (CI), Nginx (опциональный SSL)

Docker (рекомендуется)

Профили окружения

Система поддерживает несколько профилей через .env файлы:

Профиль	Файл	Команда
current	`.env.current`	`docker compose --profile current up --build`
master	`.env.master`	`docker compose --profile master up --build`
enterprise-clean	`.env.enterprise-clean`	`docker compose --profile enterprise-clean up --build`
e2e	`.env.e2e`	`docker compose -f docker-compose.e2e.yml up --build`

git clone <repository-url>
cd superset-tools
cp .env.example .env
docker compose --profile current up --build

После запуска:

Frontend: http://localhost:8000
Backend API: http://localhost:8001
PostgreSQL: localhost:5432
Agent UI: http://localhost:8002 (gradio)

Offline-бандл

xz -dc dist/docker/superset-tools.20260517.tar.xz | docker load
export POSTGRES_PASSWORD="my-strong-password"
docker compose -f dist/docker/docker-compose.light.yml up -d

Локальная разработка

Backend

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-backend.txt
pip install -e ../shared
python3 -m uvicorn src.app:app --reload --port 8000

Frontend

cd frontend
npm install
npm run dev -- --port 5173

Agent

cd agent
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e ../shared
python -m ss_tools_agent

Начальная настройка

# Переменные окружения
cp .env.example backend/.env

# Инициализация БД
cd backend && source .venv/bin/activate
python src/scripts/init_auth_db.py

# Создание администратора
python src/scripts/create_admin.py --username admin --password '<temporary-secret>'

Конфигурация

Полный список переменных — в каждом .env.*.example файле.

Основные категории

Категория	Переменные	Описание
Security	`AUTH_SECRET_KEY`, `ENCRYPTION_KEY`, `SERVICE_JWT`	JWT-подпись, шифрование данных, сервисный токен agent→backend
Database	`DATABASE_URL`, `AUTH_DATABASE_URL`, `TASKS_DATABASE_URL`	PostgreSQL подключения
Admin bootstrap	`INITIAL_ADMIN_CREATE`, `INITIAL_ADMIN_USERNAME`, `INITIAL_ADMIN_PASSWORD`, `INITIAL_ADMIN_EMAIL`	Автосоздание admin при первом запуске
LLM	`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `LLM_BASE_URL`, `LLM_MODEL`	Провайдеры и модели
Agent	`AGENT_PORT`, `ENABLE_EMBEDDING_ROUTER`	Порт Gradio, семантический роутинг
Features	`FEATURES__DATASET_REVIEW`, `FEATURES__HEALTH_MONITOR`	Включение фич
SSO	`ADFS_CLIENT_ID`, `ADFS_CLIENT_SECRET`, `ADFS_METADATA_URL`	Active Directory Federation Services
Certificates	`CERTS_PATH`, `SSL_KEY_PASSPHRASE`, `LLM_CA_CERT_URLS`	PKI для корпоративных сетей
CORS	`ALLOWED_ORIGINS`, `FORCE_HTTPS`, `APP_TIMEZONE`	Безопасность и регион
Logging	`ENABLE_BELIEF_STATE_LOGGING`, `TASK_LOG_LEVEL`	Структурированное логирование
Ports	`BACKEND_HOST_PORT`, `FRONTEND_HOST_PORT`, `AGENT_HOST_PORT`, `POSTGRES_HOST_PORT`	Проброс портов Docker

AI-агент

Отдельный сервис с чат-интерфейсом для управления платформой на естественном языке:

LangGraph-граф — оркестрация multi-step диалогов с постгресовой персистентностью
Embedding-роутинг — семантический выбор инструмента (опционально, требует sentence-transformers)
Confirmation flow — подтверждение деструктивных операций
Загрузка документов — парсинг PDF/XLSX для контекстного анализа
Gradio UI — веб-интерфейс

# Docker
docker compose --profile current up agent

# Локально
cd agent && pip install -r requirements.txt && python -m ss_tools_agent

Система сборки

build.sh — унифицированная CLI-утилита:

# Сборка и запуск
./build.sh compose                    # docker compose up --build (current profile)
./build.sh compose:master             # docker compose up (master profile)

# Индивидуальные сборки
./build.sh backend                    # backend image only
./build.sh frontend                   # frontend image only
./build.sh agent                      # agent image only

# Offline-бандлы
./build.sh bundle v1.0.0              # полный бандл (все сервисы)
./build.sh bundle:light v1.0.0        # light (backend + frontend)

Артефакты: dist/docker/superset-tools.<version>.tar.xz + sha256sum + manifest.

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

Makefile (tiered test system)

make test                 # Tier 1: быстрые unit-тесты backend + frontend (<30с)
make test-unit            # Backend unit-тесты с SQLite (без Docker)
make test-frontend        # Frontend vitest-тесты
make test-related F=path  # Tier 2: умный выбор тестов для изменённого файла
make test-integration     # Tier 3: backend integration с testcontainers
make test-e2e             # Tier 3: Playwright E2E (требуется запущенное приложение)
make test-all             # Все тесты (без установки зависимостей)

make lint                 # Все линтеры
make lint-backend         # ruff check
make lint-frontend        # eslint

make coverage             # coverage обоих стеков

Самостоятельный запуск

# Backend тесты
cd backend && source .venv/bin/activate && pytest

# Frontend тесты
cd frontend && npm run test

# Agent тесты
cd agent && source .venv/bin/activate && pytest

# Конкретный тест
pytest backend/tests/test_auth.py::test_create_user

E2E тестирование

docker compose -f docker-compose.e2e.yml up --build
cd frontend && npm run test:e2e

Покрытие кода

Сводный отчёт — scripts/coverage-summary.sh:

./scripts/coverage-summary.sh                          # Полный запуск (integration + frontend)
./scripts/coverage-summary.sh --unit                    # Backend unit (SQLite) + frontend
./scripts/coverage-summary.sh --frontend-only           # Только frontend
./scripts/coverage-summary.sh --backend-only --unit     # Только backend
./scripts/coverage-summary.sh --output-dir ./reports/coverage

Результат: coverage-summary/index.html.

Текущие показатели

Стек	Тип тестов	Процент	Покрытие (Stmts)
Backend (unit)	1723	1721/2 ✅	48%
Backend (integration)	167	167/0 ✅	12%
Frontend	2443	2442/1 ✅	99.25%

SSL/TLS конфигурация

Сертификаты для HTTPS (nginx)

Поместите файлы в ./certs/:

Вариант A — отдельные файлы:

./certs/server.crt   # SSL сертификат
./certs/server.key   # Приватный ключ

Вариант B — зашифрованный ключ + пароль:

./certs/server.crt   # SSL сертификат
./certs/server.key   # Приватный ключ (зашифрован, с DEK-Info)
SSL_KEY_PASSPHRASE=my-passphrase

Вариант C — PKCS#12 контейнер:

./certs/server.p12   # Контейнер с сертификатом + ключом
SSL_KEY_PASSPHRASE=my-passphrase

Entrypoint автоматически извлекает .crt и .key из .p12, расшифровывает ключ и передаёт nginx (ключ остаётся в tmpfs контейнера).

Корпоративные CA-сертификаты

Положите .crt/.pem в ./certs/ — entrypoint установит их в системное хранилище Alpine и NSS (Chromium/Playwright). Поддерживаются цепочки (Root → Intermediate).

LLM CA-сертификаты

LLM_CA_CERT_URLS="http://pki.company.com/root-ca.crt http://pki.company.com/intermediate-ca.crt"

Сертификаты скачиваются на старте backend и agent контейнеров, конвертируются из DER в PEM при необходимости, устанавливаются в системное хранилище.

Диагностика SSL

scripts/check_llm_certs.py                                  # Полная проверка цепочки доверия
scripts/diag_container.py --target your-llm-provider.com:443 # Контейнерная диагностика

Подробнее — ADR-0009. LLM_SSL_VERIFY удалён в 0.2.x — TLS verify всегда включён.

Enterprise Clean Deployment

Разворот в корпоративной сети с очищенным дистрибутивом (без тестовых данных, запрет внешних источников, compliance-проверка):

cp .env.enterprise-clean.example .env
docker compose --profile enterprise-clean up --build

Поддерживаются CLI, API и TUI flows. Подробнее — docs/enterprise-clean.md.

Авторизация

Два метода аутентификации:

Локальная (username/password) — JWT-токены, RBAC (admin/analyst/viewer)
ADFS SSO — Active Directory Federation Services

Управление: POST /api/admin/users, POST /api/admin/roles.

Мониторинг

Dashboard Hub — управление дашбордами с Git-статусом
Dataset Hub — управление датасетами с прогрессом маппинга
Task Drawer — мониторинг фоновых задач (WebSocket real-time)
Unified Reports — GET /api/reports?page=1&page_size=20 (фильтры по статусу, типу, дате)
Health Monitor — мониторинг здоровья системы (через FEATURES__HEALTH_MONITOR)
Semantic Map — автоматически генерируемая семантическая карта кода (semantics/semantic_map.json)

Спецификации

В specs/ ведётся 40+ feature specifications. Каждая включает: spec.md, research.md, plan.md, contracts/modules.md, data-model.md, checklists/requirements.md, tasks.md.

#	Название	Описание
011	`git-integration-dashboard`	Git-интеграция дашбордов
017	`llm-analysis-plugin`	LLM-аналитика и валидация
022	`sync-id-cross-filters`	Sync ID cross-filters
023	`clean-repo-enterprise`	Чистый репозиторий для enterprise
033	`gradio-agent-chat`	Gradio/LangGraph AI-агент
034	`task-status-center`	Центр статуса задач
038	`dashboard-scenario-model`	Сценарная модель дашбордов
041	`dataset-lineage-blast-radius`	Lineage и blast radius датасетов

Примеры скриптов

Примеры интеграции с внешними системами (Airflow, CI/CD, cron) — в examples/:

Python
Bash

Аутентификация через API Key (X-API-Key), запуск и завершение maintenance-событий.

Утилиты

Скрипт	Назначение
`coverage-summary.sh`	Сводный отчёт покрытия
`scan_secrets.sh`	Сканирование секретов
`check_llm_certs.py`	Проверка SSL-сертификатов LLM
`diag_container.py`	SSL-диагностика
`find-related-tests.py`	Поиск тестов по изменённому файлу
`pretty_cot.py`	Форматирование CoT-логов
`gen_semantics.py`	Семантическая карта кода
`build_offline_docker_bundle.sh`	Сборка offline-бандлов

Исследования

mcp-superset — MCP-сервер для Apache Superset (137 инструментов, PyPI). Streamable HTTP, SSE, stdio транспорты. Подробнее — research/mcp-superset/.

18 KiB Raw Permalink Blame History Unescape Escape