9.8 KiB
Отчёт — лабораторная 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 создаётся из примера и не коммитится:
cp .env.example .env
Соответствие .env.example:
APP_HOST/APP_PORT— bind uvicorn внутри контейнеров APIHOST_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) только для локального синтетического стенда.
Сборка и запуск:
docker compose --env-file .env up -d --build
Миграции migrations/*.sql применяет one-shot сервис migrate до старта api1/api2 (учёт в schema_migrations). Реплики API миграции при старте не выполняют.
Готовность через LB (подставьте свой HOST_PORT):
curl -i http://127.0.0.1:8080/health/ready
Ожидается HTTP 200, тело {"status":"ok"}, заголовки X-Request-Id и X-Instance-Id (api1 или api2).
Публичный smoke (при уже запущенном стенде):
python tests/smoke.py --base-url http://127.0.0.1:8080
# или: make test BASE_URL=http://127.0.0.1:8080
Проверка сохранности:
# 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-реплики:
# 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 были заняты другими контейнерами).
Остановка:
docker compose --env-file .env down
Намеренное удаление учебных данных (volumes):
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-shotmigrate; Alembic не используется. - Порты API наружу не публикуются; публичная точка входа — LB (
infra/nginx.conf:least_conn,max_fails=1,proxy_next_upstream). - Compose:
lb+api1+api2+postgres+migrate, volumepgdata;.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 допустим только на локальном учебном стенде с синтетическими данными.