docs: add agreed technology stack and on-prem deployment architecture

2026-09-26 18:50:18 +03:00
1 parent 4362489372
commit f5a720da2f
@@ -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, макеты экранов.