forked from mtusi2026/mtusi2026lab3
94 lines
8.7 KiB
Markdown
94 lines
8.7 KiB
Markdown
# Отчёт — лабораторная 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
|
||
|
||
```sh
|
||
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`.
|
||
|
||
Явные сценарии проверок:
|
||
|
||
```sh
|
||
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`: каждой реплике через окружение задаётся alias `api1`/`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.
|