Общие PostgreSQL, Valkey и идемпотентность сообщений нужны, чтобы чтение и запись переживали остановку одной реплики.
167 lines
19 KiB
Markdown
167 lines
19 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. Проверка ниже выполнена в 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.
|