221 lines
19 KiB
Markdown
221 lines
19 KiB
Markdown
# Отчёт по лабораторной работе № 3
|
||
|
||
**Дисциплина:** Высоконагруженные системы
|
||
**Тема:** Балансировка нагрузки и отказ API-реплики
|
||
**Факультет:** Факультет ИТ
|
||
**Группа:** БВТ2302
|
||
**Студент:** Соколов Илья Сергеевич
|
||
**Целевая оценка:** 3
|
||
**Дата проверки:** 31.10.2026
|
||
**Репозиторий / commit / Pull Request:** сведения о публикации не предоставлены; заполнить после отправки в GitHub.
|
||
|
||
## 1. Цель работы
|
||
|
||
Развернуть приложение с не менее чем двумя взаимозаменяемыми экземплярами API за единой точкой входа, общим хранилищем данных и сессий. Проверить корректность работы API, сохранение данных после перезапуска компонентов, отказоустойчивость при остановке одной реплики и идемпотентность повторных запросов.
|
||
|
||
## 2. Используемые технологии
|
||
|
||
- **Go 1.23** — реализация HTTP API.
|
||
- **PostgreSQL 16.9** — общее хранилище пользователей, сообщений, сессий и ключей идемпотентности.
|
||
- **Nginx 1.27.5** — балансировщик и единая точка входа.
|
||
- **Docker Desktop / Docker Compose** — сборка, запуск и управление контейнерами.
|
||
- **Python 3.12** — выполнение публичных проверок.
|
||
- **Windows PowerShell** — запуск команд на локальной машине.
|
||
|
||
## 3. Архитектура приложения
|
||
|
||
```text
|
||
Клиент (http://localhost:18080)
|
||
|
|
||
v
|
||
Nginx (lb:80)
|
||
/ \
|
||
v v
|
||
API-1 API-2
|
||
\ /
|
||
v v
|
||
PostgreSQL
|
||
(volume pgdata)
|
||
```
|
||
|
||
Стенд запускается через `compose.yaml`. Nginx публикует **только один порт на локальном компьютере** — `127.0.0.1:18080`, а обе API-реплики доступны через внутреннюю сеть Docker без отдельной публикации портов. Внутри Docker API продолжает прослушивать порт `8080`.
|
||
|
||
API не хранит критичное для корректности состояние локально: данные приложения, сессии и ключи идемпотентности находятся в общей БД PostgreSQL. Поэтому запросы одной пользовательской сессии могут обслуживаться разными репликами без повторной авторизации. Sticky sessions не используются.
|
||
|
||
Миграции выполняются отдельным одноразовым сервисом `migrate`, который стартует после готовности PostgreSQL. API начинает работу после успешного выполнения миграций. Статус `Exited (0)` для `migrate` после завершения — штатный.
|
||
|
||
**Основные решения:**
|
||
|
||
- **Балансировка:** Nginx использует внутренний DNS Docker (`api`) и `resolver 127.0.0.11 valid=1s`; настроены ограничения по времени ожидания соединения и повтор при сетевых ошибках/ошибках шлюза.
|
||
- **Readiness:** endpoint `GET /health/ready` проверяет готовность сервиса.
|
||
- **Идентификация реплик:** заголовок `X-Instance-Id` позволяет наблюдать, какой экземпляр обработал запрос.
|
||
- **Graceful shutdown:** при SIGTERM сервис перестаёт считаться готовым, выдерживает период `SHUTDOWN_DRAIN_SECONDS=1` и завершает обработку текущих запросов.
|
||
- **Идемпотентность:** запрос отправки сообщения использует `Idempotency-Key`; запись ключа и сообщения выполняется в одной транзакции PostgreSQL. Повтор с тем же ключом и телом возвращает сохранённый результат, попытка использовать ключ с другим телом отклоняется.
|
||
- **Хранение данных:** Docker volume `pgdata` сохраняется при обычных перезапусках контейнеров.
|
||
- **Защита:** заданы лимиты CPU/RAM, у API включены `read_only`, `cap_drop: ALL` и запрет повышения привилегий.
|
||
|
||
## 4. Запуск лабораторной работы
|
||
|
||
В локальной среде Windows порт `8080` оказался недоступен для публикации Docker (`bind: An attempt was made to access a socket in a way forbidden by its access permissions`). Поэтому в локальном `.env` был установлен `PUBLISHED_PORT=18080`. Это изменяет **только внешний порт балансировщика**, а не внутренний порт API. Файл `.env`, как и файлы из `secrets/`, не включается в репозиторий.
|
||
|
||
Использованный каталог проекта:
|
||
|
||
```text
|
||
D:\Study\sem_7\Высоконагруженные системы\Лабы\3\mtusi2026lab3-main
|
||
```
|
||
|
||
**Команды для воспроизведения запуска в PowerShell:**
|
||
|
||
```powershell
|
||
cd "D:\Study\sem_7\Высоконагруженные системы\Лабы\3\mtusi2026lab3-main"
|
||
|
||
# Создаёт локальные secrets/ и .env, если их ещё нет.
|
||
powershell -ExecutionPolicy Bypass -File scripts\init-secrets.ps1
|
||
|
||
# Однократно укажите в .env: PUBLISHED_PORT=18080
|
||
# На компьютере без конфликта портов допустимо оставить 8080.
|
||
|
||
docker compose up -d --build
|
||
docker compose ps
|
||
curl.exe http://localhost:18080/health/ready
|
||
```
|
||
|
||
**Фактически полученный ответ readiness:**
|
||
|
||
```json
|
||
{"status":"ok"}
|
||
```
|
||
|
||
После запуска были здоровы `mtusi-lab3-postgres-1`, `mtusi-lab3-api-1` и `mtusi-lab3-api-2`; балансировщик `mtusi-lab3-lb-1` работал с привязкой `127.0.0.1:18080->80/tcp`. После проверки отказоустойчивости первая реплика была восстановлена командой `docker compose up -d`, и обе API-реплики вновь получили статус `Healthy`.
|
||
|
||
## 5. Проверки и результаты
|
||
|
||
Все приведённые ниже результаты получены в PowerShell **31.10.2026**. Для Python в Windows использован параметр `-X utf8`, поскольку без него чтение `lab.json` завершалось `UnicodeDecodeError` из-за системной кодировки `cp1252`.
|
||
|
||
### 5.1. Базовый сценарий API (smoke)
|
||
|
||
```powershell
|
||
python -X utf8 tests\smoke.py --base-url http://localhost:18080
|
||
```
|
||
|
||
Результат:
|
||
|
||
```text
|
||
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
|
||
```
|
||
|
||
**Вывод:** сквозной публичный сценарий API пройден, включая стандартные проверки повторной отправки сообщения с тем же ключом, конфликт с другим телом и отсутствие обязательного ключа. Данный тест сам по себе не доказывает наличие двух работающих контейнеров или поведение системы при отказе.
|
||
|
||
### 5.2. Сохранность данных и сессии (persistence)
|
||
|
||
```powershell
|
||
python -X utf8 tests\resilience.py --mode persistence --action-script scripts\restart.cmd --base-url http://localhost:18080
|
||
```
|
||
|
||
Результат:
|
||
|
||
```text
|
||
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
|
||
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
|
||
```
|
||
|
||
**Вывод:** после выполнения `restart.cmd` подтверждённые данные сохранились, а существующий токен сессии остался действительным. Скрипт перезапускает LB, API и PostgreSQL без удаления volume. Для доказательства реального объёма перезапуска дополнительно требуются состояния контейнеров до/после выполнения скрипта.
|
||
|
||
### 5.3. Остановка одной реплики (failover)
|
||
|
||
```powershell
|
||
python -X utf8 tests\resilience.py --mode failover --action-script scripts\stop-one.cmd --base-url http://localhost:18080
|
||
```
|
||
|
||
Результат:
|
||
|
||
```text
|
||
Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
|
||
{"observed_instances_before": 2, "successful_writes": 8, "failed_attempts": 0, "first_recovery_seconds": 4.203}
|
||
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
|
||
```
|
||
|
||
| Показатель | Полученное значение |
|
||
| --- | ---: |
|
||
| Различных API-реплик до отказа | **2** |
|
||
| Успешных записей во время теста | **8** |
|
||
| Неудачных попыток | **0** |
|
||
| Время до первой успешной записи после начала отказа | **4,203 с** |
|
||
| Допустимое время восстановления записи по критерию лабораторной | **не более 10 с** |
|
||
| Результат теста | **PASS** |
|
||
|
||
Дополнительно выполнена команда:
|
||
|
||
```powershell
|
||
docker ps -a --filter label=com.docker.compose.service=api
|
||
```
|
||
|
||
Состояние непосредственно после теста:
|
||
|
||
```text
|
||
mtusi-lab3-api-2 Up (healthy)
|
||
mtusi-lab3-api-1 Exited (0)
|
||
```
|
||
|
||
Таким образом, одна реплика (`api-1`) была действительно остановлена, вторая (`api-2`) осталась работоспособной, а проверка сохранности данных и прежней сессии завершилась успешно. После эксперимента выполнено:
|
||
|
||
```powershell
|
||
docker compose up -d
|
||
```
|
||
|
||
После восстановления обе API-реплики получили статус `Healthy`.
|
||
|
||
## 6. Соответствие критериям лабораторной
|
||
|
||
| Критерий | Подтверждение | Статус |
|
||
| --- | --- | --- |
|
||
| Запуск через Docker Compose, одна точка входа | `docker compose up -d --build`, опубликован только порт LB | Подтверждено |
|
||
| Не менее двух API-реплик и общее хранилище | Две здоровые API-реплики; `observed_instances_before: 2` | Подтверждено |
|
||
| Работа одного пользователя через разные реплики | `resilience.py` наблюдал два `X-Instance-Id` | Подтверждено тестом |
|
||
| Публичный сквозной сценарий API | `smoke.py` — PASS | Подтверждено |
|
||
| Сохранность данных после рестарта | `persistence` — PASS | Подтверждено тестом |
|
||
| Работа при остановке одной реплики, восстановление записи за ≤10 с | `failover` — PASS; 4,203 с; 0 ошибок | Подтверждено для `api-1` |
|
||
| Сохранность данных и прежнего токена при отказе | `failover` — PASS | Подтверждено тестом |
|
||
| Идемпотентные повторы запроса | Публичный smoke проверяет повтор и конфликты; failover проверяет безопасность неопределённого повтора | Базовые проверки пройдены |
|
||
| Одновременные POST с одним ключом через разные реплики | Отдельного протокола параллельных запросов пока нет | Требует отдельного доказательства |
|
||
| Остановка второй реплики при работающей первой | Повторный независимый опыт не зафиксирован | Требует отдельного доказательства |
|
||
| Commit / PR и приложенные артефакты evidence | Ссылки и файлы не предоставлены | Требует оформления |
|
||
|
||
## 7. Особенности эксперимента и ограничения
|
||
|
||
1. **PostgreSQL и Nginx остаются единичными точками отказа.** Данный эксперимент подтверждает устойчивость к отказу одной API-реплики, а не отказоустойчивость всех компонентов или физического узла.
|
||
2. **Замер 4,203 с** — время до первой успешной записи после начала failover hook, а не полное время перезапуска приложения или узла.
|
||
3. **Автоматические проверки не заменяют доказательства действий оператора.** Для защиты полезно сохранить вывод `docker compose ps`, состояния конкретной реплики до/после остановки и доказательства восстановления.
|
||
4. **Эксперимент с остановкой второй реплики отдельно не зафиксирован.** Повторить его после восстановления первой, если это требуется преподавателем.
|
||
5. **Конкурентные запросы с одним Idempotency-Key через разные реплики отдельно не измерялись.** Корректность базовой идемпотентности подтверждена smoke-тестом, но вывод о самостоятельной конкурентной проверке не делается.
|
||
6. **Внешний порт `18080`** относится к конкретному Windows-стенду. Для запуска на другой машине допустим стандартный порт `8080`, если он свободен.
|
||
|
||
## 8. Доказательства для репозитория
|
||
|
||
В каталоге `evidence/` рекомендуется сохранить небольшие обезличенные текстовые журналы:
|
||
|
||
- `smoke.txt` — вывод `smoke.py`;
|
||
- `persistence.txt` — вывод проверки сохранности;
|
||
- `failover.txt` — вывод проверки отказа и её метрики;
|
||
- `containers.txt` — перечень контейнеров и их состояний до отказа;
|
||
- `api-after-failover.txt` — состояния API-контейнеров после остановки;
|
||
- `api-after-restore.txt` — состояния после восстановления;
|
||
- отдельный протокол остановки второй реплики и конкурентных запросов, если выполнены.
|
||
|
||
**Примечание:** перечисленные имена — рекомендуемые артефакты. Наличие этих файлов в репозитории на момент составления отчёта не подтверждено. Секреты, `.env`, токены сессий, пароли и полные дампы БД сохранять в доказательства нельзя.
|
||
|
||
## 9. Вывод
|
||
|
||
В ходе лабораторной работы № 3 развернут стенд с балансировщиком Nginx, двумя взаимозаменяемыми API-репликами и общей PostgreSQL. Публичная проверка API, тест сохранности данных после перезапуска и тест отказа одной API-реплики **завершились успешно (PASS)**.
|
||
|
||
В тесте отказоустойчивости до остановки наблюдались две реплики. После остановки `api-1` система выполнила **8 успешных записей без зарегистрированных ошибок**, а первая успешная запись после начала отказа была зафиксирована через **4,203 секунды**, что удовлетворяет требованию восстановления не позднее 10 секунд. Подтверждённые сообщения и прежняя сессия сохранились, после чего остановленная реплика была восстановлена.
|
||
|
||
**Основные автоматические тесты пройдены.** Для полного комплекта материалов на защиту остаётся приложить журналы экспериментов, проверить отказ второй реплики, отдельно зафиксировать конкурентную идемпотентность и добавить ссылку на GitHub Pull Request.
|
||
|
||
## 10. Использованные материалы и помощь ИИ
|
||
|
||
- Исходное задание, API-контракт и публичные тесты лабораторной № 3 (`README.md`, `contracts/`, `tests/`).
|
||
- Собственная кодовая база лабораторной № 2 на Go, pgx и PostgreSQL, доработанная для лабораторной № 3.
|
||
- Конфигурация Docker Compose и Nginx с опорой на официальную документацию соответствующих инструментов.
|
||
- Claude Code использовался при доработке приложения и конфигураций; ChatGPT — при диагностике запуска и подготовке отчёта. Результаты проверок приведены из фактического вывода PowerShell.
|