docs: refresh business overview and installation guide
This commit is contained in:
419
INSTALL.md
Normal file
419
INSTALL.md
Normal file
@@ -0,0 +1,419 @@
|
||||
# Установка и настройка superset-tools
|
||||
|
||||
## Содержание
|
||||
|
||||
- [Требования](#требования)
|
||||
- [Архитектура](#архитектура)
|
||||
- [Технологический стек](#технологический-стек)
|
||||
- [Docker (рекомендуется)](#docker-рекомендуется)
|
||||
- [Локальная разработка](#локальная-разработка)
|
||||
- [Конфигурация](#конфигурация)
|
||||
- [AI-агент](#ai-агент)
|
||||
- [Система сборки](#система-сборки)
|
||||
- [Тестирование](#тестирование)
|
||||
- [Покрытие кода](#покрытие-кода)
|
||||
- [SSL/TLS конфигурация](#ssltls-конфигурация)
|
||||
- [Enterprise Clean Deployment](#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` |
|
||||
|
||||
```bash
|
||||
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-бандл
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev -- --port 5173
|
||||
```
|
||||
|
||||
### Agent
|
||||
|
||||
```bash
|
||||
cd agent
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
pip install -e ../shared
|
||||
python -m ss_tools_agent
|
||||
```
|
||||
|
||||
### Начальная настройка
|
||||
|
||||
```bash
|
||||
# Переменные окружения
|
||||
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** — веб-интерфейс
|
||||
|
||||
```bash
|
||||
# Docker
|
||||
docker compose --profile current up agent
|
||||
|
||||
# Локально
|
||||
cd agent && pip install -r requirements.txt && python -m ss_tools_agent
|
||||
```
|
||||
|
||||
## Система сборки
|
||||
|
||||
`build.sh` — унифицированная CLI-утилита:
|
||||
|
||||
```bash
|
||||
# Сборка и запуск
|
||||
./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)
|
||||
|
||||
```bash
|
||||
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 обоих стеков
|
||||
```
|
||||
|
||||
### Самостоятельный запуск
|
||||
|
||||
```bash
|
||||
# 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 тестирование
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.e2e.yml up --build
|
||||
cd frontend && npm run test:e2e
|
||||
```
|
||||
|
||||
## Покрытие кода
|
||||
|
||||
Сводный отчёт — `scripts/coverage-summary.sh`:
|
||||
|
||||
```bash
|
||||
./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-сертификаты
|
||||
|
||||
```bash
|
||||
LLM_CA_CERT_URLS="http://pki.company.com/root-ca.crt http://pki.company.com/intermediate-ca.crt"
|
||||
```
|
||||
|
||||
Сертификаты скачиваются на старте backend и agent контейнеров, конвертируются из DER в PEM при необходимости, устанавливаются в системное хранилище.
|
||||
|
||||
### Диагностика SSL
|
||||
|
||||
```bash
|
||||
scripts/check_llm_certs.py # Полная проверка цепочки доверия
|
||||
scripts/diag_container.py --target your-llm-provider.com:443 # Контейнерная диагностика
|
||||
```
|
||||
|
||||
Подробнее — [ADR-0009](docs/adr/ADR-0009-ssl-certificate-management.md).
|
||||
`LLM_SSL_VERIFY` удалён в 0.2.x — TLS verify всегда включён.
|
||||
|
||||
## Enterprise Clean Deployment
|
||||
|
||||
Разворот в корпоративной сети с очищенным дистрибутивом (без тестовых данных, запрет внешних источников, compliance-проверка):
|
||||
|
||||
```bash
|
||||
cp .env.enterprise-clean.example .env
|
||||
docker compose --profile enterprise-clean up --build
|
||||
```
|
||||
|
||||
Поддерживаются CLI, API и TUI flows. Подробнее — [docs/enterprise-clean.md](docs/enterprise-clean.md).
|
||||
|
||||
## Авторизация
|
||||
|
||||
Два метода аутентификации:
|
||||
|
||||
1. **Локальная** (username/password) — JWT-токены, RBAC (admin/analyst/viewer)
|
||||
2. **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/`](./examples/):
|
||||
|
||||
- [Python](examples/maintenance-api-python.py)
|
||||
- [Bash](examples/maintenance-api-bash.sh)
|
||||
|
||||
Аутентификация через 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/`](research/mcp-superset/).
|
||||
466
README.md
466
README.md
@@ -1,369 +1,187 @@
|
||||
# superset-tools
|
||||
|
||||
[](https://www.python.org/)
|
||||
[](https://nodejs.org/)
|
||||
[](LICENSE)
|
||||
[](https://www.docker.com/)
|
||||
|
||||
**Инструменты автоматизации для Apache Superset: миграция, версионирование, аналитика и управление данными**
|
||||
**Корпоративная платформа для управления Apache Superset, перевода данных с помощью LLM и безопасной доставки аналитики между окружениями.**
|
||||
|
||||
## 📋 Содержание
|
||||
superset-tools помогает превратить набор разрозненных дашбордов, ручных переносов и служебных скриптов в управляемый процесс: с версиями, согласованиями, аудитом, фоновым выполнением и AI-ассистентом.
|
||||
|
||||
- [О проекте](#-о-проекте)
|
||||
- [Возможности](#-возможности)
|
||||
- [Архитектура](#-архитектура)
|
||||
- [Быстрый старт](#-быстрый-старт)
|
||||
- [Документация](#-документация)
|
||||
- [Тестирование](#-тестирование)
|
||||
- [Покрытие кода](#-покрытие-кода)
|
||||
- [Enterprise Clean Deployment](#-enterprise-clean-deployment)
|
||||
- [Авторизация](#-авторизация)
|
||||
- [Мониторинг](#-мониторинг)
|
||||
- [Вклад в проект](#-вклад-в-проект)
|
||||
- [Лицензия](#-лицензия)
|
||||
---
|
||||
|
||||
## 📖 О проекте
|
||||
## Когда Superset уже вырос, а процессы вокруг него — ещё нет
|
||||
|
||||
superset-tools — комплексная платформа для автоматизации работы с Apache Superset, предоставляющая инструменты для LLM-перевода контента баз данных, миграции дашбордов, управления версиями через Git, LLM-аналитики и многопользовательского контроля доступа. Система построена на модульной архитектуре с плагинной системой расширений.
|
||||
На старте Apache Superset обычно прост: аналитик создаёт датасет, собирает дашборд и показывает его коллегам. Но по мере роста компании появляются новые окружения, подразделения, языки, требования безопасности и сотни связанных объектов.
|
||||
|
||||
## ✨ Возможности
|
||||
В этот момент команда сталкивается с типичными вопросами:
|
||||
|
||||
### 🌐 LLM-перевод контента баз данных — главная фича
|
||||
- Как перенести дашборд из разработки в production и ничего не сломать?
|
||||
- Как понять, кто изменил отчёт и можно ли вернуть предыдущую версию?
|
||||
- Как перевести сотни тысяч наименований и описаний, сохранив отраслевую терминологию?
|
||||
- Как контролировать длительные операции без постоянного просмотра логов?
|
||||
- Как дать аналитикам свободу, не теряя управляемость и аудит?
|
||||
- Как подключить LLM к внутренним данным, не превращая это в набор несвязанных экспериментов?
|
||||
|
||||
superset-tools умеет переводить данные прямо в вашей БД: сотни тысяч строк номенклатуры, спецификаций, паспортов изделий — за один прогон. Никакой ручной работы, никаких копипаст в Google Translate.
|
||||
superset-tools объединяет эти задачи в одной платформе и делает работу с Superset воспроизводимой, наблюдаемой и безопасной.
|
||||
|
||||
Как это работает: выбираете таблицу-источник, указываете колонки, задаёте целевые языки и LLM-провайдера. superset-tools читает данные, отправляет в LLM и пишет перевод обратно — напрямую в целевую таблицу или через Superset SQL Lab.
|
||||
## Что получает бизнес
|
||||
|
||||
Ключевые возможности модуля:
|
||||
|
||||
- **Multi-language одной LLM-сессией** — одна строка переводится сразу на несколько языков (ru, en, de, fr, zh, kk и любые другие) в одном запросе к LLM. Экономия токенов и времени.
|
||||
- **Любой LLM-провайдер** — Qwen, DeepSeek, GPT-4o, Claude, YandexGPT, GigaChat — всё, что совместимо с OpenAI API. Меняете модель в конфигурации джобы.
|
||||
- **Preview-воркфлоу** — перед полноценным прогоном superset-tools показывает сэмпл перевода. Вы просматриваете строки, правите неудачные варианты, подтверждаете — и только потом запускаете полный прогон.
|
||||
- **Словари терминологии** — загрузите CSV/TSV с правильными переводами ваших доменных терминов: «плавка → melt», «сортопрокат → bar stock», «ТУ → technical specifications». Словари автоматически подмешиваются в промпт, LLM использует именно вашу терминологию.
|
||||
- **Inline-коррекция** — увидели плохой перевод в результатах? Правите прямо в UI, исправление улетает обратно в словарь. Каждый прогон делает систему умнее.
|
||||
- **Инкрементальный перевод** — повторный прогон переводит только новые и изменившиеся строки (сравнение по хешу ключа). Уже переведённое не трогается.
|
||||
- **Автоопределение языка источника** — не нужно указывать, на каком языке исходные данные. superset-tools определяет язык сам (через lingua-language-detector, без LLM — быстро и дёшево).
|
||||
- **Планировщик по cron** — настроили джобу на еженочный прогон? Она будет запускаться автоматически. APScheduler под капотом.
|
||||
- **Cache-механизм** — повторный перевод уже переведённого контента не тратит токены — результаты берутся из кэша.
|
||||
- **Аудит и метрики** — каждый прогон логируется: сколько строк переведено, сколько пропущено, упало, сколько токенов потрачено, сколько результата взято из кэша. Всё в структурированных событиях.
|
||||
- **Bulk-замена** — нашли, что LLM перевёл термин неконсистентно? Bulk find-and-replace по всем записям прогона.
|
||||
|
||||
> **Техническая справка:** модуль перевода — это ~120+ файлов backend на Python, собственная оркестрация (планировщик → executor → batch processor → LLM call), 4 уровня ретраев с адаптивным batch-sizer'ом, async HTTP-клиент для OpenAI API, поддержка Direct SQL (INSERT/UPSERT) и Superset SQL Lab, система промптов с Jaccard-семантикой для подбора словарных статей. Frontend — 5 страниц (джобы, прогоны, словари), 15+ Svelte-компонентов, real-time WebSocket-прогресс.
|
||||
|
||||
### 🔄 Миграция данных без страха
|
||||
|
||||
Перенос дашбордов и датасетов между dev, staging и production — рутинная операция, которая обычно отнимает часы и чревата ошибками. superset-tools делает её предсказуемой:
|
||||
|
||||
- **Dry-run режим** — перед реальными изменениями вы получаете детальный отчёт: какие объекты будут затронуты, какие риски обнаружены, что изменится в целевой среде. Никаких сюрпризов.
|
||||
- **Автоматический маппинг БД** — базы данных, ресурсы и идентификаторы сопоставляются между окружениями автоматически. Никакого ручного поиска и замены.
|
||||
- **Миграция legacy-данных** — встроенная поддержка переноса из SQLite в PostgreSQL. Устаревшие хранилища не помеха.
|
||||
|
||||
### 🌿 Git-интеграция: дашборды как код
|
||||
|
||||
Хватит копировать дашборды через export/import. Включите их в свой Git-процесс:
|
||||
|
||||
- **Версионирование** — каждый дашборд — это файл в репозитории. Полная история изменений, откат на любую версию, diff любой сложности.
|
||||
- **LLM-управление ветками** — создавайте ветки, коммитьте и сливайте изменения через natural language команды. «Создай ветку для эксперимента с отчётом по энергопотреблению и закоммить текущие дашборды».
|
||||
- **Деплой из Git** — push в целевую ветку автоматически применяет изменения на нужном окружении. CI/CD для дашбордов.
|
||||
- **Интеллектуальные сообщения коммитов** — LLM анализирует изменения и сам предлагает осмысленный заголовок коммита.
|
||||
|
||||
### 🤖 LLM-аналитика: ИИ присматривает за дашбордами
|
||||
|
||||
Не просто инструмент, а ваш ассистент по данным:
|
||||
|
||||
- **Автовалидация дашбордов** — LLM проверяет корректность метрик, источников данных и визуализаций. Нашёл подозрительный SQL в фильтре? Сообщит до того, как дашборд попадёт к пользователям.
|
||||
- **Генерация документации** — для любого датасета создаётся человекочитаемое описание: какие поля, откуда данные, какие есть зависимости.
|
||||
- **Assistant API** — управляйте superset-tools голосом или текстом на естественном языке. «Перенеси дашборд производства на staging», «Покажи историю изменений по датасету качества продукции».
|
||||
- **Умный коммитинг** — LLM анализирует изменения и генерирует сообщение коммита, отражающее суть. Никаких «fix» и «update».
|
||||
|
||||
### 📊 Управление и мониторинг: полный контроль
|
||||
|
||||
Одна консоль, чтобы править всеми:
|
||||
|
||||
- **RBAC** — гибкая ролевая модель: admin, analyst, viewer. Каждый видит и делает только то, что ему разрешено.
|
||||
- **Фоновые задачи с WebSocket** — запустили миграцию на час? Откройте Task Drawer и наблюдайте прогресс в реальном времени. Никаких логов, к которым нужно подключаться по SSH.
|
||||
- **Unified Reports** — единый формат отчётов для всех типов задач. Один эндпоинт — любые данные.
|
||||
- **Аудит** — каждое действие логируется. Кто, когда и что сделал — всегда можно выяснить.
|
||||
- **Retention-политики** — артефакты автоматически очищаются по расписанию. Диски не забиваются.
|
||||
|
||||
### 🔌 Плагинная архитектура: расширяйте без границ
|
||||
|
||||
superset-tools спроектирован как платформа. Хотите свою логику миграции? Свой источник данных? Свой триггер?
|
||||
|
||||
Каждый модуль — это изолированный плагин:
|
||||
|
||||
| Плагин | Назначение |
|
||||
| Результат | Как достигается |
|
||||
|---|---|
|
||||
| **TranslatePlugin** | LLM-перевод контента БД |
|
||||
| **MigrationPlugin** | Миграция дашбордов между окружениями |
|
||||
| **BackupPlugin** | Резервное копирование и восстановление |
|
||||
| **GitPlugin** | Полный цикл Git-операций |
|
||||
| **LLMAnalysisPlugin** | AI-валидация и генерация документации |
|
||||
| **MapperPlugin** | Маппинг колонок и ресурсов |
|
||||
| **DebugPlugin** | Диагностика и профилирование системы |
|
||||
| **SearchPlugin** | Полнотекстовый поиск по датасетам |
|
||||
| **Быстрый выпуск многоязычной отчётности** | Массовый LLM-перевод данных с корпоративными словарями и предварительной проверкой |
|
||||
| **Меньше ошибок при релизах** | Dry-run перед миграцией показывает изменения и риски до применения |
|
||||
| **Прозрачная история изменений** | Дашборды и связанные объекты версионируются через Git |
|
||||
| **Снижение ручной работы** | Повторяемые операции запускаются из интерфейса, по расписанию или через API |
|
||||
| **Контроль длительных процессов** | Прогресс, результаты и ошибки доступны в реальном времени |
|
||||
| **Управляемое использование AI** | Единые LLM-провайдеры, словари, аудит и подтверждение критических действий |
|
||||
| **Готовность к корпоративной среде** | Ролевая модель, ADFS SSO, аудит и поддержка закрытых контуров |
|
||||
|
||||
Пишите свои плагины, подключайте через простой Python API. Никакой магии — только чёткий контракт.
|
||||
## Ключевые сценарии
|
||||
|
||||
## 🏗️ Архитектура
|
||||
### Перевод корпоративных данных без ручной обработки
|
||||
|
||||
### Технологический стек
|
||||
Представьте каталог из 300 000 позиций: наименования продукции, технические характеристики, марки материалов и примечания. Отчётность нужно подготовить на английском, немецком и китайском языках, при этом терминология должна соответствовать внутренним стандартам компании.
|
||||
|
||||
**Backend:** Python 3.9+ (FastAPI, SQLAlchemy, APScheduler), PostgreSQL, GitPython, OpenAI API, Playwright
|
||||
В superset-tools команда выбирает источник, нужные поля и языки, подключает терминологический словарь и сначала получает небольшую выборку для проверки. После согласования система запускает полный перевод, сохраняет результат и формирует отчёт о выполнении.
|
||||
|
||||
**Frontend:** SvelteKit (Svelte 5.x), Vite, Tailwind CSS, WebSocket
|
||||
При следующем запуске переводятся только новые и изменившиеся записи. Уже обработанные данные и подтверждённые формулировки используются повторно, поэтому процесс становится быстрее и экономичнее.
|
||||
|
||||
**DevOps:** Docker & Docker Compose, PostgreSQL 16
|
||||
**Что поддерживается:**
|
||||
|
||||
### Модульная структура
|
||||
- несколько целевых языков за один проход;
|
||||
- OpenAI-совместимые модели и корпоративные LLM-шлюзы;
|
||||
- отраслевые словари из CSV/TSV;
|
||||
- предварительный просмотр результата;
|
||||
- исправление переводов прямо в интерфейсе;
|
||||
- инкрементальная обработка новых данных;
|
||||
- плановые запуски по расписанию;
|
||||
- статистика по строкам, ошибкам, кэшу и расходу токенов;
|
||||
- массовая корректировка неконсистентных терминов.
|
||||
|
||||
```
|
||||
superset-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/ # Спецификации
|
||||
```
|
||||
### Безопасная миграция между dev, staging и production
|
||||
|
||||
## 🚀 Быстрый старт
|
||||
Ручной export/import плохо масштабируется: идентификаторы отличаются, подключения к БД называются по-разному, а последствия становятся видны только после релиза.
|
||||
|
||||
### Требования
|
||||
superset-tools сначала выполняет dry-run и показывает, какие объекты будут созданы или изменены, какие зависимости найдены и где есть риски. Только после проверки команда запускает реальную миграцию.
|
||||
|
||||
- **Docker (рекомендуется):** Docker Engine 24+, Docker Compose v2, 4 GB RAM
|
||||
- **Локальная разработка:** Python 3.9+, Node.js 18+, npm, 2 GB RAM, 5 GB диска
|
||||
Автоматический маппинг помогает сопоставить базы данных и ресурсы между окружениями, а единый отчёт сохраняет результат операции для последующего аудита.
|
||||
|
||||
### Docker (рекомендуется)
|
||||
**Бизнес-эффект:** меньше аварийных исправлений, быстрее выпуск изменений и понятная процедура согласования релиза.
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd superset-tools
|
||||
docker compose up --build
|
||||
```
|
||||
### Дашборды как управляемые цифровые активы
|
||||
|
||||
После запуска:
|
||||
- Frontend: http://localhost:8000
|
||||
- Backend API: http://localhost:8001
|
||||
- PostgreSQL: localhost:5432
|
||||
Дашборд — это не просто экран с графиками. В нём зафиксированы бизнес-метрики, SQL-логика, фильтры и договорённости между подразделениями. Поэтому его изменения должны быть такими же прозрачными, как изменения программного кода.
|
||||
|
||||
### Локальная разработка
|
||||
Git-интеграция superset-tools позволяет:
|
||||
|
||||
```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
|
||||
- хранить историю версий;
|
||||
- сравнивать изменения;
|
||||
- возвращаться к стабильному состоянию;
|
||||
- разделять экспериментальную и промышленную работу по веткам;
|
||||
- доставлять согласованные изменения в целевое окружение;
|
||||
- генерировать понятные сообщения коммитов с помощью LLM.
|
||||
|
||||
# Frontend (в новом терминале)
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev -- --port 5173
|
||||
```
|
||||
В результате команда получает единый процесс для аналитики и разработки, а ключевые отчёты перестают зависеть от памяти отдельных сотрудников.
|
||||
|
||||
### Начальная настройка
|
||||
### AI-ассистент для повседневных операций
|
||||
|
||||
```bash
|
||||
# Переменные окружения
|
||||
cp .env.example backend/.env
|
||||
Платформой можно управлять через чат на естественном языке. Пользователь формулирует задачу так, как привык обсуждать её с коллегами:
|
||||
|
||||
# Инициализация БД
|
||||
cd backend && source .venv/bin/activate
|
||||
python src/scripts/init_auth_db.py
|
||||
> «Проверь дашборд производства перед публикацией»
|
||||
>
|
||||
> «Покажи последние изменения в отчёте по качеству»
|
||||
>
|
||||
> «Подготовь перенос дашборда на staging и сначала покажи риски»
|
||||
>
|
||||
> «Проанализируй загруженную спецификацию и найди связанные датасеты»
|
||||
|
||||
# Создание администратора
|
||||
python src/scripts/create_admin.py --username admin --password '<temporary-secret>'
|
||||
```
|
||||
AI-агент сохраняет контекст диалога, умеет работать с PDF и XLSX и запрашивает подтверждение перед критическими действиями. Это не отдельный демонстрационный чат, а дополнительный интерфейс к реальным операциям платформы.
|
||||
|
||||
> Полный каталог переменных окружения — в [`.env.example`](.env.example).
|
||||
### Единый центр контроля
|
||||
|
||||
### Offline-бандл
|
||||
Все длительные процессы — перевод, миграция, резервное копирование, анализ и Git-операции — выполняются как управляемые фоновые задачи.
|
||||
|
||||
```bash
|
||||
# Загрузка образа
|
||||
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
|
||||
```
|
||||
Пользователь видит:
|
||||
|
||||
Сборка бандла: `./build.sh bundle:light v1.0.0` (light, ~104 MB) или `./build.sh bundle v1.0.0` (full).
|
||||
- текущий статус и прогресс;
|
||||
- этап, на котором находится операция;
|
||||
- предупреждения и ошибки;
|
||||
- итоговый отчёт;
|
||||
- историю запусков;
|
||||
- автора и время действия.
|
||||
|
||||
## 📖 Документация
|
||||
Администратору не нужно подключаться к серверу и искать нужный фрагмент лога, а бизнес-пользователь не остаётся перед бесконечным индикатором загрузки.
|
||||
|
||||
- [Установка и настройка](docs/installation.md)
|
||||
## Кому подходит superset-tools
|
||||
|
||||
### BI-командам
|
||||
|
||||
Для управления большим количеством дашбордов и датасетов, выпуска изменений между окружениями и подготовки многоязычной отчётности.
|
||||
|
||||
### Аналитикам данных
|
||||
|
||||
Для запуска типовых операций из единого интерфейса, отслеживания результатов и работы с AI без необходимости писать служебные скрипты.
|
||||
|
||||
### DevOps и платформенным инженерам
|
||||
|
||||
Для воспроизводимых поставок, Git-процессов, интеграции с CI/CD, фоновых задач и развёртывания в закрытом контуре.
|
||||
|
||||
### Руководителям ИТ, BI и DWH
|
||||
|
||||
Для прозрачности процессов, разграничения доступа, истории изменений и снижения зависимости от ручных действий отдельных специалистов.
|
||||
|
||||
### Командам локализации и управления данными
|
||||
|
||||
Для массового перевода справочников и технического контента с контролем терминологии и качества результата.
|
||||
|
||||
## Чем платформа отличается от набора скриптов
|
||||
|
||||
Скрипт хорошо решает одну задачу один раз. Корпоративный процесс должен переживать рост объёмов, смену сотрудников, ошибки внешних систем и новые требования безопасности.
|
||||
|
||||
superset-tools добавляет вокруг операций необходимый управленческий контур:
|
||||
|
||||
- единый пользовательский интерфейс;
|
||||
- роли и права доступа;
|
||||
- предварительную проверку изменений;
|
||||
- фоновые задачи и повторные попытки;
|
||||
- историю и аудит;
|
||||
- отчёты в едином формате;
|
||||
- расписания и retention-политики;
|
||||
- API для внешних систем;
|
||||
- расширение через плагины.
|
||||
|
||||
## Корпоративное использование
|
||||
|
||||
Платформа рассчитана как на обычное Docker-развёртывание, так и на изолированные корпоративные сети.
|
||||
|
||||
Поддерживаются:
|
||||
|
||||
- локальная авторизация и ADFS SSO;
|
||||
- роли `admin`, `analyst` и `viewer`;
|
||||
- корпоративные CA-сертификаты;
|
||||
- собственные LLM-шлюзы и OpenAI-совместимые API;
|
||||
- развёртывание без доступа к внешним источникам;
|
||||
- очищенные enterprise-дистрибутивы;
|
||||
- журналирование действий и результатов операций.
|
||||
|
||||
## Как устроен продукт
|
||||
|
||||
Пользователь работает с единой веб-платформой, которая объединяет управление дашбордами, датасетами, миграциями, переводами, Git-репозиториями и фоновыми задачами. AI-агент предоставляет альтернативный диалоговый интерфейс, а API позволяет подключать CI/CD, Airflow, cron и внутренние корпоративные системы.
|
||||
|
||||
Архитектура модульная: стандартные возможности реализованы как плагины, поэтому платформу можно расширять под собственные источники данных и бизнес-процессы.
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
Инструкции по Docker-развёртыванию, локальной разработке, настройке LLM, SSO, сертификатов и закрытого контура находятся в [INSTALL.md](INSTALL.md).
|
||||
|
||||
## Документация
|
||||
|
||||
- [Установка и настройка](INSTALL.md)
|
||||
- [Архитектура системы](docs/architecture.md)
|
||||
- [Архитектурные решения (ADR)](docs/adr/README.md)
|
||||
- [API документация](http://localhost:8001/docs)
|
||||
- [Настройка окружений](docs/settings.md)
|
||||
- [Архитектурные решения](docs/adr/README.md)
|
||||
- [Enterprise Clean Deployment](docs/enterprise-clean.md)
|
||||
- [API после запуска](http://localhost:8001/docs)
|
||||
- [Руководство для контрибьюторов](CONTRIBUTING.md)
|
||||
|
||||
## 🧪 Тестирование
|
||||
|
||||
### Запуск тестов
|
||||
|
||||
```bash
|
||||
# Backend тесты
|
||||
cd backend && source .venv/bin/activate && pytest
|
||||
|
||||
# Frontend тесты
|
||||
cd frontend && npm run test
|
||||
|
||||
# Конкретный тест
|
||||
pytest tests/test_auth.py::test_create_user
|
||||
```
|
||||
|
||||
### 📊 Покрытие кода
|
||||
|
||||
Сводный отчёт о покрытии генерируется скриптом `scripts/coverage-summary.sh`:
|
||||
|
||||
```bash
|
||||
# Полный запуск (backend integration + frontend)
|
||||
./scripts/coverage-summary.sh
|
||||
|
||||
# Backend unit-тесты (SQLite) + frontend (быстрее, не требует Docker)
|
||||
./scripts/coverage-summary.sh --unit
|
||||
|
||||
# Только frontend
|
||||
./scripts/coverage-summary.sh --frontend-only
|
||||
|
||||
# Только backend unit
|
||||
./scripts/coverage-summary.sh --backend-only --unit
|
||||
|
||||
# Указать директорию для отчёта
|
||||
./scripts/coverage-summary.sh --output-dir ./reports/coverage
|
||||
```
|
||||
|
||||
Скрипт выполняет:
|
||||
1. Запуск backend-тестов (pytest) с `--cov=src` — unit (`--unit`) или integration (`--run-integration`)
|
||||
2. Запуск frontend-тестов (vitest) с `--coverage`
|
||||
3. Парсинг результатов тестов и процентов покрытия
|
||||
4. Генерацию единого HTML-отчёта в `coverage-summary/index.html` со сводкой по обоим стекам
|
||||
|
||||
**Текущие показатели:**
|
||||
|
||||
| Стек | Тип тестов | Процент | Покрытие (Stmts) |
|
||||
|------|-----------|---------|------------------|
|
||||
| Backend (unit) | 1723 | 1721/2 ✅ | 48% |
|
||||
| Backend (integration) | 167 | 167/0 ✅ | 12% |
|
||||
| Frontend | 2443 | 2442/1 ✅ | 99.25% |
|
||||
|
||||
> HTML-отчёты coverage по каждому стеку открываются из сводного отчёта по ссылкам.
|
||||
|
||||
## 🔐 SSL/TLS конфигурация
|
||||
|
||||
### Сертификаты для HTTPS (nginx)
|
||||
|
||||
Для включения HTTPS поместите файлы сертификатов в директорию `./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 автоматически:
|
||||
1. Извлечёт `.crt` и `.key` из `.p12` (если нет отдельных файлов)
|
||||
2. Расшифрует приватный ключ через `openssl rsa` (если есть `SSL_KEY_PASSPHRASE`)
|
||||
3. Передаст расшифрованный ключ nginx (ключ остаётся в tmpfs контейнера)
|
||||
|
||||
> **Безопасность:** Расшифрованный ключ хранится только в tmpfs `/etc/nginx/ssl/` внутри контейнера и не пишется на диск хоста. Пароль задаётся через переменную окружения, а не через файл на volume.
|
||||
|
||||
### Корпоративные CA-сертификаты
|
||||
|
||||
Положите `.crt`/`.pem` файлы в `./certs/` — entrypoint установит их в системное хранилище Alpine и NSS (Chromium/Playwright). Поддерживаются цепочки из нескольких CA (Root → Intermediate).
|
||||
|
||||
### LLM CA-сертификаты
|
||||
|
||||
Если LLM-провайдер или Superset используют корпоративный PKI — укажите HTTP URL для скачивания CA-сертификатов:
|
||||
```bash
|
||||
LLM_CA_CERT_URLS="http://pki.company.com/root-ca.crt http://pki.company.com/intermediate-ca.crt"
|
||||
```
|
||||
Сертификаты скачиваются на старте backend и agent контейнеров (через `certs.sh:download_llm_ca_certs()`), конвертируются из DER в PEM при необходимости, и устанавливаются в системное хранилище.
|
||||
|
||||
Дополнительные сертификаты можно разместить в `CERTS_PATH=./certs` (volume mount).
|
||||
|
||||
### Диагностика SSL
|
||||
|
||||
```bash
|
||||
# Полная проверка цепочки доверия
|
||||
scripts/check_llm_certs.py
|
||||
|
||||
# Контейнерная диагностика
|
||||
scripts/diag_container.py --target your-llm-provider.com:443
|
||||
```
|
||||
|
||||
Подробнее — в [ADR-0009](docs/adr/ADR-0009-ssl-certificate-management.md).
|
||||
`LLM_SSL_VERIFY` удалён в 0.2.x — TLS verify всегда включён.
|
||||
|
||||
## 🏢 Enterprise Clean Deployment
|
||||
|
||||
Для разворота в корпоративной сети с очищенным дистрибутивом (без тестовых данных, с запретом внешних источников и обязательной compliance-проверкой) используется профиль **enterprise clean**.
|
||||
|
||||
Поддерживаются CLI, API и TUI flows. Подробная документация — в [docs/enterprise-clean.md](docs/enterprise-clean.md).
|
||||
|
||||
## 🔐 Авторизация
|
||||
|
||||
Система поддерживает два метода аутентификации:
|
||||
|
||||
1. **Локальная** (username/password)
|
||||
2. **ADFS SSO** (Active Directory Federation Services)
|
||||
|
||||
Управление пользователями и ролями — через `POST /api/admin/users` и `POST /api/admin/roles`. Документация — `docs/installation.md`.
|
||||
|
||||
## 📊 Мониторинг
|
||||
|
||||
- **Dashboard Hub** — управление дашбордами с Git-статусом
|
||||
- **Dataset Hub** — управление датасетами с прогрессом маппинга
|
||||
- **Task Drawer** — мониторинг выполнения фоновых задач
|
||||
- **Unified Reports** — унифицированные отчеты по всем типам задач
|
||||
|
||||
API: `GET /api/reports?page=1&page_size=20` (фильтры по статусу, типу, дате).
|
||||
|
||||
## 💻 Примеры скриптов
|
||||
|
||||
Примеры интеграции с внешними системами (Airflow, CI/CD, cron) — в [`examples/`](./examples/):
|
||||
|
||||
- [Python](examples/maintenance-api-python.py)
|
||||
- [Bash](examples/maintenance-api-bash.sh)
|
||||
|
||||
Скрипты демонстрируют аутентификацию через API Key (`X-API-Key`), запуск и завершение maintenance-событий, обработку ошибок.
|
||||
|
||||
## 🤝 Вклад в проект
|
||||
|
||||
Мы приветствуем contributions! См. [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
|
||||
## 📄 Лицензия
|
||||
## Лицензия
|
||||
|
||||
Проект распространяется под лицензией [MIT](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user