forked from mtusi2026/mtusi2026lab3
205 lines
21 KiB
Markdown
205 lines
21 KiB
Markdown
# Отчёт — лабораторная 3
|
||
|
||
- Автор, группа: Боцоев Арсен, БВТ2303
|
||
- Целевая оценка: 4
|
||
- Commit/PR: TODO после публикации
|
||
- Использованные источники, библиотеки и помощь ИИ: PostgreSQL advisory lock, Traefik Docker provider, RFC 7617, hashlib.scrypt, psycopg 3, redis-py. Реализацию сервера, Compose и проверок помог собрать ИИ в Cursor.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Нужны Docker Engine 24+ с Compose v2 и Python 3.9+ для публичных тестов. Приложение в контейнере — Python 3.12.6. Команды ниже — для `sh` в Linux или WSL; из PowerShell блок целиком не выполняется. Порт 8080 на `127.0.0.1` должен быть свободен: его публикует только `lb`. Проверка ниже выполнена в WSL Ubuntu 26.04: Docker 29.4.2, Compose 5.1.3, Python 3.14.4. На Windows у `python` без `PYTHONUTF8=1` публичный `make check` может не прочитать `openapi.json` в кодировке cp1251; в Linux/WSL это не требуется.
|
||
|
||
```sh
|
||
cd mtusi2026lab3
|
||
cp .env.example .env
|
||
# в .env учебный POSTGRES_PASSWORD, файл не коммитить
|
||
chmod +x scripts/up.sh scripts/restart.sh scripts/stop-one.sh scripts/restore-api.sh scripts/rolling-update.sh
|
||
docker compose --env-file .env -f compose.yaml config --quiet
|
||
docker compose --env-file .env -f compose.yaml up -d --build --scale api=2 --remove-orphans
|
||
```
|
||
|
||
Тот же запуск одной командой: `sh scripts/up.sh`. Миграции применяет одноразовый сервис `migrate` до старта реплик.
|
||
|
||
Дальше один сценарий. Сначала дождаться готовности и увидеть две реплики API без порта на хосте: наружу только `127.0.0.1:8080` у `lb`. Затем проверки уровня 3. После persistence — повтор миграций: в `schema_migrations` остаются две строки, по одной на `001_init.sql` и `002_idempotency.sql`. Failover оставляет одну реплику остановленной; `docker compose ps` это показывает. Перед `grade4_probe.py` её нужно поднять и дождаться, пока обе снова healthy: probe сам останавливает каждую реплику по очереди, собирает RPS и делает rolling update, и для старта ему нужны оба `X-Instance-Id`. Probe перезаписывает `evidence/grade4.json`.
|
||
|
||
```sh
|
||
python3 - <<'PY'
|
||
import time
|
||
import urllib.request
|
||
deadline = time.time() + 120
|
||
while True:
|
||
try:
|
||
body = urllib.request.urlopen("http://127.0.0.1:8080/health/ready", timeout=2).read().decode()
|
||
except Exception:
|
||
if time.time() > deadline:
|
||
raise SystemExit("GET /health/ready не стал 200 за 120 с")
|
||
time.sleep(2)
|
||
continue
|
||
print(body)
|
||
break
|
||
PY
|
||
docker compose --env-file .env -f compose.yaml ps
|
||
|
||
# make check и make test
|
||
python3 scripts/check_contract.py
|
||
python3 tests/smoke.py --base-url http://127.0.0.1:8080
|
||
python3 tests/student_level4.py --base-url http://127.0.0.1:8080
|
||
# make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
|
||
|
||
docker compose --env-file .env -f compose.yaml run --rm --no-deps migrate
|
||
docker compose --env-file .env -f compose.yaml exec -T postgres \
|
||
sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "SELECT version, count(*) FROM schema_migrations GROUP BY version ORDER BY version;"'
|
||
|
||
# make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
python3 tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080
|
||
docker compose --env-file .env -f compose.yaml ps
|
||
sh scripts/restore-api.sh
|
||
i=0
|
||
n=0
|
||
while [ "$i" -lt 40 ]; do
|
||
n=0
|
||
for id in $(docker compose --env-file .env -f compose.yaml ps -q api); do
|
||
status=$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}' "$id")
|
||
if [ "$status" = "healthy" ]; then
|
||
n=$((n + 1))
|
||
fi
|
||
done
|
||
if [ "$n" -ge 2 ]; then
|
||
break
|
||
fi
|
||
i=$((i + 1))
|
||
sleep 1
|
||
done
|
||
if [ "$n" -lt 2 ]; then
|
||
echo "две реплики api не стали healthy" >&2
|
||
exit 1
|
||
fi
|
||
python3 scripts/grade4_probe.py
|
||
```
|
||
|
||
Остановка без удаления данных:
|
||
|
||
```sh
|
||
docker compose --env-file .env -f compose.yaml stop
|
||
```
|
||
|
||
Удаление учебных данных вместе с volumes:
|
||
|
||
```sh
|
||
docker compose --env-file .env -f compose.yaml down -v
|
||
```
|
||
|
||
Образы закреплены тегами: `python:3.12.6-slim-bookworm`, `postgres:16.6-bookworm`, `valkey/valkey:8.0.2`, `traefik:v3.7.16`. Зависимости Python закреплены в `requirements.txt`.
|
||
|
||
## Архитектура и решения
|
||
|
||
```
|
||
Клиент --HTTP--> Traefik (lb) --HTTP--> API ×2 (src/server.py)
|
||
|--SQL--> PostgreSQL
|
||
+--сессия--> Valkey (AOF + volume)
|
||
```
|
||
|
||
Из lab2 перенесены пользователи, чаты, членство, сообщения, keyset-пагинация, формат ошибок, `X-Request-Id`, Basic/Bearer, scrypt и сессии в Valkey. Локальной памяти, от которой зависит корректность, у API нет: сессии в общем Valkey, сообщения и ключи идемпотентности в общем PostgreSQL. `X-Instance-Id` — hostname контейнера, стабильный на время жизни процесса. В Compose hostname совпадает с коротким id контейнера, поэтому `scripts/stop-one.sh` находит реплику по `TARGET_INSTANCE_ID`.
|
||
|
||
Sticky cookie нет. Traefik распределяет запросы по живым контейнерам сервиса `api`. Адреса он берёт из Docker API и обновляет по событиям start/die, а не из одного закэшированного DNS-ответа. Сокет Docker смонтирован только в `lb` и только на чтение.
|
||
|
||
### Соответствие .env
|
||
|
||
| Переменная | Куда попадает |
|
||
| --- | --- |
|
||
| `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` | `postgres`; из них же `DATABASE_URL` у `migrate` и `api` |
|
||
| `SESSION_TTL_SECONDS` | API, TTL сессии в Valkey |
|
||
| `IDEMPOTENCY_TTL_SECONDS` | API, окно повторного ключа, по умолчанию 86400 |
|
||
| `DRAIN_SECONDS` | API, пауза после SIGTERM до закрытия сокета, по умолчанию 3 |
|
||
| `API_REPLICAS` | `scripts/up.sh` и `scripts/restore-api.sh`, масштаб сервиса `api` |
|
||
| `REDIS_URL` | задаёт compose только сервису `api`: `redis://valkey:6379/0` |
|
||
|
||
`INSTANCE_ID` в окружение реплик не передаётся: иначе обе получили бы один и тот же заголовок. `DATABASE_URL_FILE` и `CACHE_URL_FILE` приложение читает, если файл есть; этот стенд передаёт URL переменными и только тем сервисам, которым они нужны. Пароль Valkey нет: порт 6379 наружу не опубликован. Это учебное упрощение локального стенда.
|
||
|
||
### Идемпотентность
|
||
|
||
Область ключа: пользователь + `POST` + путь `/api/v1/chats/{id}/messages` + `Idempotency-Key`. Канонический вид тела — JSON с отсортированными ключами, где отсутствующий `attachment_ids` равен `[]`. В lab3 схема `CreateMessage` принимает только `text`; лишнее поле отклоняется с 400 до записи ключа, поэтому порядок ключей у валидного тела не создаёт второе сообщение.
|
||
|
||
Одинаковый ключ сериализуется `pg_advisory_xact_lock`. `INSERT` сообщения и `INSERT` в `idempotency_keys` — одна транзакция. Обрыв до COMMIT не оставляет ни сообщения, ни «окончательного» результата, поэтому тот же ключ можно безопасно повторить. Повтор того же канонического тела в течение TTL возвращает тот же 201 и ту же строку `messages`. Другое тело — 409. На повторе снова проверяются сессия и членство в чате. Чужой чат и пустой текст ключ не занимают.
|
||
|
||
### Миграции
|
||
|
||
Их запускает только `migrate` (`python3 /app/migrate.py`), один процесс, под `pg_advisory_lock`. Реплики API миграции не выполняют. `002_idempotency.sql` добавляет таблицу и совместим с уже работающим кодом lab2: старый процесс эту таблицу не читает. Rolling update схему не меняет. Ломающее изменение колонки при ещё живых старых репликах этот стенд не поддерживает.
|
||
|
||
### Health, таймауты, SIGTERM
|
||
|
||
| Узел | Настройка |
|
||
| --- | --- |
|
||
| API `/health/live` | 200, пока процесс жив, в том числе во время drain |
|
||
| API `/health/ready` | 200, если не идёт остановка и доступны PostgreSQL и Valkey; иначе 503 |
|
||
| Traefik healthcheck | `GET /health/ready` каждые 1 с, timeout 1 с |
|
||
| Исключение backend | одна неуспешная проверка убирает реплику из балансировки |
|
||
| Верхняя оценка обнаружения | 1 с до следующей проверки + 1 с timeout = 2 с |
|
||
| Клиент и upstream Traefik | dial 1 с, ответ 8 с, idle 5 с / 1 с |
|
||
| SIGTERM API | сразу 503 на `/health/ready` и на новые бизнес-запросы; сокет закрывается через `DRAIN_SECONDS` (3 с) |
|
||
| `stop_grace_period` API | 10 с; `scripts/stop-one.sh` вызывает `docker stop -t 8` |
|
||
| Docker healthcheck API | `/health/ready`, интервал 2 с |
|
||
|
||
Пока реплика уже отдаёт 503, но ещё не вышла, Traefik перестаёт слать ей новые запросы. Краткие обрывы до этого момента возможны и измеряются ниже. `restart: unless-stopped` поднимает контейнер после падения процесса и не поднимает его после `docker stop`.
|
||
|
||
### Лимиты и порты
|
||
|
||
Проверено `docker inspect` во время `scripts/grade4_probe.py` (`evidence/grade4.json`, поле `container_limits`):
|
||
|
||
| Сервис | CPU | RAM | Порт на хосте |
|
||
| --- | --- | --- | --- |
|
||
| api | 0.50 | 256 MiB | нет |
|
||
| lb | 0.25 | 128 MiB | 127.0.0.1:8080 |
|
||
| postgres | 0.75 | 512 MiB | нет |
|
||
| valkey | 0.25 | 128 MiB | нет |
|
||
| migrate | 0.50 | 256 MiB | нет, одноразовый контейнер |
|
||
|
||
`container_name` нет, сервис `api` масштабируется `--scale`.
|
||
|
||
## Доказательства критериев
|
||
|
||
Стенд: WSL2, 16 CPU на машине, лимиты контейнеров — из таблицы выше. Нагрузка — closed-loop POST, concurrency 4, timeout клиента 3 с, без повторов на клиенте. Это подтверждения HTTP, не замер предела БД. Дата прогона: 2026-10-30.
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke | `python3 tests/smoke.py --base-url http://127.0.0.1:8080` | PASS | evidence/smoke.txt |
|
||
| Offline-структура | `python3 scripts/check_contract.py` | PASS | evidence/smoke.txt |
|
||
| Две реплики, один вход, общая БД и сессии | `docker compose ps`, 30 GET `/users/me` | Два разных `X-Instance-Id` на одной сессии: `2d295e897529`, `3770bdb4bd34`. Порт только у lb. Postgres и Valkey без портов на хосте | evidence/level4.txt, evidence/grade4.json |
|
||
| Отказ одной реплики ≤ 10 с | `tests/resilience.py --mode failover --action-script scripts/stop-one.sh` | 2 реплики до отказа; 136 успешных записей; 1 ошибка; первое успешное восстановление 3.76 с. `api-4` остался Exited, `api-3` healthy | evidence/failover.txt |
|
||
| Идемпотентность, в том числе гонка | `tests/student_level4.py` и блок parallel в probe | 8 параллельных POST, один id сообщения, оба instance id. Другое тело — 409. История без дубля | evidence/level4.txt, evidence/grade4.json |
|
||
| Сохранность токена и сообщений | `tests/resilience.py --mode persistence --action-script scripts/restart.sh` | PASS. Перезапущены api, postgres, valkey. Volumes `mtusi-lab3_pgdata` и `mtusi-lab3_valkeydata` на месте | evidence/persistence.txt |
|
||
| Health/readiness и SIGTERM согласованы, LB убирает backend | конфиг `infra/traefik.yml`, drain в `src/server.py`, probe | Период проверки 1 с, максимум обнаружения 2 с. Hook `docker stop` вернулся за 3.73 с и 3.68 с. После возврата hook целевой id в успешных ответах отсутствует | evidence/grade4.json |
|
||
| По очереди остановить каждую реплику, собрать RPS и ошибки | `python3 scripts/grade4_probe.py` | База: 117 rps, 0 ошибок, p50 11.6 мс, p95 97 мс. Отказ первой: 60 rps, 23 ошибки за 9.7 с, чужая реплика ответила через 0.028 с, свой id вернулся через 6.7 с после start. Отказ второй: 64 rps, 67 ошибок, чужая реплика через 0.038 с, восстановление id 5.9 с | evidence/grade4.json |
|
||
| Параллельный один ключ через разные реплики | 8 потоков в probe и student_level4 | `unique_message_ids=1`, оба instance id | evidence/grade4.json |
|
||
| CPU/RAM, нет обхода LB, нет container_name | `docker inspect` внутри probe | Лимиты из таблицы выше. У API `8080/tcp` без HostPort | evidence/grade4.json |
|
||
| Rolling update под нагрузкой | `scripts/rolling-update.sh` во время той же нагрузки | exit 0, 25.2 с, 2724 успеха, 154 ошибки (5.4%), 108 rps. Образ сменился с `sha256:677eedd39f22` на `sha256:1de321e159c5`. В окне видны и старые, и новые id | evidence/grade4.json |
|
||
| Миграции один раз и совместимы | `select version from schema_migrations` | Две строки, по одной на версию: `001_init.sql`, `002_idempotency.sql`. Повторный migrate строки не удвоил. API миграции не запускает. 002 только добавляет таблицу | evidence/persistence.txt |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Гипотеза: при остановке одной из двух реплик живая продолжит чтение и запись быстрее чем за 10 с, а один `Idempotency-Key` не создаст второе сообщение даже при параллельных POST.
|
||
|
||
Профиль: closed-loop POST сообщений, 4 потока, timeout 3 с, без клиентских retry. Прогрев — 8 с baseline. Окно отказа — время `docker stop` плюс 6 с. Rolling шёл под той же нагрузкой 25 с. Один прогон. Аппаратные лимиты — таблица сервисов, не вся машина (16 CPU, память WSL 7.5 GiB).
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| Baseline, обе реплики | Оба id, ошибки около нуля | 935 успехов, 0 ошибок, 117 rps, p50/p95/p99 = 11.6/97/173 мс | — |
|
||
| `stop-one.sh` для `2d295e897529` | Запись продолжается на второй реплике, ключ не двоит | 579 успехов, 23 ошибки (3.8%), 60 rps. После возврата hook целевого id в успехах нет | Успех на другой реплике через 0.028 с от старта stop. Тот же id снова виден через 6.7 с после restore. Потери подтверждённых сообщений нет |
|
||
| `stop-one.sh` для `3770bdb4bd34` | То же для второй реплики | 618 успехов, 67 ошибок (9.8%), 64 rps | 0.038 с до чужой реплики, 5.9 с до возврата своего id |
|
||
| Публичный failover | ≥2 id до отказа, восстановление ≤ 10 с, остановленная реплика не обслуживает | 2 id, 136 успехов, 1 ошибка, first_recovery 3.76 с. `api-4` Exited, `api-3` healthy | 3.76 с от старта hook. Подтверждённые сообщения и сессия на месте |
|
||
| Rolling update под нагрузкой | Поочерёдная замена, сервис остаётся доступен | exit 0, 154 ошибки на 2724 успеха, образ сменился | Окно 25.2 с, rps 108. Дублей из-за замены не измерялось отдельно: каждая запись нагрузки имеет свой ключ |
|
||
| Рестарт api+postgres+valkey | Старый токен и сообщение живы, volume на месте | PASS публичного persistence | Volumes не удалялись |
|
||
|
||
Падение rps примерно вдвое при одной реплике совпадает с тем, что упор этого профиля — CPU API, а не отказ LB. 23 и 67 ошибок в окнах отказа — запросы, которые попали в реплику в первые секунды drain, пока Traefik ещё не снял её с балансировки. Клиент их не повторял; в публичном тесте неопределённый POST повторяется с тем же ключом, дубля нет.
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
Выдерживается остановка одного процесса API при живых LB, PostgreSQL и Valkey. Не выдерживается отказ узла, отказ самого LB и отказ PostgreSQL: это одна машина и одна БД. Падение Valkey делает `/health/ready` равным 503, потому что без общего хранилища сессий реплики разошлись бы.
|
||
|
||
Valkey без пароля и пароль БД в переменных compose — упрощение локального стенда. Сокет Docker у Traefik даёт балансировщику право читать состояние контейнеров; наружу этот сокет не публикуется.
|
||
|
||
Просроченные ключи идемпотентности удаляются при следующем использовании того же ключа, а не фоновой уборкой. `scripts/rolling-update.sh` вызывает `docker build`. В этом прогоне сборка шла через BuildKit, образ подменился, что видно по смене sha256. Схема во время rolling не мигрирует.
|
||
|
||
117 rps — closed-loop с четырьмя потоками на localhost, с coordinated omission. Это не предел стенда и не результат трека 5.
|