docs(README): переработка структуры, добавлен LICENSE (MIT) и CONTRIBUTING
- README сокращён с 449 до ~200 строк - Добавлены бейджи (Python, Node, Docker, лицензия) и оглавление - Раздел возможностей — акцент на LLM-перевод контента БД как главную фичу - Enterprise Clean вынесен в docs/enterprise-clean.md - Авторизация, мониторинг, обновление — сокращены до минимума - Создан LICENSE (MIT) - Создан CONTRIBUTING.md - Примеры переведены в промышленный контекст
This commit is contained in:
490
README.md
490
README.md
@@ -1,67 +1,118 @@
|
||||
# ss-tools
|
||||
|
||||
[](https://www.python.org/)
|
||||
[](https://nodejs.org/)
|
||||
[](LICENSE)
|
||||
[](https://www.docker.com/)
|
||||
|
||||
**Инструменты автоматизации для Apache Superset: миграция, версионирование, аналитика и управление данными**
|
||||
|
||||
## 📋 О проекте
|
||||
## 📋 Содержание
|
||||
|
||||
ss-tools — это комплексная платформа для автоматизации работы с Apache Superset, предоставляющая инструменты для миграции дашбордов, управления версиями через Git, LLM-анализа данных и многопользовательского контроля доступа. Система построена на модульной архитектуре с плагинной системой расширений.
|
||||
- [О проекте](#-о-проекте)
|
||||
- [Возможности](#-возможности)
|
||||
- [Архитектура](#-архитектура)
|
||||
- [Быстрый старт](#-быстрый-старт)
|
||||
- [Документация](#-документация)
|
||||
- [Тестирование](#-тестирование)
|
||||
- [Enterprise Clean Deployment](#-enterprise-clean-deployment)
|
||||
- [Авторизация](#-авторизация)
|
||||
- [Мониторинг](#-мониторинг)
|
||||
- [Вклад в проект](#-вклад-в-проект)
|
||||
- [Лицензия](#-лицензия)
|
||||
|
||||
### 🎯 Ключевые возможности
|
||||
## 📖 О проекте
|
||||
|
||||
#### 🔄 Миграция данных
|
||||
- **Миграция дашбордов и датасетов** между окружениями (dev/staging/prod)
|
||||
- **Dry-run режим** с детальным анализом рисков и предпросмотром изменений
|
||||
- **Автоматическое маппинг** баз данных и ресурсов между окружениями
|
||||
- **Поддержка legacy-данных** с миграцией из SQLite в PostgreSQL
|
||||
ss-tools — комплексная платформа для автоматизации работы с Apache Superset, предоставляющая инструменты для LLM-перевода контента баз данных, миграции дашбордов, управления версиями через Git, LLM-аналитики и многопользовательского контроля доступа. Система построена на модульной архитектуре с плагинной системой расширений.
|
||||
|
||||
#### 🌿 Git-интеграция
|
||||
- **Версионирование** дашбордов через Git-репозитории
|
||||
- **Управление ветками** и коммитами с помощью LLM
|
||||
- **Деплой** дашбордов из Git в целевые окружения
|
||||
- **История изменений** с детальным diff
|
||||
## ✨ Возможности
|
||||
|
||||
#### 🤖 LLM-аналитика
|
||||
- **Автоматическая валидация** дашбордов с помощью ИИ
|
||||
- **Генерация документации** для датасетов
|
||||
- **Assistant API** для natural language команд
|
||||
- **Интеллектуальное коммитинг** с подсказками сообщений
|
||||
### 🌐 LLM-перевод контента баз данных — главная фича
|
||||
|
||||
#### 📊 Управление и мониторинг
|
||||
- **Многопользовательская авторизация** (RBAC)
|
||||
- **Фоновые задачи** с реальным логированием через WebSocket
|
||||
- **Унифицированные отчеты** по выполненным задачам
|
||||
- **Хранение артефактов** с политиками retention
|
||||
- **Аудит логирование** всех действий
|
||||
ss-tools умеет переводить данные прямо в вашей БД: сотни тысяч строк номенклатуры, спецификаций, паспортов изделий — за один прогон. Никакой ручной работы, никаких копипаст в Google Translate.
|
||||
|
||||
#### 🔌 Плагины
|
||||
- **MigrationPlugin** — миграция дашбордов
|
||||
- **BackupPlugin** — резервное копирование
|
||||
- **GitPlugin** — управление версиями
|
||||
- **LLMAnalysisPlugin** — аналитика и документация
|
||||
- **MapperPlugin** — маппинг колонок
|
||||
- **DebugPlugin** — диагностика системы
|
||||
- **SearchPlugin** — поиск по датасетам
|
||||
Как это работает: выбираете таблицу-источник, указываете колонки, задаёте целевые языки и LLM-провайдера. ss-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-воркфлоу** — перед полноценным прогоном ss-tools показывает сэмпл перевода. Вы просматриваете строки, правите неудачные варианты, подтверждаете — и только потом запускаете полный прогон.
|
||||
- **Словари терминологии** — загрузите CSV/TSV с правильными переводами ваших доменных терминов: «плавка → melt», «сортопрокат → bar stock», «ТУ → technical specifications». Словари автоматически подмешиваются в промпт, LLM использует именно вашу терминологию.
|
||||
- **Inline-коррекция** — увидели плохой перевод в результатах? Правите прямо в UI, исправление улетает обратно в словарь. Каждый прогон делает систему умнее.
|
||||
- **Инкрементальный перевод** — повторный прогон переводит только новые и изменившиеся строки (сравнение по хешу ключа). Уже переведённое не трогается.
|
||||
- **Автоопределение языка источника** — не нужно указывать, на каком языке исходные данные. ss-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 — рутинная операция, которая обычно отнимает часы и чревата ошибками. ss-tools делает её предсказуемой:
|
||||
|
||||
- **Dry-run режим** — перед реальными изменениями вы получаете детальный отчёт: какие объекты будут затронуты, какие риски обнаружены, что изменится в целевой среде. Никаких сюрпризов.
|
||||
- **Автоматический маппинг БД** — базы данных, ресурсы и идентификаторы сопоставляются между окружениями автоматически. Никакого ручного поиска и замены.
|
||||
- **Миграция legacy-данных** — встроенная поддержка переноса из SQLite в PostgreSQL. Устаревшие хранилища не помеха.
|
||||
|
||||
### 🌿 Git-интеграция: дашборды как код
|
||||
|
||||
Хватит копировать дашборды через export/import. Включите их в свой Git-процесс:
|
||||
|
||||
- **Версионирование** — каждый дашборд — это файл в репозитории. Полная история изменений, откат на любую версию, diff любой сложности.
|
||||
- **LLM-управление ветками** — создавайте ветки, коммитьте и сливайте изменения через natural language команды. «Создай ветку для эксперимента с отчётом по энергопотреблению и закоммить текущие дашборды».
|
||||
- **Деплой из Git** — push в целевую ветку автоматически применяет изменения на нужном окружении. CI/CD для дашбордов.
|
||||
- **Интеллектуальные сообщения коммитов** — LLM анализирует изменения и сам предлагает осмысленный заголовок коммита.
|
||||
|
||||
### 🤖 LLM-аналитика: ИИ присматривает за дашбордами
|
||||
|
||||
Не просто инструмент, а ваш ассистент по данным:
|
||||
|
||||
- **Автовалидация дашбордов** — LLM проверяет корректность метрик, источников данных и визуализаций. Нашёл подозрительный SQL в фильтре? Сообщит до того, как дашборд попадёт к пользователям.
|
||||
- **Генерация документации** — для любого датасета создаётся человекочитаемое описание: какие поля, откуда данные, какие есть зависимости.
|
||||
- **Assistant API** — управляйте ss-tools голосом или текстом на естественном языке. «Перенеси дашборд производства на staging», «Покажи историю изменений по датасету качества продукции».
|
||||
- **Умный коммитинг** — LLM анализирует изменения и генерирует сообщение коммита, отражающее суть. Никаких «fix» и «update».
|
||||
|
||||
### 📊 Управление и мониторинг: полный контроль
|
||||
|
||||
Одна консоль, чтобы править всеми:
|
||||
|
||||
- **RBAC** — гибкая ролевая модель: admin, analyst, viewer. Каждый видит и делает только то, что ему разрешено.
|
||||
- **Фоновые задачи с WebSocket** — запустили миграцию на час? Откройте Task Drawer и наблюдайте прогресс в реальном времени. Никаких логов, к которым нужно подключаться по SSH.
|
||||
- **Unified Reports** — единый формат отчётов для всех типов задач. Один эндпоинт — любые данные.
|
||||
- **Аудит** — каждое действие логируется. Кто, когда и что сделал — всегда можно выяснить.
|
||||
- **Retention-политики** — артефакты автоматически очищаются по расписанию. Диски не забиваются.
|
||||
|
||||
### 🔌 Плагинная архитектура: расширяйте без границ
|
||||
|
||||
ss-tools спроектирован как платформа. Хотите свою логику миграции? Свой источник данных? Свой триггер?
|
||||
|
||||
Каждый модуль — это изолированный плагин:
|
||||
|
||||
| Плагин | Назначение |
|
||||
|---|---|
|
||||
| **TranslatePlugin** | LLM-перевод контента БД |
|
||||
| **MigrationPlugin** | Миграция дашбордов между окружениями |
|
||||
| **BackupPlugin** | Резервное копирование и восстановление |
|
||||
| **GitPlugin** | Полный цикл Git-операций |
|
||||
| **LLMAnalysisPlugin** | AI-валидация и генерация документации |
|
||||
| **MapperPlugin** | Маппинг колонок и ресурсов |
|
||||
| **DebugPlugin** | Диагностика и профилирование системы |
|
||||
| **SearchPlugin** | Полнотекстовый поиск по датасетам |
|
||||
|
||||
Пишите свои плагины, подключайте через простой Python API. Никакой магии — только чёткий контракт.
|
||||
|
||||
## 🏗️ Архитектура
|
||||
|
||||
### Технологический стек
|
||||
|
||||
**Backend:**
|
||||
- Python 3.9+ (FastAPI, SQLAlchemy, APScheduler)
|
||||
- PostgreSQL (основная БД)
|
||||
- GitPython для Git-операций
|
||||
- OpenAI API для LLM-функций
|
||||
- Playwright для скриншотов
|
||||
**Backend:** Python 3.9+ (FastAPI, SQLAlchemy, APScheduler), PostgreSQL, GitPython, OpenAI API, Playwright
|
||||
|
||||
**Frontend:**
|
||||
- SvelteKit (Svelte 5.x)
|
||||
- Vite
|
||||
- Tailwind CSS
|
||||
- WebSocket для реального логирования
|
||||
**Frontend:** SvelteKit (Svelte 5.x), Vite, Tailwind CSS, WebSocket
|
||||
|
||||
**DevOps:**
|
||||
- Docker & Docker Compose
|
||||
- PostgreSQL 16
|
||||
**DevOps:** Docker & Docker Compose, PostgreSQL 16
|
||||
|
||||
### Модульная структура
|
||||
|
||||
@@ -69,24 +120,24 @@ ss-tools — это комплексная платформа для автом
|
||||
ss-tools/
|
||||
├── backend/ # Backend API
|
||||
│ ├── src/
|
||||
│ │ ├── api/ # API маршруты
|
||||
│ │ ├── core/ # Ядро системы
|
||||
│ │ │ ├── task_manager/ # Управление задачами
|
||||
│ │ │ ├── auth/ # Авторизация
|
||||
│ │ │ ├── migration/ # Миграция данных
|
||||
│ │ │ └── plugins/ # Плагины
|
||||
│ │ ├── models/ # Модели данных
|
||||
│ │ ├── services/ # Бизнес-логика
|
||||
│ │ └── schemas/ # Pydantic схемы
|
||||
│ └── tests/ # Тесты
|
||||
│ │ ├── api/ # API маршруты
|
||||
│ │ ├── core/ # Ядро системы
|
||||
│ │ │ ├── task_manager/ # Управление задачами
|
||||
│ │ │ ├── auth/ # Авторизация
|
||||
│ │ │ ├── migration/ # Миграция данных
|
||||
│ │ │ └── plugins/ # Плагины
|
||||
│ │ ├── models/ # Модели данных
|
||||
│ │ ├── services/ # Бизнес-логика
|
||||
│ │ └── schemas/ # Pydantic схемы
|
||||
│ └── tests/
|
||||
├── frontend/ # SvelteKit приложение
|
||||
│ ├── src/
|
||||
│ │ ├── routes/ # Страницы
|
||||
│ │ ├── routes/ # Страницы
|
||||
│ │ ├── lib/
|
||||
│ │ │ ├── components/ # UI компоненты
|
||||
│ │ │ ├── stores/ # Svelte stores
|
||||
│ │ │ └── api/ # API клиент
|
||||
│ │ └── i18n/ # Мультиязычность
|
||||
│ │ │ ├── components/ # UI компоненты
|
||||
│ │ │ ├── stores/ # Svelte stores
|
||||
│ │ │ └── api/ # API клиент
|
||||
│ │ └── i18n/ # Мультиязычность
|
||||
│ └── tests/
|
||||
├── docker/ # Docker конфигурация
|
||||
├── docs/ # Документация
|
||||
@@ -97,63 +148,23 @@ ss-tools/
|
||||
|
||||
### Требования
|
||||
|
||||
**Локальная разработка:**
|
||||
- Python 3.9+
|
||||
- Node.js 18+
|
||||
- npm
|
||||
- 2 GB RAM (минимум)
|
||||
- 5 GB свободного места
|
||||
- **Docker (рекомендуется):** Docker Engine 24+, Docker Compose v2, 4 GB RAM
|
||||
- **Локальная разработка:** Python 3.9+, Node.js 18+, npm, 2 GB RAM, 5 GB диска
|
||||
|
||||
**Docker (рекомендуется):**
|
||||
- Docker Engine 24+
|
||||
- Docker Compose v2
|
||||
- 4 GB RAM (для стабильной работы)
|
||||
|
||||
### Быстрое развертывание бандла (offline)
|
||||
### Docker (рекомендуется)
|
||||
|
||||
```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: Локально
|
||||
После запуска:
|
||||
- Frontend: http://localhost:8000
|
||||
- Backend API: http://localhost:8001
|
||||
- PostgreSQL: localhost:5432
|
||||
|
||||
### Локальная разработка
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
@@ -169,186 +180,37 @@ npm install
|
||||
npm run dev -- --port 5173
|
||||
```
|
||||
|
||||
### Первичная настройка
|
||||
### Начальная настройка
|
||||
|
||||
```bash
|
||||
# Скопируйте шаблон переменных окружения
|
||||
cp .env.example backend/.env.bak # или используйте backend/.env напрямую
|
||||
# Переменные окружения
|
||||
cp .env.example backend/.env
|
||||
|
||||
# Инициализация БД
|
||||
cd backend
|
||||
source .venv/bin/activate
|
||||
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>'
|
||||
python src/scripts/create_admin.py --username admin --password '<temporary-secret>'
|
||||
```
|
||||
|
||||
> Полный каталог переменных окружения — в [`.env.example`](.env.example) в корне проекта.
|
||||
> Полный каталог переменных окружения — в [`.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)
|
||||
### Offline-бандл
|
||||
|
||||
```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
|
||||
# Загрузка образа
|
||||
xz -dc dist/docker/ss-tools.20260517.tar.xz | docker load
|
||||
export POSTGRES_PASSWORD="my-strong-password"
|
||||
docker compose -f dist/docker/docker-compose.light.yml up -d
|
||||
```
|
||||
|
||||
#### 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.
|
||||
Сборка бандла: `./build.sh bundle:light v1.0.0` (light, ~104 MB) или `./build.sh bundle v1.0.0` (full).
|
||||
|
||||
## 📖 Документация
|
||||
|
||||
- [Установка и настройка](docs/installation.md)
|
||||
- [Архитектура системы](docs/architecture.md)
|
||||
- [Разработка плагинов](docs/plugin_dev.md)
|
||||
- [API документация](http://localhost:8001/docs)
|
||||
- [Настройка окружений](docs/settings.md)
|
||||
|
||||
@@ -356,94 +218,52 @@ Bootstrap администратора выполняется entrypoint-скр
|
||||
|
||||
```bash
|
||||
# Backend тесты
|
||||
cd backend
|
||||
source .venv/bin/activate
|
||||
pytest
|
||||
cd backend && source .venv/bin/activate && pytest
|
||||
|
||||
# Frontend тесты
|
||||
cd frontend
|
||||
npm run test
|
||||
cd frontend && npm run test
|
||||
|
||||
# Запуск конкретного теста
|
||||
# Конкретный тест
|
||||
pytest tests/test_auth.py::test_create_user
|
||||
```
|
||||
|
||||
## 🏢 Enterprise Clean Deployment
|
||||
|
||||
Для разворота в корпоративной сети с очищенным дистрибутивом (без тестовых данных, с запретом внешних источников и обязательной compliance-проверкой) используется профиль **enterprise clean**.
|
||||
|
||||
Поддерживаются CLI, API и TUI flows. Подробная документация — в [docs/enterprise-clean.md](docs/enterprise-clean.md).
|
||||
|
||||
## 🔐 Авторизация
|
||||
|
||||
Система поддерживает два метода аутентификации:
|
||||
|
||||
1. **Локальная аутентификация** (username/password)
|
||||
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"]
|
||||
}
|
||||
```
|
||||
Управление пользователями и ролями — через `POST /api/admin/users` и `POST /api/admin/roles`. Документация — `docs/installation.md`.
|
||||
|
||||
## 📊 Мониторинг
|
||||
|
||||
### Отчеты о задачах
|
||||
|
||||
```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
|
||||
```
|
||||
API: `GET /api/reports?page=1&page_size=20` (фильтры по статусу, типу, дате).
|
||||
|
||||
## 💻 Примеры скриптов
|
||||
|
||||
Примеры Python и Bash скриптов для вызова API ss-tools из внешних систем (Airflow, CI/CD, cron) находятся в каталоге [`examples/`](./examples/).
|
||||
Примеры интеграции с внешними системами (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)
|
||||
- [Python](examples/maintenance-api-python.py)
|
||||
- [Bash](examples/maintenance-api-bash.sh)
|
||||
|
||||
Скрипты демонстрируют аутентификацию через API Key (`X-API-Key`), запуск и завершение maintenance-событий, а также обработку ошибок.
|
||||
Скрипты демонстрируют аутентификацию через API Key (`X-API-Key`), запуск и завершение maintenance-событий, обработку ошибок.
|
||||
|
||||
## 🤝 Вклад в проект
|
||||
|
||||
Мы приветствуем contributions! См. [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
|
||||
## 📄 Лицензия
|
||||
|
||||
Проект распространяется под лицензией [MIT](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user