8.7 KiB
8.7 KiB
Отчёт — лабораторная 3
- Автор, группа: Яковлев Матвей Дмитриевич, БПИ2304
- Целевая оценка; выбранный трек 5, если нужен: 3
- Commit/PR: ветка: (solution/BPI2304-Yakovlev); MR: (TODO после публикации)
- Использованные источники, библиотеки и помощь ИИ: Python 3.12, FastAPI 0.135.3, Uvicorn 0.44.0, psycopg 3.3.3, PostgreSQL 16-alpine, nginx 1.27-alpine; версии закреплены в
requirements.txt,compose.yaml,Dockerfile. При подготовке использовалась помощь Claude.
Запуск из чистого clone
git clone <url-вашего-fork> && cd <каталог>
cp .env.example .env # только синтетические локальные креды; .env в Git не попадает
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
curl -i http://localhost:8080/health/ready # единая точка входа — nginx
python tests/smoke.py --base-url http://localhost:8080
Единственный публичный порт — 8080 балансировщика; напрямую API-реплики портов не публикуют.
Остановка с сохранением данных: docker compose --env-file .env stop api1 api2 db.
Намеренное удаление учебных данных: docker compose --env-file .env down -v.
Явные сценарии проверок:
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# Windows локально: scripts/restart.cmd и scripts/stop-one.cmd
После останова одной реплики восстановление — отдельной командой:
docker compose --env-file .env start api1 (или api2).
Полный вывод — evidence/lifecycle.txt.
Архитектура и решения
Клиент → nginx (lb) → api1 / api2 (один образ, две interchangeables реплики) → общий PostgreSQL.
infra/nginx.conf: upstream сapi1:8080иapi2:8080,max_fails=1 fail_timeout=5s,proxy_next_upstream error timeout http_502 http_503 http_504, таймауты 2/10/10 с. Sticky session не используется: любая реплика обслуживает любой запрос с тем же Bearer-токеном.X-Instance-Id: каждой реплике через окружение задаётся aliasapi1/api2; заголовок добавляется middleware в каждый ответ. Один клиент видит оба значения через LB (см. доказательства).- Общее состояние: PostgreSQL хранит пользователей, чаты, участников, сообщения, сессии — в памяти процесса нет authoritative данных. Сессии не требуют повторного входа при смене реплики.
- Миграции:
SELECT pg_advisory_xact_lock(20261116)перед чтениемschema_migrations, поэтому при одновременном старте двух реплик файл001_init.sqlприменяется ровно один раз. - Общая идемпотентность: таблица
idempotency_recordsс первичным ключом(user_id, method, path, key)в той же БД.POST /chats/{id}/messagesтребуетIdempotency-Key([A-Za-z0-9._:-]{1,128}); хэш канонического тела, код и тело ответа записываются в одной транзакции с сообщением. Повтор с тем же ключом возвращает сохранённый201и тот же Message; другое тело с тем же ключом —409. При конкуренции двух реплик проигравший ловитUniqueViolation, откатывается и читает зафиксированный ответ победителя — дубля нет. Повтор снова проверяет сессию и доступ к чату. scripts/stop-one.shотображаетTARGET_INSTANCE_ID(alias изX-Instance-Id) на соответствующий Compose-сервис и останавливает только его; БД, volume и LB не трогаются.scripts/restart.shперезапускаетdb,api1,api2без удаления volume./health/readyпроверяетSELECT 1; nginx не использует пассивные проверки API как единственный механизм — при отказе реплики запрос повторяется на другой.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| ≥2 реплики, одна точка входа | docker compose ps; 8 запросов к LB |
api1/api2 в заголовке X-Instance-Id у одного клиента; только lb публикует 8080 |
evidence/lifecycle.txt, разделы 2–3 |
| Публичный smoke c идемпотентностью | python tests/smoke.py |
PASS: lab3 public API scenario...; повтор ключа = тот же Message, другой body = 409 |
evidence/lifecycle.txt, раздел 4 |
| Общая идемпотентность в БД | psql ... SELECT count(*) FROM idempotency_records |
число записей ledger равно числу сообщений; уникальный ключ (user, method, path, key) |
evidence/lifecycle.txt, раздел 5 |
| Перезапуск всего стенда с тем же токеном | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS: persistence preserved confirmed data and existing session; schema_migrations без повторов (advisory lock) |
evidence/lifecycle.txt, разделы 6–7 |
| Отказ одной реплики | make test-failover ACTION_SCRIPT=scripts/stop-one.sh |
observed_instances_before: 2, 106 успешных записей, 2 transitional failure, first_recovery_seconds: 0.608, PASS |
evidence/lifecycle.txt, разделы 8–9 |
| Офлайн-проверки | python scripts/check_contract.py; 11 unit-тестов |
PASS, 11 OK | evidence/lifecycle.txt, раздел 10 |
Эксперименты и отказы
Не проводились (целевая оценка 3); уровни 4/5 с нагрузочными сериями и сравнением 1/2/4 реплик не заявлены.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| Останов одной API-реплики hook'ом | LB направляет запросы на оставшуюся реплику; данные и сессия сохраняются | 2 реплики до отказа, 106 успешных записей во время отказа, 2 переходные ошибки, все подтверждённые сообщения на месте, дублей нет | первая успешная запись через 0.608 с; потерь данных 0 |
Перезапуск db + api1 + api2 с volume |
данные, сессии и ledger остаются | PASS; миграции не применялись повторно | automatic ready wait; потерь данных 0 |
Ограничения и следующие шаги
- Уровень 4 не реализован: нет CPU/RAM-лимитов, sequnential отказа каждой реплики под
нагрузкой, rolling update и автоматической проверки исключения недоступного backend
по healthcheck (nginx использует пассивный
max_fails/fail_timeout). - PostgreSQL остаётся единственной точкой отказа стенда; отказ узла БД не моделируется и не заявляется.
- Nginx — единственный LB; при его отказе доступ прекращается (SPOF).
- HTTP допустим только для локального изолированного стенда с синтетическими данными; для удалённой демонстрации нужен TLS.