diff --git a/docs/stack.md b/docs/stack.md new file mode 100644 index 0000000..cd07762 --- /dev/null +++ b/docs/stack.md @@ -0,0 +1,146 @@ +# Стек технологий и архитектура развёртывания + +**Проект:** АС «Платформа ОПОРА РОССИИ» +**Статус:** согласовано ядро стека, уточняются параметры сервера +**Дата:** 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** | HTTPS, статика фронтенда | +| Мониторинг | **Prometheus + Grafana + Loki** | Метрики, логи, алерты | +| Бэкапы | **pgBackRest** (БД) + rsync/rclone (файлы) | Ежесуточно, хранение ≥ 30 дней | +| CI/CD | **GitLab CI** | Сборка образов, деплой на сервер | +| AI-ассистент «Зам» | **TBD** — self-hosted LLM (Ollama/vLLM) при наличии GPU, иначе YandexGPT/GigaChat API | Зависит от наличия GPU и требований 152-ФЗ | + +--- + +## 3. Архитектура развёртывания (физический сервер) + +``` + Internet + │ + ┌─────▼─────┐ + │ Nginx │ TLS, статика, reverse proxy + └─────┬─────┘ + ┌────────────┼──────────────┐ + │ │ │ + ┌────▼────┐ ┌────▼────┐ ┌─────▼─────┐ + │ web │ │ api │ │ bot │ + │ (React) │ │FastAPI │ │ aiogram + │ + │ static │ │ │ │ MAX adapt │ + └─────────┘ └────┬────┘ └─────┬─────┘ + │ │ + ┌────────┼──────────────┤ + │ │ │ + ┌─────▼───┐ ┌──▼────┐ ┌──────▼──────┐ + │Postgres │ │ Redis │ │ MinIO │ + └─────────┘ └───┬───┘ └─────────────┘ + │ + ┌─────────┴──────────┐ + │ Celery worker + │ + │ Celery beat │ + └────────────────────┘ + + Мониторинг: Prometheus + Grafana + Loki + Бэкапы: pgBackRest → внешний диск/NAS + offsite +``` + +### Состав контейнеров (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` | Мониторинг и логи | +| `pgbackrest` | Резервное копирование БД | + +--- + +## 4. Требования к серверу (уточняются) + +| Параметр | Значение | Статус | +|---|---|---| +| ОС | Ubuntu Server 24.04 LTS (или Astra Linux / RED OS при требовании реестра) | TBD | +| CPU | ≥ 8 ядер (Вариант 1) | TBD | +| RAM | ≥ 16 ГБ (Вариант 1) | TBD | +| Диск | SSD ≥ 500 ГБ + отдельный диск под бэкапы | TBD | +| GPU | для self-hosted LLM (опционально) | TBD | +| Сеть | статический IP, домен, открытые 80/443 | TBD | +| Бэкап-хранилище | внешний диск / NAS / offsite | TBD | + +--- + +## 5. Надёжность и резервное копирование + +- Ежесуточный бэкап PostgreSQL (pgBackRest), хранение ≥ 30 дней (п. 4.1.9 ТЗ). +- Бэкап артефактов (MinIO) — ежесуточно. +- Восстановление — не более 24 ч (п. 4.1.4 ТЗ). +- Целевые RPO/RTO уточнить: текущий ежесуточный бэкап даёт RPO до 24 ч. +- Мониторинг доступности и алерты (Prometheus + Alertmanager). + +--- + +## 6. Безопасность и 152-ФЗ + +- Все данные — на физическом сервере в РФ (локализация ПДн). +- TLS на всех внешних соединениях. +- Одноразовые ссылки входа, привязка сессии к аккаунту мессенджера (п. 4.1.5 ТЗ). +- Ролевая модель доступа (п. 4.1.8 ТЗ). +- Журналирование действий пользователей и ассистента. +- Секреты — через `.env` / Docker secrets (при необходимости — HashiCorp Vault). +- **Требуется отдельная проработка:** правовые основания обработки ПДн, согласия, сроки хранения, меры защиты по ПП-1119. + +--- + +## 7. CI/CD + +- GitLab CI: линтеры → тесты → сборка Docker-образов → push в registry → деплой на сервер (SSH / Watchtower / Portainer). +- Окружения: `dev` (локально), `staging` (на сервере), `prod`. +- Миграции БД — Alembic в пайплайне деплоя. + +--- + +## 8. Открытые вопросы + +1. **Параметры сервера** — ОС, CPU/RAM/диск, наличие GPU, домен, статический IP. +2. **Реестр отечественного ПО** — нужно ли попадание (влияет на ОС и СУБД). +3. **AI-ассистент** — в объёме? self-hosted LLM (нужен GPU) или облачный YandexGPT/GigaChat? +4. **Вариант масштаба** — 1 (один сервер) или 2 (кластер, K8s, Kafka)? +5. **Бэкап-хранилище** — внешний диск, NAS или offsite? +6. **Домен и TLS** — Let's Encrypt или корпоративный сертификат? + +--- + +## 9. Следующие шаги + +1. Ответить на открытые вопросы (раздел 8). +2. Утвердить документ. +3. Перейти к техническому проекту: структура БД, контракты API, макеты экранов.