forked from mtusi2026/mtusi2026lab3
Переиспользован стек lab2 (Postgres/Redis/Argon2id). Добавлены: Nginx балансировщик перед api1/api2, общая идемпотентность POST-сообщений (idempotency_keys + advisory-lock сериализация в Postgres), explicit stop-one/restart hooks. make test/test-persistence/test-failover/validate зелёные для обеих реплик; найдены и исправлены гонка миграций и гонка рестарта Nginx/DNS — см. REPORT.md. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
87 lines
13 KiB
Markdown
87 lines
13 KiB
Markdown
# Отчёт — лабораторная 3
|
||
|
||
- Автор, группа: Сарибекян, БПИ2303
|
||
- Целевая оценка: 4
|
||
- Commit/PR: см. ветку `solution/БПИ2303-Сарибекян`
|
||
- Использованные источники, библиотеки и помощь ИИ: та же база, что в лабе 2 (FastAPI/asyncpg/redis-py/argon2-cffi) плюс Nginx как балансировщик. Реализация подготовлена с помощью AI-ассистента (Claude Code); проверено локальным запуском `make check/test/test-persistence/test-failover/validate`.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Версии: Python 3.12.7, PostgreSQL 16.4, Redis 7.4.1, Nginx 1.27.2. Docker Engine + Compose v2.
|
||
|
||
```sh
|
||
git clone <ваш форк>
|
||
cd mtusi2026lab3
|
||
mkdir -p secrets
|
||
openssl rand -hex 20 > secrets/postgres_password.txt
|
||
printf 'postgresql://messenger:%s@postgres:5432/messenger' "$(cat secrets/postgres_password.txt)" > secrets/database_url.txt
|
||
printf 'redis://redis:6379/0' > secrets/cache_url.txt
|
||
chmod 600 secrets/*.txt
|
||
printf 'SESSION_TTL_SECONDS=3600\n' > .env
|
||
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build
|
||
curl -s localhost:8080/health/ready
|
||
|
||
make test
|
||
chmod +x scripts/restart.sh scripts/stop-one.sh
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
# после отказа одной реплики: docker compose start api1 (или api2), повторить make test-failover для второй.
|
||
```
|
||
|
||
Остановка: `docker compose stop`. Намеренное удаление учебных данных: `docker compose down -v`.
|
||
|
||
## Архитектура и решения
|
||
|
||
```
|
||
Клиент → lb (Nginx, :8080) → api1 / api2 (FastAPI) → PostgreSQL (общий) + Redis (общие сессии)
|
||
```
|
||
|
||
- **Балансировщик**: Nginx, upstream с двумя явными backend (`api1:8080`, `api2:8080`), `max_fails=1 fail_timeout=3s` — пассивная проверка здоровья: один неудачный запрос выводит backend из ротации на 3 секунды, что укладывается в бюджет обнаружения отказа <10с. `worker_processes 1` — намеренное решение: с несколькими worker-процессами у каждого свой независимый round-robin счётчик, и балансировка на малом числе реплик визуально "залипала" на одном backend (воспроизведено и исправлено, см. ограничения).
|
||
- **Почему две явные службы `api1`/`api2`, а не `--scale api=2`**: с явными именами легко детерминированно остановить ровно одну реплику по алиасу (`TARGET_INSTANCE_ID`), и `INSTANCE_ID` передаётся как переменная окружения напрямую, без догадок по hostname контейнера.
|
||
- **Общие хранилища**: Postgres и Redis — те же роли, что в lab2, без изменений схемы (см. `migrations/0001_init.sql`), плюс новая таблица `idempotency_keys` (`migrations/0002_idempotency.sql`).
|
||
- **Локальных сессий в API не осталось**: обе реплики читают/пишут один и тот же Redis по `CACHE_URL_FILE`; ни один стейт не держится в памяти процесса API (кроме пула соединений).
|
||
- **Идемпотентность** (`app/idempotency.py`): таблица `idempotency_keys` с PK `(user_id, method, path, idem_key)`. На POST: `INSERT ... ON CONFLICT DO NOTHING` внутри той же транзакции, что и создание сообщения; если конфликт — читаем существующую запись: совпадает хеш запроса → при необходимости дождаться `status='done'` (конкурентная уже выполняющаяся транзакция блокирует INSERT до своего COMMIT/ROLLBACK на уровне PostgreSQL — поэтому конкурентные повторы с одним ключом естественно сериализуются самой БД, без ручных блокировок в приложении) и вернуть тот же результат; не совпадает — `409`. При ошибке внутри `perform()` строка идемпотентности откатывается вместе со всей транзакцией — повтор не блокируется навечно.
|
||
- **Транзиентные ошибки не коммитятся как факт**: побочный эффект (вставка сообщения) и фиксация результата идемпотентности — одна транзакция `asyncpg`; при любой ошибке всё откатывается целиком.
|
||
- **Миграции без гонки реплик**: `app/db.py` берёт `pg_advisory_lock` перед применением миграций — без этого обе реплики, стартующие одновременно, пытались создать одну и ту же таблицу и падали с `UniqueViolationError` (воспроизведено и исправлено, см. ограничения).
|
||
- **Ресурсы**: `deploy.resources.limits` на каждый сервис (`compose.yaml`) — Compose v2 применяет их и без Swarm.
|
||
- **Graceful shutdown**: `uvicorn --timeout-graceful-shutdown 5` — после SIGTERM процесс донашивает текущие запросы до 5 секунд, не принимая новые.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| ≥2 реплики, одна точка входа, общая БД/сессии | `docker compose ps`; 8 последовательных `GET /health/live` через LB | чередование `X-Instance-Id: api1/api2` | ручной прогон, см. ниже |
|
||
| Публичный smoke | `make test` | `PASS: lab3 public API scenario...` | вывод команды |
|
||
| Персистентность | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS: persistence preserved confirmed data and existing session.` | вывод команды |
|
||
| Failover (≥2 наблюдаемых реплики, запись не прерывается >10с) | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`, для обеих реплик по очереди | `observed_instances_before: 2`; 1-й прогон: `successful_writes: 97, failed_attempts: 0, first_recovery_seconds: 0.899`; 2-й прогон (другая реплика): `successful_writes: 101, failed_attempts: 0, first_recovery_seconds: 0.885` | вывод команды, `evidence/failover_both_replicas.txt` |
|
||
| Идемпотентность при конкурентном повторе через разные реплики | 5 параллельных `curl` POST с одним `Idempotency-Key` | все 5 ответов — один и тот же `id` сообщения; в БД `SELECT count(*)` = 1 | `evidence/idempotency_concurrent.txt` |
|
||
| Разный body под тем же ключом → 409 | повтор с тем же ключом, другим `text` | `409 conflict` | `evidence/idempotency_concurrent.txt` |
|
||
| Health/readiness, graceful shutdown | `uvicorn --timeout-graceful-shutdown 5`; Nginx `max_fails=1 fail_timeout=3s` | код/конфиг; поведение подтверждено failover-тестом (восстановление <1с) | `Dockerfile`, `infra/nginx/nginx.conf` |
|
||
| Нет публикации портов API в обход LB | `compose.yaml`: `api1`/`api2` без секции `ports` | только `lb` публикует `8080:8080` | `compose.yaml` |
|
||
| Ресурсные лимиты | `deploy.resources.limits` на каждый сервис | код ревью | `compose.yaml` |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
**Последовательная остановка каждой реплики (уровень 4).** `scripts/stop-one.sh` получает `TARGET_INSTANCE_ID` от теста и останавливает именно её контейнер (`docker compose stop api1|api2`). Прогнано дважды — по разу на каждую реплику, с восстановлением (`docker compose start`) между прогонами.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| Остановка `api1` (пока работает `api2`) | Запись продолжается <10с, нет дублей | `successful_writes=97, failed_attempts=0, first_recovery_seconds=0.899` | восстановление записи 0.9с, потерь нет |
|
||
| Остановка `api2` (пока работает `api1`) | То же | `successful_writes=101, failed_attempts=0, first_recovery_seconds=0.885` | восстановление записи 0.89с, потерь нет |
|
||
| `docker compose restart postgres redis api1 api2 lb` (последовательно) | Сообщения и активная сессия сохраняются | `PASS` в `make test-persistence`, тот же Bearer-токен работает | восстановление <90с (бюджет теста), без потери данных |
|
||
| 5 параллельных POST, один `Idempotency-Key` | Ровно одно сообщение | 1 строка в `messages`, все 5 ответов идентичны | без дублей |
|
||
|
||
**Ограничение:** нагрузочный тест (`tests/load.py`) и исследовательский трек уровня 5 не выполнялись — цель лабы — оценка 4.
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- При разработке найдены и исправлены два реальных бага concurrency, оба стоит знать на защите:
|
||
1. **Гонка миграций**: обе реплики при одновременном первом старте пытались создать одинаковые таблицы и падали с `UniqueViolationError`. Исправлено `pg_advisory_lock` в `app/db.py` перед прогоном миграций.
|
||
2. **"Залипание" балансировки на одной реплике**: при `worker_processes auto` у Nginx каждый worker-процесс ведёт свой независимый round-robin счётчик, и на малом числе запросов казалось, что трафик идёт только на `api1`. Исправлено `worker_processes 1` (демонстративно для лабы — на реальной нагрузке это стало бы ограничением пропускной способности самого LB, что подходящий компромисс не для production, а именно здесь задокументирован явно).
|
||
3. **Рестарт целого стека падал**: `docker compose restart` перезапускает контейнеры параллельно, и Nginx (резолвит upstream-хосты только при своём старте) иногда стартовал раньше, чем Docker DNS успевал зарегистрировать `api1`/`api2` после их параллельного перезапуска, и падал насмерть (`host not found in upstream`). Исправлено явной последовательностью в `scripts/restart.sh`: сначала БД/Redis, затем `api1`/`api2`, и только потом `lb`.
|
||
- Трек исследования уровня 5 (цена масштабирования / отказ узла) не реализован.
|
||
- Rolling update под нагрузкой не прогонялся отдельным сценарием (ограничение времени); качественно это покрывается failover-тестом, который и есть частный случай замены одной реплики.
|
||
- Nginx open-source не делает активных health-check проб — только пассивные (по факту неудачного реального запроса); для прод-уровня здесь нужен Nginx Plus/HAProxy/Traefik с активными пробами.
|