67 KiB
67 KiB
# Отчёт — лабораторная 3
- Автор, группа: Станислав Травкин, БВТ2304
- Целевая оценка: 5
- Текущий этап: реализованы и исследованы критерии оценок 3, 4 и 5;
- Выбранный трек оценки 5: цена масштабирования
- Commit/PR: будет указан после публикации
- Использованные источники: документация Docker Compose, FastAPI, SQLAlchemy, Alembic, PostgreSQL, Redis, Nginx; материалы лабораторной работы
- Помощь ИИ: ChatGPT использовался для обсуждения архитектуры, разработки, отладки и подготовки документации
## Запуск из чистого clone
Для запуска необходимы Docker Engine с поддержкой Docker Compose, Git и Python 3.9 или новее.
Приложение работает в контейнерах. Локальная установка PostgreSQL и Redis не требуется.
Используемые образы:
- Python 3.13.15-slim
- PostgreSQL 17.6
- Redis 8.2.2
- Nginx 1.29-alpine
Из корневого каталога проекта выполнить:
```bash
./scripts/bootstrap.sh
docker compose config --quiet
docker compose up -d --build
docker compose ps -a
```
Скрипт `bootstrap.sh` создаёт локальные файлы секретов, если они отсутствуют, и проверяет конфигурацию Compose. Значения существующих секретов не перезаписываются.
Используются файлы:
- `secrets/postgres_password` — пароль PostgreSQL
- `secrets/database_url` — строка подключения к PostgreSQL
- `secrets/cache_url` — строка подключения к Redis
Секреты исключены из Git.
Миграции Alembic выполняются отдельным сервисом `migrate` перед запуском API. Успешное завершение контейнера миграций отображается как `Exited (0)`.
После запуска обе API-реплики должны иметь статус `healthy`, PostgreSQL и Redis — `healthy`, Nginx — `Up`.
Единая точка входа:
`http://localhost:8080`
Основные проверки:
```bash
make check
make validate
make test
make test-persistence ACTION_SCRIPT=./scripts/restart.sh
make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
python3 tests/test_concurrent_idempotency.py
python3 tests/test_failover_concurrent_idempotency.py
python3 tests/test_review_regressions.py
```
Для локальных Python-проверок требуется установить зависимости из `requirements-dev.txt`, если они ещё не установлены.
После failover-тестов восстановить реплики:
```bash
docker compose start api-1 api-2
```
Безопасная остановка стенда с сохранением данных:
```bash
docker compose down
```
Повторный запуск:
```bash
docker compose up -d --build
```
Для намеренного удаления учебных данных и постоянных Docker volumes используется:
```bash
docker compose down -v
```
Последняя команда удаляет данные PostgreSQL и Redis и не применяется при обычном перезапуске.
## Архитектура и решения
Используется Docker Compose со следующими компонентами:
```text
Client
|
v
Nginx :8080
|
+---- API-1 :8080
|
+---- API-2 :8080
|
+---- PostgreSQL
|
+---- Redis
```
Nginx является единой публичной точкой входа. API-реплики не публикуют порты на хосте и доступны через внутреннюю сеть Compose.
Обе реплики используют одну PostgreSQL и один Redis.
PostgreSQL хранит постоянные данные приложения и информацию, необходимую для общей идемпотентности отправки сообщений. Redis хранит пользовательские сессии с TTL 3600 секунд.
В API не используются локальные пользовательские сессии, поэтому запросы одного пользователя могут обслуживаться разными репликами без повторной авторизации.
Каждая реплика возвращает заголовок `X-Instance-Id`, позволяющий определить обработавший запрос экземпляр.
Для отправки сообщений используется обязательный `Idempotency-Key`. Повторная отправка с тем же ключом не должна создавать второе сообщение. Согласованность между репликами обеспечивается общим PostgreSQL, транзакциями и механизмом advisory locks.
Миграции выполняются отдельным контейнером, что исключает одновременный запуск Alembic несколькими API-репликами.
В Nginx настроены два backend-сервера, динамическое разрешение DNS-имён контейнеров через Docker DNS, таймауты подключения и обработки запросов, а также повторная попытка при отдельных ошибках upstream.
Из лабораторной 2 перенесены основная реализация API, PostgreSQL, миграции, авторизация и работа с сообщениями. В лабораторной 3 добавлены балансировка, две API-реплики, идентификация экземпляров и общая идемпотентность.
Файл `.env.example` является шаблоном задания. Фактическая конфигурация контейнеров задаётся в `compose.yaml`; подключения к PostgreSQL и Redis передаются через файлы секретов.
### Проверки работоспособности и готовности
В приложении реализованы два endpoint:
- `GET /health/live` — проверяет работоспособность процесса API.
- `GET /health/ready` — проверяет доступность PostgreSQL и Redis.
При недоступности необходимой зависимости `/health/ready` возвращает HTTP 503.
Для API также настроен Docker HEALTHCHECK, обращающийся к `/health/ready`.
Это позволяет различать работающий процесс и экземпляр, готовый обслуживать запросы.
### Таймауты и завершение работы
Для подключения к PostgreSQL и Redis заданы ограничения времени ожидания. В Nginx настроены таймауты подключения, чтения и отправки запросов.
Для API установлен `stop_grace_period: 15s`.
При получении SIGTERM сервер Uvicorn завершает приложение штатно. В обработчике lifespan закрываются клиент Redis и пул соединений SQLAlchemy.
При ручной остановке `api-1` в логах наблюдались сообщения об успешном завершении приложения и серверного процесса.
### Ограничения ресурсов
В основной конфигурации для каждой API-реплики установлены 1 CPU и 512 MiB RAM. После замечания преподавателя ограничения добавлены также ко всем инфраструктурным сервисам. Фактические значения проверены командой `docker inspect` (поле `HostConfig`):
| Сервис | CPU | RAM | `NanoCpus` | `Memory`, байт |
|---|---:|---:|---:|---:|
| PostgreSQL | 1 | 768 MiB | 1000000000 | 805306368 |
| Redis | 0,5 | 256 MiB | 500000000 | 268435456 |
| Migrate | 1 | 512 MiB | 1000000000 | 536870912 |
| API-1 | 1 | 512 MiB | 1000000000 | 536870912 |
| API-2 | 1 | 512 MiB | 1000000000 | 536870912 |
| Nginx | 0,5 | 256 MiB | 500000000 | 268435456 |
Сервис `migrate` завершился с кодом 0; заданные ограничения подтверждены и для его завершившегося контейнера. Для API также задан `stop_grace_period: 15s`. При масштабировании API общий бюджет изменяется, если лимиты каждой реплики сохраняются. Поэтому проведены две серии: с фиксированным суммарным бюджетом и с растущим бюджетом.
### Секреты и сетевой доступ
API запускается от непривилегированного пользователя `appuser` с UID 10001. PostgreSQL использует пользователя `postgres` с UID 999.
API, PostgreSQL и Redis не публикуют порты на хосте. Внешний порт `8080` опубликован только у Nginx.
Секреты хранятся в локальном каталоге `secrets/`, исключённом из Git.
Скрипт `bootstrap.sh` устанавливает права:
- `700` для каталога `secrets/`
- `644` для файлов секретов
Каталог недоступен другим обычным пользователям хоста. При этом файлы с правами `644` после монтирования в контейнер доступны для чтения согласно правам файловой системы.
Это ограничение выбранной схемы Docker Compose с файловыми bind mounts. Для более строгой изоляции секретов необходим другой способ их предоставления контейнерам.
## Доказательства критериев
| Критерий | Команда или сценарий | Наблюдаемый результат | Доказательство |
| --- | --- | --- | --- |
| Публичный smoke | `make test` | PASS | `evidence/smoke.txt` |
| Структура проекта | `make check` | PASS | Вывод проверки |
| OpenAPI | `make validate` | PASS | Вывод проверки |
| Две API-реплики | `docker compose ps -a` | Обе реплики healthy | `evidence/compose-status.txt` |
| Общая сессия | `make test-failover` | Сессия сохраняется после отказа реплики | `evidence/failover.txt` |
| Отказ реплики на оценку 3 | `make test-failover ACTION_SCRIPT=./scripts/stop-one.sh` | 55 успешных записей, 4 неудачные попытки, восстановление за 1,327 с | `evidence/failover.txt` |
| Сохранность данных | `make test-persistence ACTION_SCRIPT=./scripts/restart.sh` | PASS | `evidence/persistence.txt` |
| Конкурентная идемпотентность | `python3 tests/test_concurrent_idempotency.py` | 20 запросов, 1 уникальный ID, 1 сообщение в истории | `evidence/idempotency.txt` |
| Базовая нагрузка | `tests/load.py`, 30 с, 8 клиентов | 199,148 RPS, 0 ошибок | `evidence/load-baseline.json` |
| Остановка `api-1` под нагрузкой | `tests/load.py`, 45 с, 8 клиентов | 130,833 RPS, 0 ошибок | `evidence/load-failover-api1.json` |
| Остановка `api-2` под нагрузкой | `tests/load.py`, 45 с, 8 клиентов | 133,351 RPS, 0 ошибок | `evidence/load-failover-api2.json` |
| Failover `api-1` | `make test-failover` | PASS, восстановление за 1,311 с | `evidence/failover-grade4-api1.txt` |
| Failover `api-2` | `make test-failover` | PASS, восстановление за 1,339 с | `evidence/failover-grade4-second.txt` |
| Идемпотентность при отказе | `python3 tests/test_failover_concurrent_idempotency.py` | 20 запросов, 1 сообщение, PASS | `evidence/failover-concurrent-idempotency.txt` |
| Rolling replacement | Поочерёдное пересоздание API под нагрузкой | 16927 успешных запросов, 1 ошибка | `evidence/load-rolling.json` |
| Ограничения CPU/RAM | `docker inspect` для шести сервисов | Все значения `NanoCpus` и `Memory` ненулевые; таблица выше | Вывод проверки 22.10.2026 |
| Регрессии по замечаниям | `python3 tests/test_review_regressions.py` | PASS: UTF-8 Basic Auth, двоеточие в пароле, курсор чатов, последняя страница, некорректный курсор | Вывод проверки 22.10.2026 |
| Растущий бюджет 1/2/4 | `./scripts/run_growing_scale.sh` | 289,590 / 425,950 / 601,701 RPS, по три прогона, ошибок 0 | `evidence/scale/growing/` |
| Оптимизация «до/после» | `./scripts/run_optimization.sh` | 4 → 2 реплики при 2 CPU / 1024 MiB; RPS +6,2%, p95 −29,3%, p99 −42,1%, ошибок 0 | `evidence/scale/optimization/` |
| Закрытые внутренние порты | `docker compose ps` | На хост опубликован только порт Nginx | Результат проверки |
| Корректное завершение | `docker compose stop api-1` | Штатное завершение Uvicorn | Логи контейнера |
## Эксперименты и отказы
### Оценка 3 — отказ API-реплики
Команда:
```bash
make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
```
Полученные результаты:
- Наблюдаемых реплик до отказа: 2
- Успешных записей: 55
- Неудачных попыток: 4
- Время до первого успешного восстановления: 1,327 с
- Подтверждённые данные: сохранены
- Существующая сессия: сохранена
Дополнительно вручную проверена остановка каждой реплики с восстановлением предыдущей. В обоих случаях оставшаяся реплика продолжала обслуживать запросы через Nginx.
### Оценка 3 — сохранность данных
Команда:
```bash
make test-persistence ACTION_SCRIPT=./scripts/restart.sh
```
Результат: PASS.
После перезапуска PostgreSQL, Redis и API подтверждённые данные и существующая сессия остались доступными.
### Оценка 3 — конкурентная идемпотентность
Команда:
```bash
python3 tests/test_concurrent_idempotency.py
```
Результаты:
- Параллельных запросов: 20
- Уникальных идентификаторов сообщений: 1
- Наблюдаемые реплики: `api-1`, `api-2`
- Совпадающих сообщений в истории: 1
- Итог: PASS
Таким образом, конкурентные запросы с одинаковым ключом не создали дублирующих сообщений.
### Оценка 4 — базовая нагрузка
Команда:
```bash
python3 tests/load.py --duration 30 --concurrency 8 --output evidence/load-baseline.json
```
Результаты:
| Показатель | Значение |
| --- | ---: |
| Продолжительность | 30,038 с |
| Успешные запросы | 5982 |
| Ошибки | 0 |
| Пропускная способность | 199,148 RPS |
| p50 | 33,537 мс |
| p95 | 86,622 мс |
| p99 | 201,671 мс |
Полученные значения используются как базовый ориентир для сравнения с экспериментами при остановке реплик.
### Оценка 4 — последовательная остановка реплик под нагрузкой
Для проверки устойчивости выполнялись отдельные нагрузочные испытания с последовательной остановкой `api-1` и `api-2`.
В каждом эксперименте нагрузка создавалась восемью параллельными клиентами. Примерно через 10 секунд после начала испытания останавливалась одна из реплик.
После завершения испытания реплика восстанавливалась перед следующим экспериментом.
| Сценарий | Продолжительность | Успешные запросы | Ошибки | RPS | p50 | p95 | p99 |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| Без отказа | 30,038 с | 5982 | 0 | 199,148 | 33,537 мс | 86,622 мс | 201,671 мс |
| Остановка `api-1` | 45,073 с | 5897 | 0 | 130,833 | 54,133 мс | 112,499 мс | 216,195 мс |
| Остановка `api-2` | 45,084 с | 6012 | 0 | 133,351 | 52,247 мс | 115,109 мс | 208,774 мс |
Доказательства:
- `evidence/load-baseline.json`
- `evidence/load-failover-api1.json`
- `evidence/load-failover-api2.json`
В обоих сценариях остановки приложение продолжило обслуживать запросы через оставшуюся реплику.
Ошибок в этих двух нагрузочных прогонах не зафиксировано. Пропускная способность была ниже базовой, а задержки увеличились.
При интерпретации результатов необходимо учитывать различную длительность базового и отказных испытаний, а также возможные колебания производительности тестового окружения.
### Оценка 4 — проверка восстановления после отказа
Отдельно выполнен сценарий проверки отказоустойчивости с остановкой каждой реплики.
Команда:
```bash
make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
```
Для проверки `api-2` использовалась настройка `TARGET_INSTANCE_ID`.
Результаты:
| Остановленная реплика | Наблюдаемых реплик до отказа | Успешные записи | Неудачные попытки | Первое восстановление | Итог |
| --- | ---: | ---: | ---: | ---: | --- |
| `api-1` | 2 | 65 | 3 | 1,311 с | PASS |
| `api-2` | 2 | 81 | 2 | 1,339 с | PASS |
Доказательства:
- `evidence/failover-grade4-api1.txt`
- `evidence/failover-grade4-second.txt`
Оба испытания завершились успешно.
Время восстановления характеризует момент первого успешного запроса, наблюдаемый тестовым клиентом. Оно не является отдельным измерением времени обнаружения отказа балансировщиком.
Наличие нескольких неудачных попыток показывает, что переключение не было абсолютно бесшовным.
### Оценка 4 — конкурентная идемпотентность при отказе
Команда:
```bash
python3 tests/test_failover_concurrent_idempotency.py
```
Тест создаёт 20 конкурентных запросов с одинаковым `Idempotency-Key` и инициирует остановку `api-1`.
После завершения конкурентных запросов выполняется повторная отправка с тем же ключом и проверяется история сообщений.
Результаты:
- Конкурентных запросов: 20
- Успешных запросов: 20
- Неудачных запросов: 0
- Наблюдаемые реплики: `api-1`, `api-2`
- Уникальных ID успешных ответов: 1
- Сообщений с проверяемым текстом в истории: 1
- Повторная отправка вернула тот же ID
- Итог: PASS
Доказательство:
`evidence/failover-concurrent-idempotency.txt`
Эксперимент подтвердил, что при конкурентных запросах и инициированной остановке одной реплики не появились дублирующие сообщения.
Ограничение эксперимента: все 20 запросов завершились успешно. Сам факт одновременного запуска запросов и остановки контейнера не доказывает, что конкретный запрос был прерван непосредственно во время записи в PostgreSQL.
### Оценка 4 — rolling replacement
Для проверки обновления без полной остановки сервиса выполнялось последовательное пересоздание API-реплик под постоянной нагрузкой.
Нагрузочный тест:
```bash
python3 tests/load.py --duration 90 --concurrency 8 --output evidence/load-rolling.json
```
Во время его выполнения поочерёдно запускались команды:
```bash
docker compose up -d --no-deps --force-recreate api-1
docker compose up -d --no-deps --force-recreate api-2
```
Между пересозданиями проверялись готовность API и ответы через Nginx. При проверке наблюдались ответы от обеих реплик.
Nginx, PostgreSQL и Redis во время пересоздания API не перезапускались.
Результаты:
| Показатель | Значение |
| --- | ---: |
| Продолжительность | 90,037 с |
| Успешные запросы | 16927 |
| Ошибки | 1 |
| Доля ошибок | Около 0,0059 % |
| Пропускная способность | 188,0 RPS |
| p50 | 33,878 мс |
| p95 | 99,116 мс |
| p99 | 199,301 мс |
Доказательство:
`evidence/load-rolling.json`
Во время последовательного пересоздания реплик сервис в целом оставался доступным, однако зарегистрирована одна ошибка.
Поэтому результат нельзя характеризовать как обновление с гарантированным отсутствием ошибок. Эксперимент подтверждает возможность поочерёдного обновления при сохранении обслуживания большинства запросов.
### Оценка 4 — проверка ограничений и завершения
Проверка Docker показала, что на каждую API-реплику действуют ограничения 1 CPU и 512 MiB RAM.
При ручной остановке `api-1` контейнер завершился с кодом 0. В логах Uvicorn наблюдалось штатное завершение приложения.
После восстановления реплика снова получила статус `healthy`.
Проверка опубликованных портов подтвердила, что на хосте доступен только Nginx на порту 8080.
API-реплики, PostgreSQL и Redis доступны через внутреннюю сеть Docker Compose.
### Проверка изолированного окружения
На этапе оценки 3 дополнительно проводились проверки с отдельным именем проекта Docker Compose и чистыми Docker volumes.
Функциональные проверки, сохранность данных, отказоустойчивость и конкурентная идемпотентность в таком окружении завершились успешно.
Это подтверждает воспроизводимость запуска на новом наборе volumes в использованной локальной среде.
Полностью независимый запуск на другом компьютере из нового клона репозитория отдельно не подтверждён.
## Ограничения
PostgreSQL, Redis и Nginx представлены одиночными экземплярами и остаются едиными точками отказа.
При недоступности PostgreSQL или Redis API может потерять готовность к обслуживанию запросов. Репликация и автоматическое переключение этих компонентов не реализованы.
Nginx способен перенаправлять запросы на доступную API-реплику, но отдельные запросы во время отказа или обновления всё равно могут завершиться ошибкой.
Нагрузочный генератор `tests/load.py` создаёт фиксированное число конкурентных клиентов и измеряет успешную пропускную способность и задержки. Он не обеспечивает точное поддержание заданного входящего RPS.
Поэтому полученные значения характеризуют пропускную способность в выбранном режиме нагрузки, а не максимальную производительность системы при произвольном входящем потоке.
В нагрузочных результатах отсутствует детальная посекундная разбивка ошибок и задержек. Время восстановления измеряется отдельно тестом отказоустойчивости.
Секреты хранятся вне Git, но файловая схема Docker Compose с правами `644` не обеспечивает строгой изоляции содержимого от всех процессов, имеющих доступ к смонтированным файлам.
Испытания проведены в одном локальном окружении. Результаты зависят от характеристик компьютера, Docker, нагрузки и состояния базы данных.
## Итоги оценки 4
Выполнены следующие проверки:
- Две API-реплики за балансировщиком Nginx.
- Общие PostgreSQL и Redis.
- Общая авторизация и идемпотентность между репликами.
- Проверки `/health/live` и `/health/ready`.
- Таймауты подключения и обработки запросов.
- Корректное завершение приложения при SIGTERM.
- Ограничения CPU и RAM.
- Отсутствие прямой публикации внутренних сервисов.
- Однократное выполнение миграций отдельным контейнером.
- Остановка каждой API-реплики под нагрузкой.
- Проверка времени восстановления после отказа.
- Конкурентная идемпотентность при инициированном отказе.
- Поочерёдное пересоздание реплик под нагрузкой.
- Хранение секретов вне Git.
Базовая пропускная способность в проведённом испытании составила 199,148 успешного запроса в секунду.
При остановке одной реплики оставшаяся продолжала обслуживать запросы. В отдельных failover-проверках первое успешное восстановление наблюдалось через 1,311 и 1,339 секунды.
При rolling replacement зарегистрирована одна ошибка на 16928 попыток.
Таким образом, реализована и экспериментально проверена устойчивость к отказу одной API-реплики. Полная безошибочность переключения и отсутствие единых точек отказа для всей инфраструктуры не заявляются.
## Оценка 5 — исследование цены масштабирования
### Цель эксперимента
Исследовать влияние количества API-реплик на пропускную способность и задержки приложения при фиксированном суммарном бюджете CPU и RAM.
Сравниваются конфигурации с 1, 2 и 4 API-репликами. PostgreSQL, Redis и Nginx остаются общими компонентами системы.
### Методика
Для всех конфигураций установлен одинаковый суммарный лимит ресурсов API: 2 CPU и 1024 MiB RAM.
| API-реплик | CPU на реплику | RAM на реплику | Общий CPU | Общая RAM |
|---|---|---|---|---|
| 1 | 2 | 1024 MiB | 2 | 1024 MiB |
| 2 | 1 | 512 MiB | 2 | 1024 MiB |
| 4 | 0,5 | 256 MiB | 2 | 1024 MiB |
Конфигурации запускаются с использованием `compose.yaml` и `compose.scale.yaml`. Для каждого количества реплик подготовлена отдельная конфигурация Nginx.
Нагрузочные испытания выполняются скриптом `tests/load.py`. Генератор использует закрытую модель нагрузки с фиксированным количеством конкурентных клиентов, отправляющих POST-запросы на создание сообщений. Автоматические повторные попытки отсутствуют.
Первоначально для каждой конфигурации проведены тесты продолжительностью 60 секунд с 8, 16, 32 и 64 конкурентными клиентами.
Для сравнения воспроизводимости дополнительно выполнены повторные прогоны при 16 клиентах. В итоговом сравнении используются три измерения для каждой конфигурации.
Измеряются успешные запросы в секунду (RPS), задержки p50, p95, p99 и количество ошибок.
Исходные результаты сохранены в `evidence/scale/`. Скрипт `scripts/analyze_scale.py` вычисляет агрегированные показатели и формирует графики.
### Результаты при 16 клиентах
| API-реплик | RPS, прогон 1 | RPS, прогон 2 | RPS, прогон 3 | Средний RPS | Стандартное отклонение RPS |
|---|---|---|---|---|---|
| 1 | 145,953 | 142,549 | 142,668 | 143,723 | 1,932 |
| 2 | 224,292 | 210,316 | 228,380 | 220,996 | 9,472 |
| 4 | 106,885 | 97,026 | 108,340 | 104,084 | 6,155 |
Средние значения перцентилей отдельных прогонов:
| API-реплик | Средний p95 | Средний p99 | Ошибок за три прогона |
|---|---|---|---|
| 1 | 135,946 мс | 158,606 мс | 0 |
| 2 | 129,875 мс | 371,534 мс | 0 |
| 4 | 572,950 мс | 1152,931 мс | 0 |
При одинаковом суммарном бюджете ресурсов конфигурация с двумя репликами показала наибольшую пропускную способность — 220,996 RPS.
По сравнению с одной репликой прирост составил около 53,8%. При переходе с двух реплик на четыре пропускная способность, напротив, снизилась примерно на 52,9%.
При этом минимальное среднее значение p99 наблюдалось у одной реплики. Следовательно, выбор конфигурации зависит не только от максимального RPS, но и от требований к задержкам.
### Графики
Пропускная способность при 16 конкурентных клиентах:

Задержки p95 и p99:

На первом графике столбики погрешности обозначают выборочное стандартное отклонение RPS трёх прогонов.
На втором графике приведены средние значения перцентилей отдельных прогонов. Они не являются перцентилями объединённой выборки всех запросов.
### Диагностика ограничений CPU
Для конфигурации с четырьмя репликами дополнительно исследовано использование CPU.
Проверка параметров cgroup показала, что каждой реплике установлена квота 50000 микросекунд процессорного времени на период 100000 микросекунд, что соответствует 0,5 CPU.
Во время отдельного нагрузочного испытания зафиксировано ограничение процессорного времени (CPU throttling). Доля периодов с throttling составила приблизительно:
| Реплика | Доля периодов с throttling |
|---|---|
| api-1 | 55,0% |
| api-2 | 35,8% |
| api-3 | 41,4% |
| api-4 | 37,8% |
Во время нагрузки наблюдалось использование CPU около установленного лимита, тогда как потребление памяти составляло примерно 70 MiB на реплику при лимите 256 MiB.
Это согласуется с предположением о существенном влиянии процессорных ограничений на результаты четырёх реплик.
### Дополнительный диагностический эксперимент
Для проверки влияния CPU-квоты проведён отдельный эксперимент с четырьмя репликами и 16 конкурентными клиентами.
CPU-квота каждой реплики временно увеличена с 0,5 до 1 CPU. Лимит памяти не изменялся.
При суммарном лимите 4 CPU получены следующие результаты:
- Успешная пропускная способность: 353,146 RPS.
- p50: 31,047 мс.
- p95: 125,895 мс.
- p99: 300,611 мс.
- Ошибок: 0.
Это приблизительно на 239,3% выше средней пропускной способности четырёх реплик при суммарном лимите 2 CPU.
Однако данный эксперимент использовал вдвое больший CPU-бюджет, поэтому его нельзя считать прямым сравнением эффективности масштабирования при одинаковых ресурсах.
После эксперимента ограничения четырёх реплик были возвращены к 0,5 CPU.
Результат свидетельствует о чувствительности производительности к доступному процессорному времени, но сам по себе не доказывает, что всё снижение производительности четырёх реплик вызвано исключительно CPU throttling.
### Ограничения исследования
Испытания выполнялись в одном локальном окружении. На результаты могли влиять фоновая нагрузка компьютера, планировщик CPU, состояние PostgreSQL и Redis, прогрев системы и накопление данных в базе.
Для каждой конфигурации при 16 клиентах проведено три прогона. Это позволяет оценить повторяемость результатов, но недостаточно для строгих статистических выводов.
Генератор использует закрытую модель нагрузки, поэтому результаты зависят от задержек ответов и производительности самого клиента. Возможны coordinated omission и дополнительная нагрузка со стороны генератора.
PostgreSQL, Redis и Nginx не масштабировались вместе с API. Поэтому эксперимент характеризует масштабирование API при фиксированной общей инфраструктуре.
Зафиксированы признаки CPU throttling, однако влияние других факторов на снижение производительности четырёх реплик полностью не исключено.
### Экспериментальная оптимизация CPU-периода
В качестве дополнительной оптимизации проверено изменение периода CPU-квоты для четырёх API-реплик при неизменном суммарном бюджете ресурсов.
В исходной конфигурации каждая реплика имела период 100000 мкс и квоту 50000 мкс. В экспериментальной конфигурации период увеличен до 200000 мкс, а квота — до 100000 мкс. В обоих случаях лимит каждой реплики составлял 0,5 CPU, суммарный бюджет — 2 CPU и 1024 MiB RAM.
Для экспериментальной конфигурации проведено три нагрузочных теста продолжительностью 60 секунд с 16 конкурентными клиентами.
| Прогон | RPS | p95 | p99 | Ошибок |
|---|---:|---:|---:|---:|
| 1 | 86,649 | 888,403 мс | 1559,440 мс | 1 |
| 2 | 85,505 | 925,831 мс | 1351,136 мс | 0 |
| 3 | 85,683 | 890,303 мс | 1366,728 мс | 0 |
| Среднее | 85,946 | 901,512 мс | 1425,768 мс | — |
Сравнение со стандартным периодом 100 мс:
| Метрика | Период 100 мс | Период 200 мс | Изменение |
|---|---:|---:|---:|
| Средний RPS | 104,084 | 85,946 | −17,4% |
| Средний p95 | 572,950 мс | 901,512 мс | +57,3% |
| Средний p99 | 1152,931 мс | 1425,768 мс | +23,7% |
| Ошибок за три прогона | 0 | 1 | — |
Увеличение CPU-периода не привело к улучшению производительности. Средняя пропускная способность снизилась на 17,4%, а задержки p95 и p99 увеличились.
Следовательно, предложенная оптимизация оказалась неэффективной в исследованных условиях. При этом результаты не позволяют утверждать, что увеличение CPU-периода всегда ухудшает производительность: вывод относится к данному приложению, окружению и выбранной нагрузке.
После эксперимента восстановлена стандартная конфигурация с двумя API-репликами.
Результаты сохранены в `evidence/scale/replicas-4-c16-period200.json`, `evidence/scale/replicas-4-c16-period200-repeat.json` и `evidence/scale/replicas-4-c16-period200-repeat2.json`.
### Вторая серия: растущий суммарный бюджет CPU и RAM
Для отделения влияния числа реплик от влияния выделенных ресурсов проведена дополнительная серия. В отличие от основной серии с фиксированным бюджетом, каждая API-реплика получает 1 CPU и 512 MiB RAM. PostgreSQL, Redis и Nginx остаются общими компонентами, их лимиты не увеличиваются. Использован скрипт `./scripts/run_growing_scale.sh`.
| API-реплик | CPU на реплику | RAM на реплику | Общий CPU API | Общая RAM API |
|---|---:|---:|---:|---:|
| 1 | 1 | 512 MiB | 1 | 512 MiB |
| 2 | 1 | 512 MiB | 2 | 1024 MiB |
| 4 | 1 | 512 MiB | 4 | 2048 MiB |
Для каждого варианта: 16 конкурентных клиентов, 15 секунд прогрева, затем три измерения по 60 секунд; запросы `POST` на создание сообщений, закрытая модель нагрузки, без автоматических повторных попыток. Между вариантами Compose-стенд пересоздавался без `down -v`. Все API-реплики становились `healthy`. Итоговые средние и стандартные отклонения вычислены по трём прогонам.
| API-реплик | Средний RPS | Стандартное отклонение RPS | Средний p95 | Средний p99 | Ошибок за три прогона |
|---|---:|---:|---:|---:|---:|
| 1 | 289,590 | 3,160 | 72,661 мс | 106,882 мс | 0 |
| 2 | 425,950 | 4,614 | 63,237 мс | 93,203 мс | 0 |
| 4 | 601,701 | 4,421 | 41,706 мс | 79,650 мс | 0 |
При переходе от 1 к 2 репликам средний RPS увеличился на 47,1%; от 2 к 4 — на 41,3%; от 1 к 4 — на 107,8%. Средний p95 при переходе от 1 к 4 репликам уменьшился на 42,6%. Это подтверждает положительный эффект добавления API-ресурсов в данной серии, но не доказывает линейного масштабирования: при четырёхкратном CPU-бюджете RPS вырос примерно в 2,08 раза.
В первой серии общий бюджет API составлял 2 CPU и 1024 MiB для всех вариантов, поэтому там сравнивалась **цена распределения фиксированных ресурсов**. В этой серии бюджет API увеличивался пропорционально числу реплик, поэтому она показывает **эффект добавления ресурсов**. Числа RPS между сериями нельзя использовать как строгое сравнение «до/после» изменения приложения: менялись ресурсные лимиты и состояние экспериментального окружения.
Доказательства: JSON-файлы измерений в `evidence/scale/growing/`, вывод `./scripts/run_growing_scale.sh` и агрегирование `python3 scripts/summarize_growing_scale.py`. Исходные JSON-файлы должны быть включены в коммит вместе с отчётом.
### Контрольный эксперимент «до/после»: оптимизация числа реплик
После неудачного эксперимента с изменением CPU-периода выполнен отдельный контрольный эксперимент по выбору числа API-реплик. Проверялась гипотеза, что при фиксированном суммарном бюджете уменьшение числа реплик с четырёх до двух повысит пропускную способность и снизит задержки. Это **оптимизация конфигурации развёртывания**, а не изменение кода приложения.
В обеих конфигурациях суммарный бюджет API равен 2 CPU и 1024 MiB RAM. Код приложения, генератор нагрузки, число клиентов и лимиты инфраструктурных сервисов не менялись. При переключении пересоздавались контейнеры, но Docker volumes не удалялись; менялись число API-реплик, распределение их квот и список upstream-серверов Nginx.
| Условие | До оптимизации | После оптимизации |
|---|---:|---:|
| API-реплики | 4 | 2 |
| CPU на реплику | 0,5 | 1 |
| RAM на реплику | 256 MiB | 512 MiB |
| Суммарный бюджет API | 2 CPU / 1024 MiB | 2 CPU / 1024 MiB |
| Конкурентные клиенты | 16 | 16 |
| Прогрев | 15 с | 15 с |
| Основные измерения | 3 × 60 с | 3 × 60 с |
Использована закрытая модель нагрузки `POST`-запросами на создание сообщений без автоматических повторных попыток. Для каждой конфигурации выполнены прогрев и три отдельных измерения.
| Метрика | До: 4 реплики | После: 2 реплики | Изменение |
|---|---:|---:|---:|
| RPS, прогон 1 | 403,177 | 417,559 | — |
| RPS, прогон 2 | 392,746 | 416,933 | — |
| RPS, прогон 3 | 386,841 | 421,396 | — |
| Средний RPS | 394,255 | 418,629 | +6,2% |
| Средний p95 | 91,445 мс | 64,615 мс | −29,3% |
| Средний p99 | 165,019 мс | 95,539 мс | −42,1% |
| Ошибок за три прогона | 0 | 0 | — |
**Подтверждённое улучшение:** при переходе от четырёх к двум репликам средний RPS вырос на 6,2%, средний p95 уменьшился на 29,3%, а средний p99 — на 42,1%. Во всех шести основных прогонах ошибок не зафиксировано. При этом каждый из трёх прогонов конфигурации «после» показал больший RPS, чем любой из трёх прогонов «до».
Результат согласуется с гипотезой о преимуществах двух реплик при ограниченном бюджете, но конкретный вклад CPU throttling, планировщика и других накладных расходов в этом контрольном эксперименте отдельно не измерялся. Результаты отличаются по абсолютному RPS от ранней серии с фиксированным бюджетом; сравнивать их напрямую как единый эксперимент некорректно из-за возможных изменений состояния стенда и базы данных. Вывод «до/после» основан только на шести прогонах новой контрольной серии.
Исходные JSON-файлы: `evidence/scale/optimization/before-run1.json` — `before-run3.json` и `after-run1.json` — `after-run3.json`; файлы прогрева хранятся в том же каталоге. Скрипт `scripts/run_optimization.sh` воспроизводит эксперимент и восстанавливает обычную конфигурацию с двумя репликами. Испытание проведено в одном локальном окружении при 16 клиентах; результат не следует обобщать на все нагрузки и оборудование.
### Сопоставление с предыдущими экспериментами
В исходной серии с фиксированным бюджетом конфигурация с двумя репликами также оказалась быстрее четырёх (220,996 против 104,084 RPS). Однако это отдельная серия с иными абсолютными результатами; её нельзя объединять с новым контрольным экспериментом при расчёте процента улучшения.
Во второй серии с растущим бюджетом четыре реплики достигли 601,701 RPS при 4 CPU и 2048 MiB RAM суммарно. Поэтому преимущество двух реплик относится к **фиксированному бюджету**, а не к любым условиям масштабирования. Эксперимент с изменением CPU-периода остался отрицательным (−17,4% RPS) и не рассматривается как успешная оптимизация.
### Итоговые выводы
В работе исследована цена горизонтального масштабирования API в двух режимах: при фиксированном суммарном бюджете 2 CPU и 1024 MiB RAM и при увеличении бюджета от 1 CPU / 512 MiB до 4 CPU / 2048 MiB.
В исходной серии с фиксированным бюджетом при 16 конкурентных клиентах конфигурация с двумя репликами обеспечила максимальную среднюю пропускную способность — 220,996 RPS. Это приблизительно на 53,8% больше, чем у одной реплики, и на 112,3% больше, чем у четырёх.
При этом одна реплика показала наименьшую среднюю задержку p99 — 158,606 мс. Следовательно, оптимальный выбор зависит от требований к пропускной способности и задержкам.
Диагностика четырёх реплик выявила CPU throttling. Дополнительный эксперимент с увеличенным CPU-бюджетом подтвердил чувствительность приложения к доступному процессорному времени, но не позволил однозначно установить единственную причину снижения производительности.
Попытка оптимизации путём увеличения периода CPU-квоты со 100 до 200 мс при сохранении общего бюджета оказалась неэффективной: RPS снизился на 17,4%.
По результатам исследования для данной нагрузки выбрана конфигурация с двумя API-репликами по 1 CPU и 512 MiB RAM. В отдельном контрольном эксперименте «до/после» при том же суммарном бюджете она обеспечила 418,629 RPS против 394,255 RPS у четырёх реплик (+6,2%) и снизила средние p95 и p99 на 29,3% и 42,1% соответственно. Это подтверждённое конфигурационное улучшение без увеличения общего бюджета API.
Во второй серии с растущим бюджетом средний RPS вырос с 289,590 (1 реплика) до 601,701 (4 реплики), без ошибок за девять измерений. Таким образом, горизонтальное масштабирование необходимо оценивать экспериментально: увеличение числа реплик само по себе не гарантирует повышения производительности, а выделение дополнительных ресурсов способно изменить результат.
## Команды для демонстрации
Все команды выполняются из корневого каталога проекта. Команды с `docker compose down` останавливают стенд, но без `-v` сохраняют постоянные данные PostgreSQL. Для демонстрации достаточно начать с обычной конфигурации двух реплик. Запуск тестов создаёт учебные записи в базе; повторные измерения на изменившемся состоянии базы могут отличаться от приведённых в отчёте.
### 1. Подготовка и запуск
```bash
./scripts/bootstrap.sh
docker compose config --quiet
docker compose up -d --build
docker compose ps -a
```
При первом запуске локальных Python-тестов установить зависимости в виртуальное окружение:
```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt
```
Если `.venv` уже существует и зависимости установлены, повторять создание окружения не нужно. Для проверки миграций и журналов:
```bash
docker compose ps -a
docker compose logs --tail=50 migrate
docker compose logs --tail=30 api-1 api-2 nginx
```
Сервис `migrate` должен завершиться с кодом 0; две реплики API, PostgreSQL и Redis должны быть `healthy`.
### 2. Проверка API, балансировки и изоляции
```bash
curl -i http://localhost:8080/health/live
curl -i http://localhost:8080/health/ready
for i in $(seq 1 12); do curl -s -D - -o /dev/null http://localhost:8080/health/live | grep -i '^x-instance-id:'; done
docker compose ps
docker compose port nginx 8080
```
В заголовке `X-Instance-Id` при повторных запросах ожидаются ответы от `api-1` и `api-2`. Порты API, PostgreSQL и Redis на хост не публикуются; точка входа — Nginx на `localhost:8080`.
Проверка ресурсных ограничений и запуска API от непривилегированного пользователя:
```bash
for i in 1 2; do docker inspect mtusi2026lab3-api-$i-1 --format '{{.Name}} NanoCpus={{.HostConfig.NanoCpus}} Memory={{.HostConfig.Memory}} StopTimeout={{.HostConfig.StopTimeout}}'; done
docker compose exec -T api-1 id
docker stats --no-stream
```
### 3. Функциональные тесты и отказоустойчивость
```bash
make check
make validate
make test
make test-persistence ACTION_SCRIPT=./scripts/restart.sh
make test-failover ACTION_SCRIPT=./scripts/stop-one.sh
python3 tests/test_concurrent_idempotency.py
python3 tests/test_failover_concurrent_idempotency.py
docker compose start api-1 api-2
docker compose ps
```
Тесты проверяют контракт, сохранность данных, работу сессии при отказе и отсутствие дублирования сообщения при конкурентной отправке с одинаковым `Idempotency-Key`. После сценариев отказа необходимо восстановить обе реплики.
Для ручного показа остановки одной реплики и восстановления:
```bash
docker compose stop api-1
curl -i http://localhost:8080/health/ready
docker compose ps
docker compose start api-1
docker compose ps
```
### 4. Нагрузка и последовательное обновление на оценку 4
Базовый нагрузочный тест:
```bash
python3 tests/load.py --duration 30 --concurrency 8 --output evidence/load-demo.json
```
Для демонстрации rolling replacement запустить нагрузку в первом терминале:
```bash
python3 tests/load.py --duration 90 --concurrency 8 --output evidence/load-rolling-demo.json
```
Пока идёт тест, во втором терминале поочерёдно выполнить:
```bash
docker compose up -d --no-deps --force-recreate api-1
docker compose ps
docker compose up -d --no-deps --force-recreate api-2
docker compose ps
```
После теста посмотреть JSON-файл с RPS, задержками и ошибками. Пересоздание под нагрузкой не гарантирует нулевое число ошибок: в исходном эксперименте была зафиксирована одна ошибка.
### 5. Воспроизведение сравнения 1, 2 и 4 реплик на оценку 5
Используются `compose.yaml`, `compose.scale.yaml` и конфигурации Nginx в `infra/scale/`. Для каждого варианта общий лимит API одинаков: 2 CPU и 1024 MiB RAM. Переход между вариантами выполняется с остановкой предыдущего стенда. Команды не используют `down -v`, поэтому накопленные данные сохраняются.
Одна реплика — 2 CPU и 1024 MiB:
```bash
docker compose -f compose.yaml -f compose.scale.yaml down
API_REPLICAS=1 API_CPUS=2.0 API_MEMORY=1024m docker compose -f compose.yaml -f compose.scale.yaml up -d --build postgres redis migrate api-1 nginx
docker compose -f compose.yaml -f compose.scale.yaml ps
python3 tests/load.py --duration 60 --concurrency 16 --output evidence/scale/demo-1-c16.json
```
Две реплики — по 1 CPU и 512 MiB:
```bash
docker compose -f compose.yaml -f compose.scale.yaml down
API_REPLICAS=2 API_CPUS=1.0 API_MEMORY=512m docker compose -f compose.yaml -f compose.scale.yaml up -d --build postgres redis migrate api-1 api-2 nginx
docker compose -f compose.yaml -f compose.scale.yaml ps
python3 tests/load.py --duration 60 --concurrency 16 --output evidence/scale/demo-2-c16.json
```
Четыре реплики — по 0,5 CPU и 256 MiB:
```bash
docker compose -f compose.yaml -f compose.scale.yaml down
API_REPLICAS=4 API_CPUS=0.5 API_MEMORY=256m docker compose -f compose.yaml -f compose.scale.yaml up -d --build postgres redis migrate api-1 api-2 api-3 api-4 nginx
docker compose -f compose.yaml -f compose.scale.yaml ps
python3 tests/load.py --duration 60 --concurrency 16 --output evidence/scale/demo-4-c16.json
```
Для демонстрации ограничений четырёх реплик:
```bash
for i in 1 2 3 4; do docker inspect mtusi2026lab3-api-$i-1 --format '{{.Name}} NanoCpus={{.HostConfig.NanoCpus}} Memory={{.HostConfig.Memory}}'; done
docker stats --no-stream
```
Исторические результаты всех прогонов находятся в `evidence/scale/`; графики уже сохранены в `evidence/scale/charts/`. Для повторного формирования графиков:
```bash
python3 scripts/analyze_scale.py
```
Для воспроизведения всех исходных серий вместо `--concurrency 16` последовательно использовать 8, 16, 32 и 64 клиента; для статистического сравнения провести по три прогона при 16 клиентах, сохраняя каждый результат в отдельный JSON-файл.
### 6. Проверка изменения CPU-периода
Этот эксперимент проводится на четырёх репликах. Он показал отрицательный результат, поэтому не является рекомендуемой рабочей конфигурацией. Дополнительный файл `compose.cpu-period.yaml` заменяет способ задания лимита CPU: `cpu_period: 200000` и `cpu_quota: 100000` вместо `cpus: 0.5`. Перед запуском убедиться, что файл присутствует в проекте.
```bash
docker compose -f compose.yaml -f compose.scale.yaml down
API_REPLICAS=4 API_CPUS=0.5 API_MEMORY=256m docker compose -f compose.yaml -f compose.scale.yaml -f compose.cpu-period.yaml config --quiet
API_REPLICAS=4 API_CPUS=0.5 API_MEMORY=256m docker compose -f compose.yaml -f compose.scale.yaml -f compose.cpu-period.yaml up -d --build postgres redis migrate api-1 api-2 api-3 api-4 nginx
for i in 1 2 3 4; do docker inspect mtusi2026lab3-api-$i-1 --format '{{.Name}} NanoCpus={{.HostConfig.NanoCpus}} CpuPeriod={{.HostConfig.CpuPeriod}} CpuQuota={{.HostConfig.CpuQuota}}'; done
python3 tests/load.py --duration 60 --concurrency 16 --output evidence/scale/demo-4-c16-period200.json
```
При корректной конфигурации каждая реплика имеет `NanoCpus=0`, `CpuPeriod=200000`, `CpuQuota=100000`, то есть 0,5 CPU. Для повторения методики выполнить три прогона с разными именами выходных файлов.
### 7. Воспроизведение серии с растущим бюджетом
```bash
./scripts/run_growing_scale.sh
python3 scripts/summarize_growing_scale.py
```
Скрипт последовательно запускает 1, 2 и 4 API-реплики с лимитами 1 CPU и 512 MiB на реплику, выполняет прогрев и три измерения по 60 секунд. Результаты сохраняются в `evidence/scale/growing/`. После завершения восстанавливается основная конфигурация двух реплик. Команда пересоздаёт контейнеры, поэтому её следует выполнять на учебном стенде.
### 8. Воспроизведение контрольной оптимизации «до/после»
```bash
./scripts/run_optimization.sh
```
Скрипт сравнивает четыре реплики по 0,5 CPU / 256 MiB и две реплики по 1 CPU / 512 MiB при одинаковом общем бюджете 2 CPU / 1024 MiB. Для каждой конфигурации выполняются 15 секунд прогрева и три измерения по 60 секунд с 16 клиентами. Результаты сохраняются в `evidence/scale/optimization/`. После эксперимента восстанавливаются две API-реплики. Скрипт пересоздаёт контейнеры без удаления volumes и предназначен для учебного стенда.
### 9. Регрессионные тесты по замечаниям
```bash
python3 tests/test_review_regressions.py
for service in postgres redis migrate api-1 api-2 nginx; do
echo "=== $service ==="
docker inspect "$(docker compose ps -aq "$service")" --format 'CPU: {{.HostConfig.NanoCpus}}, RAM: {{.HostConfig.Memory}} bytes'
done
```
Регрессионный тест проверяет UTF-8 Basic Auth с двоеточием в пароле, переход между страницами списка чатов, отсутствие курсора на последней странице и отклонение некорректного курсора. Команда `docker inspect` подтверждает ограничения всех сервисов.
### 10. Возврат к основной конфигурации после демонстрации
```bash
docker compose -f compose.yaml -f compose.scale.yaml -f compose.cpu-period.yaml down
API_REPLICAS=2 API_CPUS=1.0 API_MEMORY=512m docker compose -f compose.yaml -f compose.scale.yaml up -d --build postgres redis migrate api-1 api-2 nginx
docker compose -f compose.yaml -f compose.scale.yaml ps
curl -i http://localhost:8080/health/ready
```
Для обычной остановки без удаления данных:
```bash
docker compose down
```
`docker compose down -v` применять только при намеренном удалении учебной базы и volumes. При защите удобно показать сначала работающие две реплики, затем `X-Instance-Id`, проверки `make`, failover и результаты масштабирования; полные 60-секундные серии можно воспроизвести по приведённым командам при необходимости.