forked from mtusi2026/mtusi2026lab3
ЛР 3: отчёт и итоговые доказательства (уровень 4)
This commit is contained in:
@@ -1,37 +1,131 @@
|
||||
# Отчёт — лабораторная 3
|
||||
|
||||
- Автор, группа: TODO
|
||||
- Целевая оценка; выбранный трек 5, если нужен: TODO
|
||||
- Commit/PR: TODO после публикации
|
||||
- Использованные источники, библиотеки и помощь ИИ: TODO
|
||||
- Автор, группа: Саргсян Сона, БВТ2302
|
||||
- Целевая оценка: 4
|
||||
- Commit/PR: заполнить после публикации
|
||||
- Использованные источники, библиотеки и помощь ИИ: Claude Code. Библиотеки: FastAPI, Pydantic, Uvicorn, asyncpg, argon2-cffi, redis-py (клиент Valkey). Код перенесён из собственной ветки `solution/bvt2302-sargsyan` лабораторной работы 2.
|
||||
|
||||
## Запуск из чистого clone
|
||||
|
||||
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
|
||||
Нужны Git, Docker (Compose v2) с запущенным daemon, Make, Python 3.9+ (публичные проверки и собственные тесты используют только стандартную библиотеку), `openssl`. Порт 8080 на localhost должен быть свободен.
|
||||
|
||||
Версии: Python 3.12.7 (образ `python:3.12.7-slim`, закреплён digest), FastAPI 0.115.2, Uvicorn 0.32.0, asyncpg 0.30.0, argon2-cffi 23.1.0, redis-py 5.2.1, PostgreSQL 16.6 (`postgres:16.6-alpine`), Valkey 8.0.1 (`valkey/valkey:8.0.1-alpine`), HAProxy 3.0.7 (`haproxy:3.0.7-alpine`). Железо: ноутбук MacBook на Docker Desktop, точные параметры хоста и VM не фиксировались; нагрузочный генератор работает на той же машине, что и стенд.
|
||||
|
||||
Действия оператора (один раз, секреты в Git не попадают):
|
||||
|
||||
```sh
|
||||
mkdir -p secrets
|
||||
PW=$(openssl rand -hex 24)
|
||||
printf '%s' "$PW" > secrets/postgres_password
|
||||
printf 'postgresql://messenger:%s@postgres:5432/messenger' "$PW" > secrets/database_url
|
||||
chmod 644 secrets/*
|
||||
cp .env.example .env
|
||||
chmod +x scripts/*.sh
|
||||
```
|
||||
|
||||
Права 644 нужны, чтобы пользователь `app` в контейнере прочитал секрет; допустимо только для локального стенда с синтетическими данными.
|
||||
|
||||
Сборка, миграции, запуск (одна последовательность):
|
||||
|
||||
```sh
|
||||
docker compose --env-file .env config --quiet
|
||||
docker compose --env-file .env up -d --build
|
||||
curl --fail --retry 30 --retry-connrefused --retry-delay 1 http://localhost:8080/health/ready
|
||||
```
|
||||
|
||||
Порядок старта задаёт Compose: PostgreSQL (healthy) → одноразовая задача `migrate` (завершается с кодом 0) → реплики `api` → `lb`. Миграции применяет только `migrate` (`python -m src.migrate`); реплики API миграции не запускают.
|
||||
|
||||
Проверки:
|
||||
|
||||
```sh
|
||||
make check
|
||||
make test
|
||||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh # затем: docker compose --env-file .env start api
|
||||
scripts/show-instances.sh
|
||||
python3 student_tests/test_idempotency_parallel.py
|
||||
scripts/run-failover-series.sh
|
||||
APP_VERSION=v1 docker compose --env-file .env up -d --build
|
||||
APP_VERSION=v2 docker compose --env-file .env build migrate
|
||||
APP_VERSION=v2 python3 student_tests/loadgen.py --duration 120 --action-script scripts/rolling-update.sh --action-at 10 --output evidence/load-rolling.json
|
||||
python3 student_tests/test_sigterm.py
|
||||
```
|
||||
|
||||
`make test-failover` останавливает реплику, которую тест выбрал по первому ответу, и оставляет её остановленной. Восстановление: `docker compose --env-file .env start api`. Тест выбирает цель детерминированно (roundrobin), чтобы проверить вторую реплику, перед запуском сдвигается чётность одним запросом `curl http://localhost:8080/health/live`.
|
||||
|
||||
Остановка с сохранением данных: `docker compose --env-file .env down`. Намеренное удаление учебных данных: `docker compose --env-file .env down -v`.
|
||||
|
||||
## Архитектура и решения
|
||||
|
||||
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
|
||||
```
|
||||
Клиент ──> HAProxy (127.0.0.1:8080, единственный опубликованный порт)
|
||||
│ проверка GET /health/ready раз в 1 с, адреса из Docker DNS
|
||||
├──> api (реплика 1) ──┐
|
||||
└──> api (реплика N) ──┼──> PostgreSQL 16 (volume pgdata) — источник истины
|
||||
└──> Valkey 8 (кэш сессий, без persistence)
|
||||
migrate (одноразово) ──> PostgreSQL
|
||||
```
|
||||
|
||||
| Роль | Service | Версия | Health/readiness | Volume | Сеть/порт | Credentials |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| API | `api` (N реплик) | собственный образ `mtusi-messenger:lab3` | Dockerfile HEALTHCHECK и `/health/ready` | нет (stateless) | `expose 8080`, наружу не опубликован | `database_url` (Compose secret, файл) |
|
||||
| Миграции | `migrate` | тот же образ | код завершения 0 | нет | внутренняя сеть | `database_url` |
|
||||
| БД | `postgres` | 16.6-alpine | `pg_isready` | `pgdata` | 5432 внутри сети | `postgres_password` (secret) |
|
||||
| Кэш сессий | `valkey` | 8.0.1-alpine | `valkey-cli ping` | нет | 6379 внутри сети | без пароля, только внутренняя сеть |
|
||||
| LB | `lb` | HAProxy 3.0.7 | активные проверки backend | нет | `127.0.0.1:8080` | нет |
|
||||
|
||||
**Источник истины.** PostgreSQL хранит пользователей, чаты, сообщения, сессии (SHA-256 токена, срок, отзыв) и ключи идемпотентности. Сессии общие для всех реплик, потому что лежат в PostgreSQL; Valkey лишь ускоряет проверку и недоступность кэша не ломает API (любой сбой считается промахом). Локального состояния в процессе API нет, sticky session не используются. Кэширования истории сообщений нет, поэтому подтверждённое сообщение видно следующему чтению через любую реплику.
|
||||
|
||||
**Идемпотентность отправки сообщения.** Таблица `idempotency_keys` с ключом `(user_id, method, path, idem_key)` и хешем тела. В одной транзакции: проверка членства, захват ключа (`INSERT ... ON CONFLICT`), вставка сообщения и привязка `message_id`. Параллельный запрос с тем же ключом ждёт коммита первого на уникальном индексе и затем возвращает то же сообщение. Другое тело при том же ключе даёт 409. При сбое транзакция откатывается вместе с ключом, поэтому 5xx не фиксируется как результат. Повтор заново проверяет сессию и доступ к чату. Ключи старше `IDEMPOTENCY_TTL_SECONDS` (24 ч) считаются свободными.
|
||||
|
||||
**Балансировка и отказ.** HAProxy проверяет `GET /health/ready` раз в секунду (`inter 1s`), исключает реплику после 2 неудач подряд (`fall 2`), возвращает после 2 успехов (`rise 2`), `timeout check 2s`. Максимальное время обнаружения отказа: 2 × 1 с + 2 с = 4 с. Адреса backend берутся из Docker DNS (`server-template api 1-8 api:8080`, обновление раз в секунду), поэтому новые и пересозданные реплики подхватываются без перезапуска LB. `option redispatch` и `retries 3` перенаправляют запрос на другую реплику, если соединение с выбранной не установилось.
|
||||
|
||||
**Readiness, таймауты, SIGTERM.** Критичная зависимость readiness — PostgreSQL (Valkey не критичен). При SIGTERM реплика сразу отвечает 503 на `/health/ready` и ещё `DRAIN_SECONDS=5` обслуживает запросы, пока LB её исключает; затем uvicorn завершается штатно (`--timeout-graceful-shutdown 8`). `stop_grace_period: 20s` вмещает drain и graceful-завершение (5 + до 8 с). Таймауты: пул БД и команды 5 с, кэш 0,5 с, LB: connect 1 с, server 10 с.
|
||||
|
||||
**Ресурсы и безопасность.** Лимиты (Compose `deploy.resources.limits`): API 0,5 CPU / 256 МБ на реплику (переменные `API_CPUS`, `API_MEM`), PostgreSQL 1,0 / 512 МБ, Valkey 0,25 / 128 МБ, LB 0,5 / 256 МБ, migrate 0,5 / 256 МБ. У API нет `container_name` и published-портов, число реплик задаёт `API_REPLICAS`. Пароль БД доступен только `postgres`, строка подключения только `migrate` и `api`.
|
||||
|
||||
**Миграции и rolling update.** `scripts/rolling-update.sh` собирает новый образ, один раз запускает `migrate`, затем по очереди: `docker stop -t 20` (graceful) → удаление → создание реплики из нового образа → ожидание healthy → пауза 5 с. Миграция `002_idempotency.sql` только добавляет таблицу, поэтому совместима со старой версией (подход expand/contract). Несовместимые изменения схемы (удаление или переименование колонок) потребовали бы разделения на два релиза; здесь они не выполнялись.
|
||||
|
||||
**Что перенесено из lab2.** Приложение, миграция `001`, Argon2id, сессии, Valkey-кэш, Dockerfile, собственные тесты. **Что изменено.** Миграции вынесены в отдельный сервис; добавлены `X-Instance-Id`, обязательный `Idempotency-Key`, drain и `X-App-Version`; compose с LB и репликами; `test_sigterm.py` приведён к новой семантике (readiness 503, затем закрытие порта).
|
||||
|
||||
**Переменные `.env.example`.** `APP_ENV`, `SESSION_TTL_SECONDS`, `API_REPLICAS` передаются в compose. `DATABASE_URL_FILE` задан в compose как путь к secret, `CACHE_URL` в compose как `redis://valkey:6379/0`. Переменные `APP_HOST`, `APP_PORT` заданы в Dockerfile. `SESSION_STORE=postgres` соответствует реализации (источник истины PostgreSQL, Valkey лишь кэш).
|
||||
|
||||
## Доказательства критериев
|
||||
|
||||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||||
| --- | --- | --- | --- |
|
||||
| Публичный smoke | make test | TODO | TODO |
|
||||
| Остальные пункты уровня 3 | TODO | TODO | TODO |
|
||||
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
|
||||
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
|
||||
|
||||
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
|
||||
| Публичный smoke | `make test` | PASS | `evidence/smoke.txt`, `evidence/smoke-level4.txt` |
|
||||
| Compose запускает ≥2 API, один LB, общие БД и сессии | `docker compose up -d --build`, `ps` | 2 реплики api, lb, postgres, valkey, migrate Exited (0) | `evidence/ps-before.txt` |
|
||||
| Разные реплики для одной сессии | `scripts/show-instances.sh` | 2 разных `X-Instance-Id`, по 5 запросов | `evidence/instances.txt` |
|
||||
| Отказ одной реплики ≤10 с | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`, для каждой реплики | 0 ошибок, восстановление 2,0 / 1,6 / 2,2 с | `evidence/failover-1.txt`, `failover-2.txt`, `failover-*-ps.txt`, `failover-level4.txt` |
|
||||
| Идемпотентность, повтор и переключение реплики | smoke и `student_tests/test_idempotency_parallel.py` | 5 раундов × 30 параллельных, 1 сообщение, другое тело → 409 | `evidence/idempotency-parallel.txt` |
|
||||
| Сохранность после рестарта | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | данные и токен сохранены | `evidence/persistence.txt`, `persistence-level4.txt`, `restart-before.txt`, `restart-after.txt` |
|
||||
| Уровень 4: health/readiness, SIGTERM, период и время обнаружения | `student_tests/test_sigterm.py`, конфиг HAProxy | readiness 503 за 0,06 с; выход за 5,3 с (idle) и 13,4 с (незавершённый POST), код 0; обнаружение ≤4 с | `evidence/sigterm-level4.txt`, `infra/haproxy/haproxy.cfg` |
|
||||
| Уровень 4: поочерёдная остановка с RPS, ошибками, восстановлением | `scripts/run-failover-series.sh` | см. таблицу ниже | `evidence/load-baseline.json`, `load-stop-0.json`, `load-stop-1.json` |
|
||||
| Уровень 4: лимиты, нет published-портов и container_name | `docker stats`, `compose.yaml` | лимиты применены | `evidence/docker-stats.txt` |
|
||||
| Уровень 4: rolling update под нагрузкой | `scripts/rolling-update.sh` под `loadgen.py` | 95 152 запроса, 0 ошибок | `evidence/load-rolling.json`, `rolling-ps.txt` |
|
||||
|
||||
## Эксперименты и отказы
|
||||
|
||||
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
|
||||
Профиль нагрузки (`student_tests/loadgen.py`): closed-loop, 8 потоков, POST сообщения с уникальным `Idempotency-Key` в один чат через LB, без прозрачных retry, таймаут 3 с. Базовая нагрузка 30 с, серия отказов по 40 с (отказ на 10-й секунде), rolling update 120 с. Прогрева отдельно не было, повторов по одному на сценарий. Сырые сводки сохранены в `evidence/*.json`, токены в них не попадают.
|
||||
|
||||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||||
| --- | --- | --- | --- |
|
||||
| TODO | TODO | TODO | TODO |
|
||||
| Базовая нагрузка, 2 реплики | стабильный RPS | 856 RPS, 25 691 запрос, 0 ошибок, p50/p95/p99 = 6,4 / 28,7 / 61,7 мс | — |
|
||||
| Остановка реплики 1 (`docker stop -t 2`) | запись продолжается на реплике 2 | 0 ошибок, 630 RPS за 40 с, p99 85,4 мс, макс. пауза 0,17 с | 0 с, данные не потеряны |
|
||||
| Остановка реплики 2 | то же | 0 ошибок, 635 RPS за 40 с, p99 81,2 мс, макс. пауза 0,22 с | 0 с, данные не потеряны |
|
||||
| `make test-failover` по каждой реплике | запись ≤10 с | 0 ошибок, восстановление 2,0 / 1,6 / 2,2 с | данные сохранены |
|
||||
| Rolling update v1 → v2 под нагрузкой | без потерь | 95 152 запроса, 0 ошибок, 793 RPS, p99 72,1 мс, макс. пауза 0,18 с; v1 виден до 31,4 с, v2 с 21,2 с | потерь нет |
|
||||
| 30 параллельных POST с одним ключом × 5 раундов | одно сообщение | все 201, один `id`, в истории 5 сообщений | дублей нет |
|
||||
|
||||
После потери реплики пропускная способность падает примерно с 856 до 560–630 RPS (одна реплика с лимитом 0,5 CPU). Нулевые ошибки объясняются тем, что остановленный контейнер перестаёт принимать соединения сразу, а HAProxy делает redispatch; переходный период обнаружения в этих прогонах клиент не заметил, но по настройкам он может достигать 4 с.
|
||||
|
||||
## Ограничения и следующие шаги
|
||||
|
||||
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
|
||||
- Один Docker-host: потеря узла останавливает всё. PostgreSQL, Valkey и HAProxy в единственном экземпляре, это SPOF; выдерживается только отказ одной API-реплики и её плановая замена. Отказ БД, LB и узла не заявляется.
|
||||
- Нагрузочный генератор closed-loop, на той же машине, что и стенд; возможна coordinated omission, один запуск на сценарий без повторов и доверительных интервалов, параметры хоста не зафиксированы. RPS нельзя переносить на другие машины. Измерялось только время ответа успешных запросов, ошибки считались отдельно.
|
||||
- HAProxy повторяет только неудачное соединение. Прерванный POST клиент повторяет сам с тем же `Idempotency-Key`; повторы создания чата и других POST без ключа не безопасны и не выполняются.
|
||||
- Просроченные записи `idempotency_keys` не удаляются (таблица растёт); для эксплуатации нужна фоновая очистка по `created_at`.
|
||||
- Пароль к Valkey не задан (допустимо только во внутренней сети учебного стенда), секреты имеют права 644.
|
||||
- Rolling update проверен для обратно совместимой миграции; несовместимые схемы не проверялись.
|
||||
- Трек уровня 5 не выполнялся.
|
||||
@@ -0,0 +1,7 @@
|
||||
NAME STATUS
|
||||
mtusi-lab3-api-3 Up 17 seconds (healthy)
|
||||
mtusi-lab3-api-4 Up 17 seconds (healthy)
|
||||
mtusi-lab3-lb-1 Up 23 minutes
|
||||
mtusi-lab3-migrate-1 Exited (0) 17 seconds ago
|
||||
mtusi-lab3-postgres-1 Up 23 seconds (healthy)
|
||||
mtusi-lab3-valkey-1 Up 23 seconds (healthy)
|
||||
@@ -0,0 +1,7 @@
|
||||
NAME STATUS
|
||||
mtusi-lab3-api-3 Up 4 minutes (healthy)
|
||||
mtusi-lab3-api-4 Up 3 minutes (healthy)
|
||||
mtusi-lab3-lb-1 Up 23 minutes
|
||||
mtusi-lab3-migrate-1 Exited (0) 3 minutes ago
|
||||
mtusi-lab3-postgres-1 Up 4 minutes (healthy)
|
||||
mtusi-lab3-valkey-1 Up 4 minutes (healthy)
|
||||
Reference in New Issue
Block a user