From 5571448e5753725c564d94085024786a316b6436 Mon Sep 17 00:00:00 2001 From: DeOwl Date: Tue, 26 May 2026 11:45:13 +0300 Subject: [PATCH] added readme --- README.md | 165 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..25e5d61 --- /dev/null +++ b/README.md @@ -0,0 +1,165 @@ +# Quantum Backend + +Бэкенд-сервис распределенной системы для расчета энергии основного состояния молекул с помощью квантовых алгоритмов (VQE). + +## 📋 Описание + +Quantum Backend — это центральный микросервис, отвечающий за: + +- Управление командами и правами доступа пользователей +- Регистрацию и управление вычислительными системами +- Создание и управление экспериментами +- Распределение задач через брокер сообщений RabbitMQ +- Отслеживание статуса вычислительных систем через механизм heartbeat +- Отказоустойчивое восстановление вычислений + +## 🏗 Архитектура + +Сервис построен на следующих технологиях: + +| Компонент | Технология | +|-----------|------------| +| Web-фреймворк | FastAPI | +| ORM | SQLAlchemy 2.0 (async) | +| База данных | PostgreSQL (asyncpg) | +| Кеширование | Redis + FastAPI Cache | +| Брокер сообщений | RabbitMQ (aio-pika) | +| Аутентификация | Keycloak (python-keycloak) | +| Хранилище файлов | MinIO | + +## 🚀 Запуск + +### Требования + +- Docker & Docker Compose v2 +- Python 3.11+ (для локальной разработки) + +## ⚙️ Переменные окружения + +| Переменная | Описание | +|------------|----------| +| `KEYCLOAK_URL` | URL сервера Keycloak | +| `KEYCLOAK_REALM` | Realm Keycloak | +| `KEYCLOAK_CLIENT_ID` | Client ID | +| `KEYCLOAK_CLIENT_SECRET` | Client Secret | +| `RABBITMQ_HOST` | Хост RabbitMQ | +| `RABBITMQ_USER` | Пользователь RabbitMQ | +| `RABBITMQ_PASSWORD` | Пароль RabbitMQ | + +### Docker Compose + +```bash +# Клонирование репозитория +git clone https://git.deowl.ru/vkrb/quantum_backend.git +cd quantum_backend + +# Запуск всех сервисов +docker compose up -d +``` + +### Локальная разработка + +```bash +# Создание виртуального окружения +python -m venv venv +source venv/bin/activate # Linux/Mac +# или +venv\Scripts\activate # Windows + +# Запуск сервера +uvicorn src.app:app --reload --host 0.0.0.0 --port 8000 +``` + +## 📁 Структура проекта + +``` +src/ +├── api_endpoint/ # HTTP-эндпоинты +│ ├── experiment_api.py # Работа с экспериментами +│ ├── machine_api.py # Управление вычислительными системами +│ ├── teams_api.py # Управление командами +│ ├── user_api.py # Профили пользователей +│ └── health_api.py # Health check +├── config/ +│ ├── database_config.py # Настройки подключения к PostgreSQL +│ ├── keycloak_config.py # Конфигурация аутентификации Keycloak +│ ├── logging_config.py # Настройки логирования +│ ├── minio_config.py # Конфигурация MinIO (файловое хранилище) +│ ├── rabbitmq_config.py # Менеджер подключения к RabbitMQ +│ └── seeding.py # Начальные данные (permissions, статусы) +├── connections/ # Подключения к внешним сервисам +│ ├── db.py # PostgreSQL +│ ├── rabbitmq.py # RabbitMQ (heartbeat, задачи, прогресс) +│ ├── keycloak.py # Аутентификация +│ └── minio.py # Файловое хранилище +├── crud/ # Операции с БД +│ ├── experiment_crud.py +│ ├── machine_crud.py +│ ├── team_crud.py +│ └── user_crud.py +├── sql_models/ # SQLAlchemy модели +│ └── models.py +├── rest_models/ # Pydantic схемы +└── app.py # Точка входа +``` + +## 🔌 API Endpoints + +Сервис предоставляет следующие группы эндпоинтов: + +| Префикс | Описание | +|---------|----------| +| `/health` | Проверка работоспособности | +| `/user` | Управление профилем пользователя | +| `/team` | Управление командами и участниками | +| `/machine` | Управление вычислительными системами | +| `/experiment` | Управление экспериментами и задачами | + +Подробная документация API доступна после запуска по адресу: +`http://localhost:8000/docs` + + +## 🔄 RabbitMQ Интеграция + +Сервис использует RabbitMQ для трех основных задач: + +### 1. Heartbeat мониторинг (fanout exchange `heartbeat`) +- Вычислительные системы каждые 5 секунд отправляют статус +- Сервер отслеживает активность через Redis sorted set +- При timeout > 30 секунд система помечается как OFFLINE + +### 2. Распределение задач (topic exchange `team_{id}`) +- При запуске эксперимента задачи публикуются в очереди по кол-ву кубит +- Routing key: `qubits.{N}` +- Вычислительные системы подписываются на соответствующие очереди + +### 3. Отчеты о прогрессе (direct exchange `progress_report`) +- Вычислительные системы отправляют промежуточные результаты +- Headers: `task_id`, `status`, `system_id` +- Обновление статуса задачи в БД + +## 🗄 База данных + +Основные сущности: + +| Таблица | Описание | +|---------|----------| +| `users` | Пользователи (keycloak_id) | +| `teams` | Команды исследователей | +| `team_members` | Участники команд с правами | +| `permissions` | Доступные права | +| `computational_systems` | Вычислительные системы | +| `team_systems` | Доступ ВС к командам | +| `experiments` | Эксперименты | +| `experiment_types` | Типы экспериментов (модульные) | +| `instances` | Задачи (молекулы) | +| `simulation_results` | Результаты вычислений | +| `simulation_statuses` | Статусы задач | + +## 🔐 Аутентификация + +Сервис использует Keycloak для аутентификации: + +- JWT токены, передаваемые в заголовке `Authorization: Bearer ` +- Автоматическое создание пользователя в локальной БД при первом входе +- Проверка прав через механизм `check_team_permission`