forked from mtusi2026/mtusi2026lab3
113 lines
16 KiB
Markdown
113 lines
16 KiB
Markdown
# Отчёт — лабораторная 3
|
||
|
||
- **Автор / группа:** Авзалов Артур Марсович, БПИ2301
|
||
- **Целевая оценка:** 4; трек 5 не заявлен
|
||
- **Статус:** локальная реализация проверена на двух Windows-компьютерах с Docker Desktop 06.11.2026; публичный API, persistence, идемпотентность, остановка обеих реплик и поочерёдное пересоздание под нагрузкой проверены.
|
||
- **Инструменты:** Python 3.12, FastAPI/Pydantic, PostgreSQL 16, psycopg3 pool, Redis 7.4 с AOF, HAProxy 3.1, Docker Compose.
|
||
- **Помощь ИИ:** ChatGPT использовался для генерации кода, SQL-миграций, конфигурации инфраструктуры, тестов и пояснений. Результаты ниже получены на локальном стенде и зафиксированы по фактическому выводу команд.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Нужны Docker Desktop (Compose v2), Python 3.9+ и make (или запуск тестов напрямую). PowerShell:
|
||
|
||
```powershell
|
||
Copy-Item .env.example .env
|
||
# В .env заменить POSTGRES_PASSWORD на свой локальный случайный ASCII-пароль без URI-спецсимволов.
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build
|
||
docker compose --env-file .env ps
|
||
make check PYTHON=python
|
||
make test PYTHON=python
|
||
python tests/idempotency_parallel.py
|
||
```
|
||
|
||
Все API-запросы идут только через `http://localhost:8080` (HAProxy). PostgreSQL, Redis и API-реплики не публикуют портов на хост. Не коммитить `.env` и результаты с секретами. Безопасная остановка: `docker compose --env-file .env down`; **без `-v`**. Удаление учебных данных только намеренно: `down -v`.
|
||
|
||
Запуск миграций: одноразовый сервис `migrate` выполняется до старта API; версионные скрипты `db/migrations/001_initial.sql` и `002_idempotency.sql`. Отдельная повторная проверка: `docker compose --env-file .env run --rm migrate`.
|
||
|
||
Проба сохранности на Windows:
|
||
|
||
```powershell
|
||
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd
|
||
```
|
||
|
||
На Linux: `chmod +x scripts/*.sh`, затем `make test-persistence ACTION_SCRIPT=scripts/restart.sh`.
|
||
|
||
## Архитектура
|
||
|
||
```text
|
||
Client localhost:8080 -> HAProxy roundrobin + readiness check (1 s interval, fall=2)
|
||
| |
|
||
api1 api2
|
||
\ /
|
||
PostgreSQL (users, chats, messages, idempotency receipts)
|
||
Redis AOF (session:<SHA256(bearer)> => user UUID, EX TTL)
|
||
```
|
||
|
||
Между API-репликами нет общих файлов и локального авторизационного состояния. `API_INSTANCE_ID` назначается для каждой реплики, отражается в `X-Instance-Id`, а `X-Request-Id` генерируется для каждого запроса. Basic используется только на login; пользователь и членство проверяются через Bearer + Redis + PostgreSQL. Argon2id применяется для паролей.
|
||
|
||
Тексты сообщений, названия чатов и display names — UTF-8 в PostgreSQL `bytea`, чтобы API поддерживал U+0000, запрещённый в PostgreSQL `text/varchar`. Транзакция защищает создание чата и участников. Пагинация истории — keyset по `(created_at, id)`, индекс `(chat_id, created_at, id)`.
|
||
|
||
### Идемпотентность POST сообщений
|
||
|
||
Ключ `(actor_id, chat_id, method, Idempotency-Key)` уникален в PostgreSQL. Body fingerprint — SHA-256 канонического JSON с полем `text`; lab3 ещё не содержит вложений. В транзакции после проверки доступа вызывается `pg_advisory_xact_lock(hashtextextended(scope, 0))`, затем либо читается результат предыдущего сообщения, либо атомарно вставляются сообщение и receipt. Повтор возвращает тот же `201 Message`, другое тело с тем же ключом — `409`. Блокировка работает между процессами и освобождается с завершением транзакции.
|
||
|
||
Результаты сохраняются бессрочно: требование **не менее 24 часов** выполняется, но БД будет расти; политику очистки следует добавить при длительной эксплуатации. Внешний отказ после COMMIT безопасен: повтор возвращает исходное сообщение. Нет автоматических повторов POST на уровне HAProxy.
|
||
|
||
### Отказы и ограничения
|
||
|
||
Остановка одной API-реплики переносится на другую. HAProxy проверяет `GET /health/ready` с интервалом 1 с и `fall=2`; в двух прогонах с остановкой api1 восстановление записи заняло 6.281 и 8.282 с. При повторной автоматической проверке на втором компьютере восстановление заняло 8.328 с; имя остановленной реплики в сохранённом выводе не указано. Все три значения меньше 10 с. При ручной остановке api2 на первом компьютере LB вернул 200 от api1; на втором компьютере первый запрос к LB получил переходный 503, после чего публичный smoke успешно прошёл через оставшуюся реплику. Мгновенное переключение или точное время восстановления для api2 не заявляются. Graceful shutdown Uvicorn ограничен 8 с, Docker stop grace period 12 с. HAProxy использует Docker DNS резолвер для смены адреса пересозданной реплики. На каждом API контейнере CPU limit 0.75 и RAM limit 384 MiB, LB 0.5/128 MiB, PG 1.0/512 MiB, Redis 0.5/256 MiB.
|
||
|
||
Остановка PostgreSQL или Redis делает обязательные операции недоступными (503); `/health/live` не зависит от внешних сервисов, `/health/ready` проверяет оба. Хранилища **не реплицированы**. Потеря узла Docker, LB, диска или volumes не покрыта. HTTP Basic/Bearer в локальном стенде допускается только на loopback; для удалённого доступа требуется TLS.
|
||
|
||
Миграции вынесены в отдельный one-shot сервис и координируются PG advisory lock. Текущие миграции предназначены для **чистого стенда Lab3**; автоматический импорт уже существующей чужой схемы/volume Lab2 не заявлен. Rolling update рассчитан на совместимость неизменной текущей схемы с обеими API-репликами; миграции с несовместимыми ALTER TABLE потребуют расширения стратегии.
|
||
|
||
## Фактические проверки (Windows PowerShell + Docker Desktop, 06.11.2026)
|
||
|
||
| Критерий | Команда / способ | Наблюдение |
|
||
| --- | --- | --- |
|
||
| Подъём стенда | `docker compose --env-file .env up -d --build`, `docker compose --env-file .env ps` | **PASS**: `api1`, `api2`, `lb`, `postgres`, `redis` — `healthy`; наружу опубликован только LB на `127.0.0.1:8080` |
|
||
| Проверка структуры | `make check PYTHON=python` | **PASS**: `offline skeleton structure, local refs and Python syntax; application NOT tested.` |
|
||
| Публичный API | `make test PYTHON=python` | **PASS**: `lab3 public API scenario`; также **PASS** после rolling update и при остановленной api2 на обоих компьютерах |
|
||
| Конкурентная идемпотентность | `python tests/idempotency_parallel.py` | **PASS**: две реплики, одно сообщение, повтор `201`, изменённое тело `409` |
|
||
| Persistence | `python tests/resilience.py --mode persistence --action-script scripts/restart.cmd` | **PASS**: подтверждённые данные и прежняя сессия сохранились после restart; тест требует дополнительно показать scope hook |
|
||
| Автоматический failover | `python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd` | **PASS** трижды (6.281, 8.282 и 8.328 с); на первом компьютере после тестов в `docker compose ps` отсутствовала api1, api2 оставалась `healthy`. На втором выбор остановленной реплики в логе не зафиксирован |
|
||
| Отказ api2 | `docker compose --env-file .env stop --timeout 1 api2` + `curl.exe -i http://localhost:8080/health/ready` + `make test PYTHON=python` | **PASS** для функциональной доступности: на первом ПК `200 OK`, `X-Instance-Id: api1` и smoke PASS. На втором ПК первый `curl` вернул от HAProxy `503 No server is available`, но следующий smoke PASS при остановленной api2. Срок восстановления именно для api2 не замерен |
|
||
| Повторное применение миграций на втором ПК | `docker compose --env-file .env run --rm migrate` | **PASS**: `Migrations up to date` |
|
||
| Возврат обеих реплик | `docker compose --env-file .env up -d --no-deps --wait api1 api2` | **PASS**: обе реплики `healthy` |
|
||
| Rolling update под нагрузкой | Фоновый 90-секундный `tests/load.py` + поочерёдное `--force-recreate --wait api1`, затем `api2` | **PASS**: нагрузка была `Running` до замены; обе реплики вернулись в `healthy`; первый ПК — 171 успешная запись, 0 ошибок; второй ПК — 168 успешных записей, 0 ошибок; оба раза job `Completed` |
|
||
|
||
Linux persistence отдельно не прогонялся. Локальный дополнительный unit-тест `tests/own_unit.py` не заявляется как выполненный; публичный smoke, check и конкурентная идемпотентность проверены.
|
||
|
||
### Измерения нагрузки
|
||
|
||
| Сценарий | Успешные запросы | Ошибки | RPS | p50 | p95 | p99 |
|
||
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
|
||
| Базовая нагрузка, concurrency=4, 30 с | 60 | 0 | 1.863 | 2063 мс | 2344 мс | 2703 мс |
|
||
| 90 с без подтверждённого перекрытия с update | 176 | 0 | 1.914 | 2063 мс | 2203 мс | 2469 мс |
|
||
| Rolling update под нагрузкой, первый ПК, concurrency=4, 90 с | 171 | 0 | 1.838 | 2063 мс | 2828 мс | 4047 мс |
|
||
| Базовая нагрузка, второй ПК, concurrency=4, 30 с | 60 | 0 | 1.882 | 2093 мс | 2125 мс | 2329 мс |
|
||
| Rolling update, второй ПК, concurrency=4, 90 с | 168 | 0 | 1.861 | 2094 мс | 2156 мс | 6172 мс |
|
||
|
||
Rolling update запускался в PowerShell `Start-Job`; после 15 секунд тест был `Running`, затем по очереди выполнялось пересоздание реплик. На первом ПК `api1` восстановилась за 7.6 с, `api2` за 6.9 с; на втором — за 7.1 с и 7.5 с соответственно. `Wait-Job` оба раза вернул JSON с нулём ошибок и состоянием `Completed`. Эти результаты подтверждают замену контейнеров под нагрузкой, но не являются тестом обновления на новую версию кода или несовместимой схемы БД.
|
||
|
||
Фактические значения failover в автоматических прогонах:
|
||
|
||
| Остановленная реплика | Успешные записи | Неуспешные попытки | Первое восстановление записи |
|
||
| --- | ---: | ---: | ---: |
|
||
| api1, прогон 1 | 8 | 0 | 6.281 с |
|
||
| api1, прогон 2 | 6 | 1 | 8.282 с |
|
||
| выбранная тестом реплика, второй ПК | 6 | 1 | 8.328 с |
|
||
| api2, ручной сценарий (первый ПК) | Smoke: PASS | Не измерено | Проверка readiness дала HTTP 200, время failover не измерялось |
|
||
| api2, ручной сценарий (второй ПК) | Smoke: PASS | Первый curl: 503 | После 503 smoke прошёл; время восстановления не измерялось |
|
||
|
||
На первом ПК остановку именно api2 подтвердил `docker compose ps`, а обработчик ответа имел `X-Instance-Id: api1`. На втором ПК остановка api2 подтверждена выводом `docker compose stop`, первый readiness-запрос вернул 503 от HAProxy, последующий smoke прошёл. Ручной сценарий не даёт количественной оценки RPS или задержки восстановления для api2.
|
||
|
||
`tests/load.py` использует closed-loop нагрузку без автоматических повторов: измерение включает клиентские задержки и может страдать coordinated omission. p50/p95/p99 относятся только к успешным HTTP-ответам. На обоих компьютерах медиана осталась около 2.1 с; это делает нехватку RAM первого ПК менее убедительной единственной причиной. Задержку не профилировали, узкое место не установлено.
|
||
|
||
### Ограничения результатов
|
||
|
||
- PostgreSQL, Redis и балансировщик представлены одним экземпляром; отказ всего хоста и потеря volumes не покрываются.
|
||
- При остановке api2 проверены работоспособность и публичный smoke, но отдельное инструментальное время восстановления и RPS этой реплики не фиксировались. На втором ПК первый readiness после остановки вернул 503, поэтому непрерывную безошибочную доступность в этом сценарии не заявляем.
|
||
- Приведены результаты двух Windows-хостов при конкретном closed-loop профиле нагрузки; Linux-испытание не проводилось.
|