Files
samsik eb9c378b9c Собрать стенд lab3 с двумя репликами API за Traefik.
Общие PostgreSQL, Valkey и идемпотентность сообщений нужны, чтобы чтение и запись переживали остановку одной реплики.
2026-10-23 01:14:48 +03:00

167 lines
19 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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. Проверка ниже выполнена в WSL Ubuntu 22.04: Docker 29.1.3, Compose 2.40.3, Python 3.10. На Windows у `python` без `PYTHONUTF8=1` публичный `make check` может не прочитать `openapi.json` в кодировке cp1251; в Linux/WSL это не требуется.
```sh
git clone <url-этого-форка>
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`.
Готовность: `GET http://127.0.0.1:8080/health/ready` возвращает `{"status":"ok"}`. Порт 8080 опубликован только у `lb` и только на 127.0.0.1. Миграции применяет одноразовый сервис `migrate` до старта реплик. Повторный запуск не вставляет данные второй раз: версии лежат в `schema_migrations` (`001_init.sql`, `002_idempotency.sql`).
Проверки:
```sh
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
python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
python3 tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080
python3 scripts/grade4_probe.py
```
После failover одна реплика остаётся остановленной. Вернуть её:
```sh
sh scripts/restore-api.sh
```
Остановка без удаления данных:
```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, 20 CPU на машине, лимиты контейнеров — из таблицы выше. Нагрузка — closed-loop POST, concurrency 4, timeout клиента 3 с, без повторов на клиенте. Это подтверждения HTTP, не замер предела БД. Дата прогона: 2026-10-23.
| Критерий 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 | вывод в той же сессии, контракт не менялся |
| Две реплики, один вход, общая БД и сессии | `docker compose ps`, 30 GET `/users/me` | Два разных `X-Instance-Id` на одной сессии. Порт только у lb. Postgres и Valkey без портов на хосте | evidence/level4.txt, evidence/grade4.json |
| Отказ одной реплики ≤ 10 с | `tests/resilience.py --mode failover --action-script scripts/stop-one.sh` | 2 реплики до отказа; 139 успешных записей; 4 ошибки; первое успешное восстановление 3.56 с. `api-3` остался Exited, `api-4` 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.70 с и 3.81 с. После возврата hook целевой id в успешных ответах отсутствует | evidence/grade4.json |
| По очереди остановить каждую реплику, собрать RPS и ошибки | `python3 scripts/grade4_probe.py` | База: 397 rps, 0 ошибок, p50 4.3 мс, p95 59 мс. Отказ первой: 171 rps, 154 ошибки за 9.7 с, чужая реплика ответила через 0.034 с, свой id вернулся через 5.3 с после start. Отказ второй: 172 rps, 40 ошибок, чужая реплика через 0.003 с, восстановление id 6.1 с | 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, 34.9 с, 12894 успеха, 80 ошибок (0.6%), 370 rps. Образ сменился с `sha256:d1cb2d180884` на `sha256:3ba24670218f`. В окне видны и старые, и новые id | evidence/grade4.json |
| Миграции один раз и совместимы | `select version from schema_migrations` | Две строки: `001_init.sql`, `002_idempotency.sql`. API миграции не запускает. 002 только добавляет таблицу | этот отчёт |
## Эксперименты и отказы
Гипотеза: при остановке одной из двух реплик живая продолжит чтение и запись быстрее чем за 10 с, а один `Idempotency-Key` не создаст второе сообщение даже при параллельных POST.
Профиль: closed-loop POST сообщений, 4 потока, timeout 3 с, без клиентских retry. Прогрев — 8 с baseline. Окно отказа — время `docker stop` плюс 6 с. Rolling шёл под той же нагрузкой 35 с. Повтор одного прогона. Аппаратные лимиты — таблица сервисов, не вся машина (20 CPU, память WSL около 16 GiB).
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| Baseline, обе реплики | Оба id, ошибки около нуля | 3182 успеха, 0 ошибок, 397 rps, p50/p95/p99 = 4.3/59/68 мс | — |
| `stop-one.sh` для `4cd3b03e049d` | Запись продолжается на второй реплике, ключ не двоит | 1664 успеха, 154 ошибки (8.5%), 171 rps. После возврата hook целевого id в успехах нет | Успех на другой реплике через 0.034 с от старта stop. Тот же id снова виден через 5.3 с после restore. Потери подтверждённых сообщений нет |
| `stop-one.sh` для `ee551154827e` | То же для второй реплики | 1693 успеха, 40 ошибок (2.3%), 172 rps | 0.003 с до чужой реплики, 6.1 с до возврата своего id |
| Публичный failover | ≥2 id до отказа, восстановление ≤ 10 с, остановленная реплика не обслуживает | 2 id, 139 успехов, 4 ошибки, first_recovery 3.56 с. `api-3` Exited, `api-4` healthy | 3.56 с от старта hook. Подтверждённые сообщения и сессия на месте |
| Rolling update под нагрузкой | Поочерёдная замена, сервис остаётся доступен | exit 0, 80 ошибок на 12894 успеха, образ сменился | Окно 34.9 с, rps 370. Дублей из-за замены не измерялось отдельно: каждая запись нагрузки имеет свой ключ |
| Рестарт api+postgres+valkey | Старый токен и сообщение живы, volume на месте | PASS публичного persistence | Volumes не удалялись |
Падение rps примерно вдвое при одной реплике совпадает с тем, что упор этого профиля — CPU API, а не отказ LB. 154 ошибки в первом отказе — запросы, которые попали в реплику в первые секунды drain, пока Traefik ещё не снял её с балансировки. Клиент их не повторял; в публичном тесте неопределённый POST повторяется с тем же ключом, дубля нет.
## Ограничения и следующие шаги
Выдерживается остановка одного процесса API при живых LB, PostgreSQL и Valkey. Не выдерживается отказ узла, отказ самого LB и отказ PostgreSQL: это одна машина и одна БД. Падение Valkey делает `/health/ready` равным 503, потому что без общего хранилища сессий реплики разошлись бы.
Valkey без пароля и пароль БД в переменных compose — упрощение локального стенда. Сокет Docker у Traefik даёт балансировщику право читать состояние контейнеров; наружу этот сокет не публикуется.
Просроченные ключи идемпотентности удаляются при следующем использовании того же ключа, а не фоновой уборкой. `scripts/rolling-update.sh` вызывает `docker build`; на Docker 29 этот путь печатает предупреждение про legacy builder, образ при этом собирается и подменяется, что видно по смене sha256. Схема во время rolling не мигрирует.
397 rps — closed-loop с четырьмя потоками на localhost, с coordinated omission. Это не предел стенда и не результат трека 5.