# Стек технологий и архитектура развёртывания

**Проект:** АС «Платформа ОПОРА РОССИИ»
**Статус:** согласовано (бэкапы отложены, выбор LLM — в тестировании)
**Дата:** 26.09.2026

---

## 1. Назначение документа

Документ фиксирует согласованный технологический стек и архитектуру развёртывания Системы на физическом сервере заказчика (on-premise, территория РФ). Служит основой для технического проекта и сметы.

---

## 2. Согласованный стек

| Слой | Технология | Комментарий |
|---|---|---|
| Backend API | **Python 3.12 + FastAPI** | Async, автогенерация OpenAPI, единое API для бота и сайта |
| ORM / миграции | **SQLAlchemy 2 + Alembic** | Контроль схемы, миграции |
| БД | **PostgreSQL 16** | Реляционная СУБД по ТЗ |
| Кэш / rate-limit | **Redis** | Лимиты, кэш, брокер для Celery |
| Очередь / фоновые задачи | **Celery + Redis** | Рассылки, автообновление срезов, ретраи |
| Планировщик | **Celery Beat** | Расписание рассылок и выгрузок |
| Бот | **aiogram 3** (Telegram) + адаптер **MAX Bot API** | Единый бот-адаптер с двумя каналами (п. 4.1.13.2 ТЗ) |
| Frontend | **React + TypeScript + Vite** | Mobile-first SPA |
| UI | **Tailwind CSS + shadcn/ui** | Гибкость под брендбук «ОПОРА РОССИИ» |
| Файлы (артефакты) | **MinIO** (S3-совместимое, локально) | Файлы до 50 МБ, привязка к объектам |
| Контейнеризация | **Docker Engine + Docker Compose** | Один сервер; задел под Kubernetes при росте |
| Reverse proxy / TLS | **Nginx + Certbot (Let's Encrypt)** | HTTPS, статика фронтенда |
| Мониторинг | **Prometheus + Grafana + Loki** | Метрики, логи, алерты |
| Бэкапы | **Отложены** (см. раздел 5) | Принятый риск на текущем этапе |
| CI/CD | **GitLab CI** | Сборка образов, деплой на сервер |
| AI-ассистент «Зам» | **OpenRouter → `deepseek/deepseek-chat`** | Без GPU; модель выбрана по тестам (раздел 8). PiAPI — резерв (медиа) |

---

## 3. Архитектура развёртывания (физический сервер)

```
                    Internet
                       │
                 ┌─────▼─────┐
                 │   Nginx   │  TLS (Let's Encrypt), статика, reverse proxy
                 └─────┬─────┘
          ┌────────────┼──────────────┐
          │            │              │
     ┌────▼────┐  ┌────▼────┐   ┌─────▼─────┐
     │  web    │  │   api   │   │  bot      │
     │ (React) │  │FastAPI  │   │ aiogram + │
     │ static  │  │         │   │ MAX adapt │
     └─────────┘  └────┬────┘   └─────┬─────┘
                       │              │
              ┌────────┼──────────────┤
              │        │              │
        ┌─────▼───┐ ┌──▼────┐  ┌──────▼──────┐
        │Postgres │ │ Redis │  │   MinIO     │
        └─────────┘ └───┬───┘  └─────────────┘
                        │
              ┌─────────┴──────────┐
              │  Celery worker +   │
              │  Celery beat       │
              └────────────────────┘

     Мониторинг: Prometheus + Grafana + Loki
     AI: внешний LLM API (OpenRouter / PiAPI) — только обезличенные данные
```

### Состав контейнеров (Docker Compose)

| Контейнер | Назначение |
|---|---|
| `nginx` | TLS-терминация, reverse proxy, раздача статики |
| `web` | Сборка React (или статика через nginx) |
| `api` | FastAPI (gunicorn + uvicorn workers) |
| `bot` | aiogram + адаптер MAX |
| `worker` | Celery worker |
| `beat` | Celery beat |
| `postgres` | PostgreSQL 16 |
| `redis` | Redis |
| `minio` | S3-совместимое хранилище артефактов |
| `prometheus` / `grafana` / `loki` | Мониторинг и логи |

---

## 4. Параметры сервера

| Параметр | Значение |
|---|---|
| ОС | **Ubuntu Server (LTS)** |
| CPU | **Intel Xeon** |
| RAM | **16 ГБ** |
| GPU | **нет** (AI — через внешний API) |
| Диск | **SSD, единый** (отдельного диска под бэкапы нет) |
| Сеть | **статический IP** |
| Домен | **opora.my-dpr.ru** (тестовый) |
| TLS | **Let's Encrypt** (Certbot, автообновление) |

**Примечание по реестру отечественного ПО:** сервер на Ubuntu, поэтому полное соответствие реестру (ОС Astra Linux / RED OS) сейчас не достигается. При необходимости импортозамещения — отдельная миграция ОС и СУБД (Postgres Pro / Tantor). На текущем этапе используем стандартный PostgreSQL 16.

---

## 5. Надёжность и резервное копирование

**Решение заказчика: бэкапы на текущем этапе отложены.**

Принятый риск: при сбое диска или ошибке данные могут быть потеряны безвозвратно. Рекомендация на будущее (не блокирует старт):

- минимальный `pg_dump` раз в сутки на внешнее хранилище (offsite, S3-совместимое в РФ) — дёшево и снимает основной риск;
- бэкап артефактов (MinIO) через rclone;
- хранение ≥ 30 дней (п. 4.1.9 ТЗ);
- восстановление — не более 24 ч (п. 4.1.4 ТЗ).

Мониторинг доступности и алерты (Prometheus + Alertmanager) — в объёме.

---

## 6. Безопасность и 152-ФЗ

- Все данные — на физическом сервере в РФ (локализация ПДн).
- TLS на всех внешних соединениях (Let's Encrypt).
- Одноразовые ссылки входа, привязка сессии к аккаунту мессенджера (п. 4.1.5 ТЗ).
- Ролевая модель доступа (п. 4.1.8 ТЗ).
- Журналирование действий пользователей и ассистента.
- Секреты — через `.env` / Docker secrets (при необходимости — HashiCorp Vault).

### AI-ассистент и внешние API (важно)

OpenRouter и PiAPI — зарубежные сервисы, данные уходят за пределы РФ. Требования:

- **Не передавать персональные данные** (ФИО, контакты, аккаунты мессенджеров) во внешний LLM.
- Передавать только обезличенный контекст: агрегаты по регионам, названия целей, тексты задач без ПДн.
- Все действия ассистента фиксировать в журнале (кто, что, когда).
- Ассистент действует в рамках прав владельца, с возможностью отключения/ограничения.
- **Требуется отдельная проработка:** правовые основания обработки ПДн, согласия, сроки хранения, меры защиты по ПП-1119.

---

## 7. CI/CD

- GitLab CI: линтеры → тесты → сборка Docker-образов → push в registry → деплой на сервер (SSH).
- Окружения: `dev` (локально), `staging` (на сервере), `prod`.
- Миграции БД — Alembic в пайплайне деплоя.

---

## 8. AI-ассистент: выбранная модель

**Модель: `deepseek/deepseek-chat` (через OpenRouter).**

Выбор сделан по результатам тестирования (стенд `tools/test_models.py`, отчёт — `docs/llm-test-report.md`).

| Тест | Статус | Латентность | Стоимость |
|---|---|---|---|
| Русский текст (еженедельный фокус целей) | ✅ OK | 9.65 с | $0.00019 |
| Function calling (`create_task`) | ✅ OK | 3.55 с | $0.00034 |
| Структурированный JSON | ✅ OK | 3.34 с | $0.00008 |

**Оценка стоимости:** ~$0.0002–0.0003 за действие ассистента → ~$3/мес при 10 000 действий, ~$30/мес при 100 000.

**Критерии, по которым оценивалась модель:** русский язык и терминология, надёжность function calling, стоимость, латентность, размер контекста, стабильность JSON.

**PiAPI** — резервный вариант (генерация медиа), на текущем этапе не используется.

---

## 9. Открытые вопросы

1. **Бэкапы** — когда включать (отложено).
2. **Реестр отечественного ПО** — нужен ли в перспективе.
3. **PiAPI** — назначение и момент подключения (резерв).

---

## 10. Следующие шаги

1. Утвердить документ.
2. Перейти к техническому проекту: структура БД, контракты API, макеты экранов.