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

# Клонирование репозитория
git clone https://git.deowl.ru/vkrb/quantum_backend.git
cd quantum_backend

# Запуск всех сервисов
docker compose up -d

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

# Создание виртуального окружения
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 <token>
• Автоматическое создание пользователя в локальной БД при первом входе
• Проверка прав через механизм check_team_permission