DeOwl
5571448e57
Some checks failed
Build and Deploy Docker Image / build-and-push (push) Has been cancelled
166 lines
7.4 KiB
Markdown
166 lines
7.4 KiB
Markdown
# 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 <token>`
|
||
- Автоматическое создание пользователя в локальной БД при первом входе
|
||
- Проверка прав через механизм `check_team_permission`
|