forked from mtusi2026/mtusi2026lab4
182 lines
24 KiB
Markdown
182 lines
24 KiB
Markdown
# Отчёт — лабораторная 3
|
||
|
||
- Автор, группа: Савельев Иван, БВТ2304.
|
||
- Целевая оценка: **4**, весь уровень 3 и все пункты уровня 4. Треки оценки 5 не заявлены.
|
||
- Решение: Docker Compose + HAProxy, две реплики FastAPI, общий PostgreSQL и Valkey.
|
||
- Commit/PR: после публикации. Локальные проверки относятся к рабочим изменениям поверх `source_commit` из `evidence/lab3-checks.json`.
|
||
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Нужны Docker Engine с Compose v2, Python 3.11, Bash и make. Для демонстрации `demo.sh` также нужны curl и jq. Проверено на Docker Engine 29.0.1, Compose 2.40.3, macOS arm64. Команды выполнять из корня репозитория:
|
||
|
||
```sh
|
||
python3 -m venv .venv
|
||
.venv/bin/python -m pip install -r requirements.txt -r requirements-dev.txt
|
||
./scripts/start.sh
|
||
./scripts/check.sh
|
||
./scripts/demo.sh
|
||
```
|
||
|
||
`start.sh` создаёт локальные `.env` и `secrets/`, собирает образ, поднимает PostgreSQL и Valkey, выполняет отдельный сервис `migrate`, запускает две API-реплики и HAProxy. API ожидают успешного завершения миграций. Скрипт возвращает управление после проверки обеих реплик через LB. Основной адрес — `http://localhost:8080`.
|
||
|
||
Пароль PostgreSQL генерируется случайно в `secrets/postgres_password`; DSN и URL Valkey находятся в `secrets/database_url` и `secrets/cache_url`. Существующие значения не перезаписываются. Каталог имеет права 0700, файлы — 0444 для чтения пользователем контейнера 10001. `.env`, `secrets/`, `.venv` исключены из Git и Docker build context. `.env.example` содержит настройки и пути, без значений секретов.
|
||
|
||
| Переменная | Использование |
|
||
| --- | --- |
|
||
| APP_HOST, APP_PORT | Адрес API внутри контейнера: 0.0.0.0:8080 |
|
||
| HOST_PORT | Порт единственного публичного входа HAProxy на 127.0.0.1, по умолчанию 8080 |
|
||
| API_REPLICAS | Количество реплик сервиса api, по умолчанию 2; конфигурация LB содержит 10 мест |
|
||
| SESSION_STORE | valkey, общее хранилище серверных сессий |
|
||
| SESSION_TTL_SECONDS | TTL новой сессии, по умолчанию 3600; рестарт TTL не продлевает |
|
||
| DATABASE_URL_FILE, CACHE_URL_FILE | Пути к Docker secrets |
|
||
| IDEMPOTENCY_TTL_SECONDS | Срок результата повтора, по умолчанию 86400, меньше 24 часов запрещено |
|
||
| APP_ENV | Учебная метка окружения; поведение приложения не переключает |
|
||
|
||
Если порт занят, например стендом lab2:
|
||
|
||
```sh
|
||
HOST_PORT=8081 ./scripts/start.sh
|
||
BASE_URL=http://localhost:8081 ./scripts/check.sh
|
||
```
|
||
|
||
Для дальнейших команд с нестандартным портом сохранить `HOST_PORT=8081` в `.env` или передавать его в окружении. Для HTTP-проверок передавать соответствующий `BASE_URL`.
|
||
|
||
```sh
|
||
docker compose ps -a
|
||
docker compose logs --tail 30 api lb
|
||
./scripts/restart.sh # API, PostgreSQL, Valkey и LB; volumes сохраняются
|
||
./scripts/stop.sh # удаление контейнеров и сети с сохранением volumes
|
||
|
||
# Только для намеренного удаления учебных данных текущего Compose project:
|
||
docker compose down --volumes
|
||
```
|
||
|
||
Compose project `mtusi-lab3` отделён от lab2. Тестовый сценарий использует своё случайное имя и порт; в конце удаляет только свои тестовые контейнеры и volumes.
|
||
|
||
## Архитектура и перенос из lab2
|
||
|
||
```text
|
||
Клиент → HAProxy :8080 → api × 2 → PostgreSQL (данные и результаты повторов)
|
||
↘ Valkey (общие Bearer-сессии)
|
||
Отдельный migrate → PostgreSQL; завершается до первого запуска API
|
||
```
|
||
|
||
Сохранены пользователи, Argon2id, Basic-вход, Bearer-сессии с TTL и отзывом, чаты, проверки доступа, сообщения, единые ошибки, X-Request-Id и keyset-пагинация. PostgreSQL остаётся источником истины для данных. Valkey хранит SHA-256 токена → пользователя и время окончания, с AOF `appendfsync always`, `noeviction` и постоянным volume. Подтверждённые данные и действующие сессии переживают обычный рестарт. Локального состояния, от которого зависит корректность, в API нет.
|
||
|
||
Добавлены `X-Instance-Id`, общая идемпотентность, LB и управление репликами. `X-Instance-Id` равен hostname контейнера и стабилен в течение жизни процесса. В доказательствах он сопоставлен с настоящим container ID; заголовок не подменяется балансировщиком. Любой ответ, сформированный API, включая health и ошибки, содержит оба служебных заголовка.
|
||
|
||
HAProxy использует round robin без sticky session. `server-template` получает адреса масштабируемого сервиса `api` из Docker DNS `127.0.0.11`; записи переопрашиваются, устаревшие адреса удаляются. `hold valid/obsolete=1s`, повтор разрешения — 1s. Новые IP после пересоздания обнаруживаются без рестарта LB. `wait-ready.sh` проверяет Docker health всех работающих API и наблюдает каждую через LB.
|
||
|
||
API не публикуют порты на хост, работают от UID/GID 10001, без volumes данных и без `container_name`. Только LB публикует порт. Секрет PostgreSQL доступен БД; DSN — API и мигратору; URL Valkey — только API. LB не получает секреты. PostgreSQL и Valkey используют отдельные именованные volumes.
|
||
|
||
| Контейнер | CPU | RAM |
|
||
| --- | ---: | ---: |
|
||
| Каждый API | 1 | 256 MiB |
|
||
| HAProxy | 0.5 | 64 MiB |
|
||
| PostgreSQL | 1 | 512 MiB |
|
||
| Valkey | 0.5 | 128 MiB |
|
||
| Одноразовый migrate | 1 | 256 MiB |
|
||
|
||
## Готовность, таймауты и SIGTERM
|
||
|
||
`/health/live` проверяет жизнь процесса. `/health/ready` проверяет PostgreSQL и Valkey: обе зависимости критичны для обязательного синхронного пути. При отказе любой зависимости live остаётся 200, ready становится 503. При старте API также проверяет наличие и checksum всех миграций, не выполняя DDL.
|
||
|
||
HAProxy проверяет `/health/ready` каждую 1 секунду. Два последовательных неуспеха исключают backend (`fall 2`), два успеха возвращают (`rise 2`). Таймаут подключения — 1s, ответа healthcheck — 1s. Консервативная верхняя оценка обнаружения отказа по этим настройкам — **6 секунд**: ожидание ближайшей проверки, два подключения/ответа и интервал между ними; задержки планирования ОС в оценку не входят. Отказ с немедленным connection refused обычно обнаруживается быстрее. Это укладывается в требование восстановления за 10 секунд.
|
||
|
||
Остальные таймауты HAProxy: server 8s, client 10s, чтение HTTP-заголовков 5s. `retries 1` относится к установлению backend-соединения; повторов уже отправленных HTTP POST по статусам не включено. Клиент повторяет неопределённый POST сообщения с исходным ключом.
|
||
|
||
API является PID 1. При SIGTERM Uvicorn прекращает приём новых соединений, даёт текущим запросам до 5 секунд и закрывает пул. Docker даёт 8 секунд до принудительного завершения. Проверка с незавершённым телом POST измеряет отказ новых соединений и выход до 8 секунд; проверяется `Application shutdown complete`, exit code 0 и отсутствие OOM. Переходные ошибки до исключения backend из LB учитываются в нагрузочном сценарии.
|
||
|
||
## Общая идемпотентность
|
||
|
||
Для POST сообщения требуется ровно один `Idempotency-Key` по шаблону `[A-Za-z0-9._:-]{1,128}`. Отсутствие и неверный формат дают 400. Область ключа — пользователь, POST, путь конкретного чата, ключ. Метод и тип пути фиксированы единственным обработчиком; таблица хранит `(user_id, chat_id, key)` как первичный ключ.
|
||
|
||
В одной транзакции PostgreSQL:
|
||
|
||
1. Проверяется членство в чате; сессия повторно проверяется middleware при каждом запросе.
|
||
2. Берётся транзакционная advisory lock для области ключа. Она общая для всех реплик; возможная коллизия хеша лишь сериализует независимые запросы.
|
||
3. При действующем результате сравнивается значение `text`, а не исходные JSON-байты. Совпадение возвращает прежний 201 и Message; другой текст даёт 409.
|
||
4. Для нового или истёкшего ключа создаются сообщение и строка результата с TTL, затем выполняется COMMIT. Ответ отправляется после COMMIT.
|
||
|
||
Порядок/пробелы JSON и Unicode escaping не меняют результат. В контракте lab3 поле сообщения только `text`; вложения появляются с lab4. Ключи разных пользователей и чатов независимы. 5xx не сохраняется как результат; откат убирает и сообщение, и строку идемпотентности. При обрыве после COMMIT повтор на другой реплике читает прежнее сообщение. Результаты хранятся минимум 24 часа, переживают рестарт и замену API. Истёкшая строка заменяется при следующем использовании того же ключа; сообщения остаются в истории.
|
||
|
||
## Миграции и поочерёдная замена
|
||
|
||
`migrate` — один отдельный Compose-service, выполняющий SQL под общей advisory lock и сохраняющий SHA-256 версий. API только проверяют схему. Ручная команда — `./scripts/migrate.sh`; повтор безопасен и не создаёт повторных данных.
|
||
|
||
Миграция `001_initial.sql` не изменялась. `002_message_idempotency.sql` только добавляет таблицу и не изменяет существующие поля. Она совместима с уже работающей версией приложения. При последующих изменениях разрешены только обратно совместимые добавления перед rolling update; удаление/переименование полей потребует отдельного перехода или окна обслуживания. Автоматическая совместимость произвольных миграций не заявляется.
|
||
|
||
```sh
|
||
./scripts/rolling-update.sh
|
||
```
|
||
|
||
Скрипт сначала собирает образ и запускает миграции, затем для каждого исходного API-контейнера: проверяет наличие другой здоровой реплики, останавливает и удаляет выбранный контейнер, создаёт только недостающую реплику через `up --no-deps --no-recreate --scale`, ждёт её готовности через LB и переходит к следующей. PostgreSQL, Valkey и HAProxy не перезапускаются. Это поочерёдная замена с сохранением хотя бы одной готовой реплики; краткие переходные ошибки измеряются, нулевые ошибки не обещаются.
|
||
|
||
## Команды проверки и доказательства
|
||
|
||
```sh
|
||
make check validate PYTHON=.venv/bin/python
|
||
./scripts/check.sh
|
||
make test-persistence PYTHON=.venv/bin/python ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover PYTHON=.venv/bin/python ACTION_SCRIPT=scripts/stop-one.sh
|
||
docker compose start api
|
||
./scripts/wait-ready.sh
|
||
|
||
# Полный воспроизводимый прогон в отдельном тестовом стенде:
|
||
./scripts/check-docker.sh
|
||
```
|
||
|
||
Для ручной остановки конкретной реплики задать `TARGET_INSTANCE_ID` из её `X-Instance-Id` и вызвать `./scripts/stop-one.sh`. Скрипт сопоставляет hostname контейнерам только текущего Compose project, требует минимум две работающие реплики, останавливает ровно выбранную и оставляет её остановленной. `docker compose ps -a` показывает фактическое состояние. Восстановление — `docker compose start api` и `./scripts/wait-ready.sh`. Полный сценарий последовательно повторяет отказ для каждой из двух реплик, восстанавливая предыдущую.
|
||
|
||
| Критерий ТЗ | Проверка | Доказательство |
|
||
| --- | --- | --- |
|
||
| Воспроизводимый стенд, две реальные API-реплики и единый вход | start.sh, Docker inspect, общий Compose-service api | compose.yaml; containers в lab3-checks.json |
|
||
| Общая сессия, запросы через разные реплики | 20 параллельных повторов с одним Bearer-токеном | test_parallel_replay_across_replicas; lab3-checks.txt |
|
||
| Публичный контракт, включая ошибки и идемпотентность | make test, 28 собственных тестов | lab3-checks.txt |
|
||
| Рестарт всех компонентов, прежняя сессия и сообщения | make test-persistence, StartedAt до/после; повтор ключа после рестарта | persistence в lab3-checks.json |
|
||
| Публичный отказ одной выбранной реплики, восстановление ≤10s | make test-failover, реально остановленный container ID | public_failover; lab3-checks.txt |
|
||
| Отказ каждой API-реплики, чтения и записи под нагрузкой | Два отдельных load_action, восстановление предыдущей между ними | failovers в lab3-checks.json |
|
||
| Параллельная общая идемпотентность, нет дублей | 20 одновременных запросов через ≥2 реплики; сверка истории после отказов | test_idempotency.py; duplicate_messages=0 |
|
||
| Readiness, таймауты и SIGTERM | Отказ PostgreSQL/Valkey; незавершённый запрос + TERM | dependency_readiness и sigterm |
|
||
| CPU/RAM-лимиты, отсутствие обхода LB и container_name | Проверки Docker inspect для всех контейнеров | containers; compose.yaml |
|
||
| Поочерёдная замена под нагрузкой | rolling-update.sh, новые ID обоих API; неизменный StartedAt остальных | rolling_update в lab3-checks.json |
|
||
| Отдельные согласованные миграции | Одноразовый сервис, повторный запуск дважды без изменения данных | lab3-checks.txt; миграции 001/002 |
|
||
|
||
Файлы текущего прогона: [evidence/lab3-checks.txt](evidence/lab3-checks.txt) и [evidence/lab3-checks.json](evidence/lab3-checks.json). Идентификаторы контейнеров, ресурсы, времена, ошибки и посекундные исходные счётчики сохранены без паролей и токенов. `evidence/docker-checks.txt`, `research.*`, `query-plans.json` и `REPORT.lab2.md` относятся ко второй лабораторной.
|
||
|
||
## Измерения
|
||
|
||
Дата прогона — 29.10.2026. Среда: macOS arm64, Docker VM Linux aarch64, 10 CPU, 8217448448 байт RAM. Лимиты контейнеров приведены выше. Профиль — четыре закрытых клиента: POST сообщения и GET истории с существующими сессиями, пауза 50ms между парами запросов. Для неопределённого POST сохраняются прежние ключ и тело. При отказе нагрузка длится 15 секунд после начала воздействия; при замене — весь action и минимум 3 секунды после. Перед воздействием есть 1 секунда прогрева, которая входит в общие счётчики.
|
||
|
||
Численные результаты последнего успешного прогона приведены ниже.
|
||
|
||
| Воздействие | Длительность, с | Успешные HTTP/с | Ошибки | Макс. пауза POST / GET, с | Потеря подтверждённых / дубли |
|
||
| --- | ---: | ---: | ---: | --- | --- |
|
||
| Остановка 7f6a80b69e32 | 16.009 | 98.44 | 4 | 1.957 / 2.004 | 0 / 0 |
|
||
| Остановка f973eaec4d52 | 16.015 | 98.28 | 4 | 2.006 / 2.006 | 0 / 0 |
|
||
| Поочерёдная замена обоих API | 23.774 | 89.64 | 11 | 1.059 / 2.034 | 0 / 0 |
|
||
|
||
SIGTERM с незавершённым POST: новые соединения перестали приниматься за 0.167 с, выход за 5.393 с, exit code 0, OOM отсутствует. При остановке Valkey и PostgreSQL по отдельности подтверждены API live=200, API ready=503 и LB ready=503; после восстановления прежний токен продолжил работать.
|
||
|
||
RPS считается по всем успешным HTTP-запросам чтения и записи за полную длительность сценария; ошибки считаются отдельно. «Первый успех» показывает продолжение обслуживания после начала action, а максимальный промежуток между успешными запросами дополнительно показывает паузы во всём сценарии. После каждого воздействия проверяются все подтверждённые сообщения, исходное сообщение до отказа, отсутствие повторяющихся ID/текстов и работа прежней сессии.
|
||
|
||
Это короткие проверки отказоустойчивости для оценки 4. Нагрузка закрытая, присутствует coordinated omission; p50/p95 относятся только к успешным ответам. Предельная производительность и масштабирование 1/2/4 здесь не исследуются.
|
||
|
||
## Ограничения
|
||
|
||
Выдерживается отказ одной API-реплики при работающей другой. PostgreSQL, Valkey, HAProxy и сам хост остаются точками отказа; отказ узла и HA хранилищ не заявлены. Остановка БД или Valkey делает обязательный API неготовым. При полном рестарте допустимо окно недоступности, данные и действующие сессии сохраняются в volumes. Удаление volumes намеренно уничтожает данные.
|
||
|
||
Нет автоматического TTL-удаления всех давно неиспользуемых ключей идемпотентности: они удаляются при повторном использовании ключа. Срок сессий зависит от часов; keyset-пагинация сохраняет ограничения lab2 при конкурентных записях и переводе часов. Поочерёдная замена останавливается при отсутствии здоровой резервной реплики, автоматический rollback образа не реализован.
|
||
|
||
## Источники
|
||
|
||
- [Docker Compose services, replicas, secrets и depends_on](https://docs.docker.com/reference/compose-file/services/).
|
||
- [Compose up: scale и no-recreate](https://docs.docker.com/reference/cli/docker/compose/up/).
|
||
- [HAProxy: DNS и server-template](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/proxying-essentials/dns-resolution/).
|
||
- [HAProxy: active health checks, inter/fall/rise](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/reliability/health-checks/).
|
||
- [PostgreSQL: advisory locks](https://www.postgresql.org/docs/17/explicit-locking.html#ADVISORY-LOCKS).
|
||
- [Uvicorn: graceful shutdown timeout](https://uvicorn.dev/settings/#timeouts).
|
||
|
||
Стек приложения и закреплённые зависимости перенесены из lab2 (`requirements.txt`): Python 3.11.15, FastAPI 0.142.4, Uvicorn 0.54.0, Psycopg 3.3.6, PostgreSQL 17.6, Valkey 8.1.3; добавлен HAProxy 3.2.6-alpine. README задания, OpenAPI и публичные tests не изменялись. CI запускает контрактные и Docker-проверки; успешный удалённый запуск GitHub Actions без отдельного результата не заявлен.
|