forked from mtusi2026/mtusi2026lab3
154 lines
9.8 KiB
Markdown
154 lines
9.8 KiB
Markdown
# Отчёт — лабораторная 3
|
||
|
||
- Автор, группа: Гадяцкий Л. Е., БПИ2302
|
||
- Целевая оценка: 3
|
||
- Commit/PR: solution/BPI2302-Gadiatskiy
|
||
- Использованные источники и библиотеки:
|
||
- контракт и семантика: `contracts/openapi.json`, `contracts/README.md`, `README.md`, `COURSE.md`
|
||
- перенос из lab2: FastAPI, PostgreSQL/сессии, SQLAlchemy, миграции, формат ошибок
|
||
- runtime: FastAPI 0.115.6, Uvicorn 0.34.0, Pydantic 2.10.4, SQLAlchemy 2.0.36, psycopg 3.2.4, argon2-cffi 23.1.0
|
||
- PostgreSQL: `postgres:16-alpine`; LB: `nginx:1.27-alpine`
|
||
- Помощь ИИ использована при переносе lab2, частично при настройке Compose+Nginx и при написании отчёта. Результаты подтверждаются сохранёнными запусками.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
**Prerequisites:** Docker и Docker Compose. Python 3.9+ нужен только для публичных проверок (`make check` / `make test` / `tests/resilience.py`). Runtime приложения — внутри образа.
|
||
|
||
**Версии:**
|
||
- API: базовый образ `python:3.12.8-slim-bookworm` → локальный `mtusi-messenger:lab3`
|
||
- PostgreSQL: `postgres:16-alpine`
|
||
- Nginx: `nginx:1.27-alpine`
|
||
- зависимости: `requirements.txt`
|
||
|
||
**Конфигурация:** секретов в Git нет. Локальный `.env` создаётся из примера и не коммитится:
|
||
|
||
```sh
|
||
cp .env.example .env
|
||
```
|
||
|
||
Соответствие `.env.example`:
|
||
- `APP_HOST` / `APP_PORT` — bind uvicorn внутри контейнеров API
|
||
- `HOST_PORT` — порт LB на host (по умолчанию 8080; если занят — например 8081)
|
||
- `APP_ENV` — среда запуска (`lab`)
|
||
- `SESSION_TTL_SECONDS` — TTL сессии (по умолчанию 3600; для обычного smoke ≥ 300)
|
||
- `SESSION_STORE=postgres` — сессии в PostgreSQL (общие для всех реплик)
|
||
- `DATABASE_URL` — строка подключения API/migrate к PostgreSQL в compose-сети
|
||
(приложение также поддерживает `DATABASE_URL_FILE`)
|
||
- `IDEMPOTENCY_TTL_SECONDS` — срок хранения идемпотентных записей (по умолчанию 86400)
|
||
- `API_REPLICAS=2` — в `compose.yaml` зафиксированы сервисы `api1` и `api2`
|
||
|
||
Учебные credentials compose (`messenger` / `messenger`) только для локального синтетического стенда.
|
||
|
||
**Сборка и запуск:**
|
||
|
||
```sh
|
||
docker compose --env-file .env up -d --build
|
||
```
|
||
|
||
Миграции `migrations/*.sql` применяет one-shot сервис `migrate` до старта `api1`/`api2` (учёт в `schema_migrations`). Реплики API миграции при старте не выполняют.
|
||
|
||
Готовность через LB (подставьте свой `HOST_PORT`):
|
||
|
||
```sh
|
||
curl -i http://127.0.0.1:8080/health/ready
|
||
```
|
||
|
||
Ожидается HTTP 200, тело `{"status":"ok"}`, заголовки `X-Request-Id` и `X-Instance-Id` (`api1` или `api2`).
|
||
|
||
**Публичный smoke** (при уже запущенном стенде):
|
||
|
||
```sh
|
||
python tests/smoke.py --base-url http://127.0.0.1:8080
|
||
# или: make test BASE_URL=http://127.0.0.1:8080
|
||
```
|
||
|
||
**Проверка сохранности:**
|
||
|
||
```sh
|
||
# Unix:
|
||
chmod +x scripts/restart.sh
|
||
python tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
|
||
|
||
# Windows:
|
||
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8080
|
||
```
|
||
|
||
Hook выполняет `docker compose --env-file .env restart` для `postgres`, `api1`, `api2`, `lb` **без** удаления volumes (`down -v` не используется).
|
||
|
||
**Проверка отказа одной API-реплики:**
|
||
|
||
```sh
|
||
# Unix:
|
||
chmod +x scripts/stop-one.sh
|
||
python tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080
|
||
|
||
# Windows:
|
||
python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8080
|
||
```
|
||
|
||
`TARGET_INSTANCE_ID` = `X-Instance-Id` (`api1`/`api2`); hook делает `docker compose stop` только этой реплики и оставляет её остановленной. После теста: `docker compose --env-file .env start api1` (или `api2`). Для защиты повторить на второй реплике после восстановления первой.
|
||
|
||
Локальная проверка автора выполнялась на `HOST_PORT=8082` (host-порты 8080/8081 были заняты другими контейнерами).
|
||
|
||
**Остановка:**
|
||
|
||
```sh
|
||
docker compose --env-file .env down
|
||
```
|
||
|
||
Намеренное удаление учебных данных (volumes):
|
||
|
||
```sh
|
||
docker compose --env-file .env down -v
|
||
```
|
||
|
||
## Архитектура и решения
|
||
|
||
```
|
||
HTTP-клиент
|
||
→ lb (Nginx)
|
||
→ api1 / api2 (uvicorn + FastAPI)
|
||
→ PostgreSQL
|
||
users, chats, chat_members, messages, sessions, idempotency_records
|
||
```
|
||
|
||
- Источник истины — PostgreSQL. Локального состояния, от которого зависит корректность, в API нет.
|
||
- Сессии в PostgreSQL: один Bearer работает через любую реплику без sticky sessions.
|
||
- `X-Instance-Id` стабилен на жизнь процесса (`INSTANCE_ID` сервиса).
|
||
- `Idempotency-Key` обязателен на `POST .../messages`; область: пользователь + метод + путь + ключ; запись результата атомарна с сообщением; другой body при том же ключе → 409; TTL 24ч.
|
||
- ORM-модели: `src/messenger/tables.py`. Доступ к данным: `src/messenger/store.py`.
|
||
- Миграции: SQL в `migrations/` + one-shot `migrate`; Alembic не используется.
|
||
- Порты API наружу не публикуются; публичная точка входа — LB (`infra/nginx.conf`: `least_conn`, `max_fails=1`, `proxy_next_upstream`).
|
||
- Compose: `lb` + `api1` + `api2` + `postgres` + `migrate`, volume `pgdata`; `.env` в Git не коммитится.
|
||
|
||
Перенесено из lab2: auth Basic→Bearer, Argon2id, чаты/сообщения, keyset-пагинация, формат ошибок.
|
||
Добавлено в lab3: Nginx LB, две реплики API, `X-Instance-Id`, общая идемпотентность, отдельный migrate, `scripts/stop-one`.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke (lab2 + Idempotency-Key / X-Instance-Id) | `python tests/smoke.py --base-url http://127.0.0.1:8082` | `PASS: lab3 public API scenario...` | `evidence/smoke.txt` |
|
||
| Стенд: ≥2 API, один LB, общая БД и сессии | `docker compose --env-file .env ps` | `lb`, `api1`, `api2`, `postgres`; migrate Exited 0 | `evidence/compose-ps.txt` |
|
||
| Разные реплики через LB с одной сессией | серия запросов через LB | `api1` и `api2` | `evidence/instances.txt` |
|
||
| Persistence: рестарт без удаления volumes, прежний токен | `python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8082` | `PASS: persistence preserved...` | `evidence/restart.txt` |
|
||
| Failover: остановка одной API-реплики | `python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8082` | 2 instance до отказа; first_recovery ≈2.75 с; без дублей | `evidence/failover.txt` |
|
||
| Идемпотентность POST сообщений | smoke replay + failover retries | тот же ключ → то же Message; другой body → 409 | `evidence/smoke.txt`, `evidence/failover.txt` |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Для оценки 3 отдельный нагрузочный трек не выполнялся. Проверены сохранность и отказ API-реплики:
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| `docker compose --env-file .env restart` (postgres+api1+api2+lb), volumes сохранены | `/health/ready` ok; прежний Bearer читает те же данные; сессия действует | persistence PASS | в бюджете теста (hook ≤90 с, ready ≤90 с); потери данных нет |
|
||
| `docker compose stop` одной API-реплики | LB обслуживает живую; записи ≤10 с; без дублей по retry | failover PASS; `first_recovery_seconds≈2.75` | подтверждённые сообщения на месте |
|
||
|
||
Аппаратный профиль: локальный Docker Desktop на Windows; 2 API + Nginx + PostgreSQL без CPU/RAM limits.
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- Redis/Valkey, CPU/RAM limits, rolling update под нагрузкой и трек 5 не выполнялись.
|
||
- Единственный PostgreSQL и единственный Nginx — SPOF; отказ host/узла не выдерживается.
|
||
- Basic по HTTP допустим только на локальном учебном стенде с синтетическими данными.
|