149 lines
15 KiB
Markdown
149 lines
15 KiB
Markdown
# Отчёт — лабораторная 3
|
||
|
||
- Автор, группа: Сергей Возжин, БПИ2301.
|
||
- Целевая оценка: 4; трек 5 не выбран.
|
||
- Commit/PR: коммит не создавался по условию выполнения; указать после публикации.
|
||
- Использованные источники: материалы и контракт репозитория, документация Docker Compose и HAProxy.
|
||
- Библиотеки: FastAPI, Uvicorn, SQLAlchemy, asyncpg, Alembic, redis-py, Argon2, pytest.
|
||
- Помощь ИИ: OpenAI Codex использовался для плана, реализации lab3, тестов, сценариев отказа и оформления отчёта; результат проверен исполняемыми тестами.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Требуются Docker Engine с Compose v2, Python 3.9+ для публичных тестов и свободный host-порт 8080. Проверенный стенд: Docker 28.0.4, Compose 2.34.0, API на Python 3.13.15. Образы: `python:3.13.15-slim`, `haproxy:3.2.26-alpine`, `postgres:17.4-alpine`, `redis:7.4.2-alpine`.
|
||
|
||
Создать локальную конфигурацию, не добавляя её в Git:
|
||
|
||
```sh
|
||
cp .env.example .env
|
||
```
|
||
|
||
Перед запуском заменить учебный пароль PostgreSQL в `.env` и ту же часть пароля в `DATABASE_URL`. Сам `.env` игнорируется Git. Все данные тестов должны быть синтетическими.
|
||
|
||
Проверить конфигурацию, собрать образы, однократно применить миграции и дождаться готовности:
|
||
|
||
```sh
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build --wait
|
||
docker compose --env-file .env ps
|
||
```
|
||
|
||
`migrate` выполняет `alembic upgrade head` один раз. Две реплики `api` стартуют только после успешной миграции и готовности Redis; HAProxy стартует после готовности API. Единственная публичная точка входа — `http://localhost:8080`.
|
||
|
||
Полный набор проверок:
|
||
|
||
```sh
|
||
python3 -m venv .venv
|
||
.venv/bin/python -m pip install -r requirements-dev.txt
|
||
make check
|
||
make validate PYTHON=.venv/bin/python
|
||
make test
|
||
make test-idempotency PYTHON=.venv/bin/python
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
```
|
||
|
||
После failover восстановить вторую реплику и дождаться готовности:
|
||
|
||
```sh
|
||
docker compose --env-file .env up -d --wait --wait-timeout 60 api lb
|
||
```
|
||
|
||
Для проверки другой реплики повторить `make test-failover` после восстановления первой. Для поочерёдной замены под нагрузкой запустить `tests/load.py`, параллельно выполнить `scripts/rolling-update.sh` и сохранить агрегаты.
|
||
|
||
Безопасная остановка с сохранением named volumes:
|
||
|
||
```sh
|
||
docker compose --env-file .env down
|
||
```
|
||
|
||
Намеренное необратимое удаление всех учебных данных выполняется только оператором:
|
||
|
||
```sh
|
||
docker compose --env-file .env down -v
|
||
```
|
||
|
||
## Архитектура и решения
|
||
|
||
```text
|
||
HTTP client
|
||
|
|
||
v
|
||
HAProxy :8080
|
||
|
|
||
+-- round-robin --> API replica 1 --+
|
||
| +--> PostgreSQL
|
||
+-- round-robin --> API replica 2 --+--> Redis sessions
|
||
```
|
||
|
||
PostgreSQL — источник истины для пользователей, чатов, участников и сообщений. Redis — общее хранилище действующих сессий с AOF. Локального значимого состояния у API нет; sticky sessions не используются.
|
||
|
||
Из lab2 перенесены REST API, PostgreSQL, Redis-сессии, password KDF и миграции. В lab3 добавлены HAProxy, две API-реплики, `X-Instance-Id`, обязательный `Idempotency-Key`, конкурентная проверка и сценарии отказа/замены.
|
||
|
||
Каждый API-процесс один раз берёт `X-Instance-Id` из hostname контейнера. Middleware добавляет его во все созданные API ответы. Значение меняется при замене контейнера.
|
||
|
||
Идемпотентность сообщения хранится в PostgreSQL. Уникальность `(sender_id, chat_id, idempotency_key)` соответствует области пользователь + метод отправки сообщения + путь чата + ключ. `INSERT ... ON CONFLICT DO NOTHING` и чтение существующей строки выполняются в одной транзакции. Одинаковое тело возвращает исходный `201 Message`, другое тело — `409`. Ограничение хранится дольше обязательных 24 часов.
|
||
|
||
Миграция выполняется отдельно. Поле `idempotency_key` nullable: старая версия может продолжать писать `NULL`, новая читает старые записи. Создание unique constraint может блокировать большую production-таблицу; это ограничение учебной миграции описано и не маскируется.
|
||
|
||
HAProxy использует round-robin и Docker DNS `127.0.0.11`. `/health/ready` проверяется каждую секунду с `fall 2`, `rise 2`, `timeout check 2s`. При быстром отказе типичное исключение занимает 2–3 секунды; консервативная верхняя оценка с двумя полными timeout — около 6 секунд. Наблюдавшееся восстановление записи — 2,560–3,248 секунды, что меньше требуемых 10 секунд.
|
||
|
||
Таймауты HAProxy: connect/check 2 секунды, client/server 30 секунд. Uvicorn прекращает принимать новые соединения по SIGTERM, имеет graceful shutdown 5 секунд, Compose даёт API `stop_grace_period` 10 секунд.
|
||
|
||
Лимиты контейнеров:
|
||
|
||
| Сервис | CPU | RAM |
|
||
| --- | ---: | ---: |
|
||
| API, каждая реплика | 0,5 | 256 MiB |
|
||
| HAProxy | 0,25 | 128 MiB |
|
||
| PostgreSQL | 1,0 | 512 MiB |
|
||
| Redis | 0,25 | 128 MiB |
|
||
| migrate | 0,5 | 256 MiB |
|
||
|
||
Наружу опубликован только порт HAProxy. PostgreSQL, Redis и API доступны только в Compose-сети. `DATABASE_URL` получают только API и migrate; настройки PostgreSQL — только сам PostgreSQL. `container_name` отсутствует.
|
||
|
||
Переменные `.env.example`: `APP_PORT` задаёт host-порт HAProxy; `POSTGRES_*` настраивают PostgreSQL; `DATABASE_URL` используют API/migrate; `REDIS_URL` используют API/migrate; `SESSION_TTL_SECONDS` задаёт TTL серверной сессии; `LOG_LEVEL` задаёт логирование API. `APP_HOST` и `APP_ENV` оставлены как описательные учебные настройки и приложением не читаются.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Доказательство |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke | `make test` | `PASS: lab3 public API scenario` | `evidence/results.md` |
|
||
| Две реплики и одна точка входа | 20 запросов через `localhost:8080`, `docker compose ps` | два `X-Instance-Id`; host-порт есть только у HAProxy | `evidence/results.md` |
|
||
| Общая сессия | smoke/idempotency через HAProxy | одна Bearer-сессия работает на обеих репликах | `evidence/results.md` |
|
||
| Общая идемпотентность | `make test-idempotency PYTHON=.venv/bin/python` | 20 конкурентных запросов, две реплики, одно сообщение; `5 passed` | `evidence/results.md` |
|
||
| Persistence | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | данные и прежний token доступны после рестарта API/PostgreSQL/Redis | `evidence/results.md` |
|
||
| Отказ первой реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | восстановление 3,248 с; 111 успешных записей за 15 с (≈7,40 RPS), 1 переходная ошибка | `evidence/results.md` |
|
||
| Отказ второй реплики | восстановление первой и повтор failover | восстановление 2,560 с; 110 успешных записей за 15 с (≈7,33 RPS), 1 переходная ошибка | `evidence/results.md` |
|
||
| Health/timeouts/SIGTERM | HAProxy checks и остановка выбранного контейнера | backend исключён, другая реплика продолжила чтение/запись | `evidence/results.md` |
|
||
| CPU/RAM и закрытые порты | `docker compose ps`, `docker stats --no-stream` | лимиты применены; наружу опубликован только 8080 HAProxy | `evidence/results.md` |
|
||
| Поочерёдная замена | `scripts/rolling-update.sh` во время `tests/load.py` | обе реплики получили новые container ID, 10 512 успешных запросов, 0 ошибок | `evidence/rolling-update.md`, `evidence/rolling-update-load.json` |
|
||
|
||
Трек оценки 5 не заявлен.
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Проверяемое ожидание: остановка любой одной API-реплики не приводит к потере подтверждённых сообщений или сессии, а новые чтения/записи возобновляются не позднее 10 секунд.
|
||
|
||
Аппаратная конфигурация локального стенда: Apple M4 Pro, 12 CPU cores, 24 GB RAM; Docker Desktop. Основной профиль — closed-loop POST сообщений, 30 секунд, concurrency 4, без автоматических retry и отдельного временного прогрева. Bootstrap выполняется до измеряемого интервала. После профиля: 39 пользователей, 13 чатов, 18 448 сообщений, PostgreSQL 14 MB.
|
||
|
||
Основной прогон: 9807 успешных запросов, 0 ошибок, 326,771 successful RPS, p50/p95/p99 6,436/52,344/63,559 мс. CPU/RAM по двум срезам приведены в `evidence/results.md`; обе API-реплики использовали около 50–52% CPU и 66–76 MiB RAM каждая.
|
||
|
||
Числа двух failover-запусков взяты из JSON summary, который печатает `tests/resilience.py`: `successful_writes`, `failed_attempts` и `first_recovery_seconds`. Приблизительный RPS рассчитан как число успешных записей, делённое на 15 секунд нагрузки. Результат persistence взят из успешного завершения того же теста в режиме `persistence`. Числа поочерёдной замены взяты из `evidence/rolling-update-load.json`, записанного `tests/load.py` во время работы `scripts/rolling-update.sh`.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| Restart API + PostgreSQL + Redis | данные и token сохраняются | persistence PASS | время отдельно не замерялось; потерь нет |
|
||
| Остановка первой API-реплики | HAProxy оставляет вторую | 111 записей за 15 с (≈7,40 RPS), 1 краткая ошибка | 3,248 с; потерь и дублей нет |
|
||
| Остановка второй после восстановления первой | симметричный failover | 110 записей за 15 с (≈7,33 RPS), 1 краткая ошибка | 2,560 с; потерь и дублей нет |
|
||
| Поочерёдная замена двух API | трафик продолжается | 10 512 успешных запросов, 0 ошибок | явного перерыва не наблюдалось |
|
||
|
||
`tests/load.py` — простой closed-loop генератор, ограниченный клиентом и подверженный coordinated omission. Перцентили учитывают только успешные запросы. Эти цифры описывают конкретный учебный стенд и не объявляются максимальной производительностью.
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
Стенд выдерживает остановку одного API-процесса при работающих HAProxy, второй API-реплике, PostgreSQL, Redis и Docker-host. Он не выдерживает потерю единственного HAProxy, PostgreSQL, Redis или всего host: это осознанные SPOF лабораторной работы.
|
||
|
||
HAProxy и хранилища не реплицированы. Redis AOF снижает риск потери сессий при штатном перезапуске, но не является HA. Docker Compose обеспечивает локальную воспроизводимость, а не перенос контейнеров между узлами. HTTP используется только локально с синтетическими данными; TLS здесь не заявлен. Универсальная идемпотентность остальных POST, WebSocket, UI, мониторинг и требования оценки 5 намеренно не реализованы.
|
||
|
||
Следующие возможные улучшения, не входящие в оценку 4: несколько Docker-узлов, HA для LB/БД/Redis, online-создание индекса на большой таблице и более строгий open-loop нагрузочный генератор.
|