forked from mtusi2026/mtusi2026lab3
258 lines
16 KiB
Markdown
258 lines
16 KiB
Markdown
# Отчёт — лабораторная 3
|
||
|
||
- Автор, группа: Булла Максим, БПИ2301
|
||
- Целевая оценка: **4**
|
||
- Commit/PR: f731f9b
|
||
- Источники, библиотеки и помощь ИИ: официальная документация Docker Compose,
|
||
HAProxy, Go/Fiber; код и инфраструктура подготовлены с помощью
|
||
DeepSeek V4.1 Flash + OpenCode
|
||
|
||
## 1. Что сделано
|
||
|
||
Рабочая база lab2 (Go + Fiber v3, PostgreSQL, Redis-сессии, миграции) доведена
|
||
до lab3:
|
||
|
||
- HAProxy стал единственной публичной точкой входа;
|
||
- запущены две API-реплики без публикации их портов;
|
||
- сессии и идемпотентность сообщений вынесены в общие хранилища;
|
||
- `X-Instance-Id` добавлен во все ответы API;
|
||
- миграции вынесены в отдельный one-shot сервис;
|
||
- настроены readiness, graceful shutdown и ограничения CPU/RAM;
|
||
- добавлены action-скрипты для restart/failover и rolling replacement;
|
||
- подготовлен профиль k6 для проверки rolling update под нагрузкой.
|
||
|
||
Обязательный контракт, `lab.json` и публичные тесты не изменялись. Существующие
|
||
неочевидные решения отмечены в коде комментариями `AGENT:`; перечень файлов
|
||
для их проверки и удаления находится в `LEFT_TO_REVIEW.md`. Новые комментарии
|
||
`AGENT:` в этой итерации не добавлялись: изменения и их обоснование записаны в
|
||
`CHANGELOG.md`.
|
||
|
||
## 2. Запуск из чистого clone
|
||
|
||
Требуется Docker Engine с Compose v2 и свободный порт `8080` (или другой
|
||
`LB_PORT`). Версии образов зафиксированы в `compose.yaml`.
|
||
|
||
```sh
|
||
cp .env.example .env
|
||
# задать локальный POSTGRES_PASSWORD; остальное можно оставить по умолчанию
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build
|
||
make wait
|
||
```
|
||
|
||
Порядок запуска:
|
||
|
||
1. PostgreSQL и Redis проходят healthcheck.
|
||
2. Сервис `migrate` один раз применяет миграции и завершается.
|
||
3. Запускаются API-реплики с `RUN_MIGRATIONS=false`.
|
||
4. HAProxy начинает отдавать `/health/ready` только после готовности API.
|
||
|
||
Проверки:
|
||
|
||
```sh
|
||
make test
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
make test-concurrency
|
||
```
|
||
|
||
Дополнительно:
|
||
|
||
```sh
|
||
make k6 VUS=20 DURATION=60s # нагрузка через HAProxy
|
||
make validate PYTHON=.venv/bin/python
|
||
```
|
||
|
||
Остановка без удаления данных:
|
||
|
||
```sh
|
||
docker compose --env-file .env down
|
||
```
|
||
|
||
Намеренное удаление учебных данных (только отдельный стенд):
|
||
|
||
```sh
|
||
docker compose --env-file .env down -v
|
||
```
|
||
|
||
`.env` в репозиторий не попадает; в `.env.example` лежит только placeholder
|
||
пароля.
|
||
|
||
## 3. Архитектура и решения
|
||
|
||
```text
|
||
клиент
|
||
│ HTTP :8080
|
||
▼
|
||
HAProxy ── readiness /health/ready, retries, stats :8404, Prometheus /metrics
|
||
│ Docker DNS, server-template api 1..4
|
||
├──────────────┐
|
||
▼ ▼
|
||
API-1 API-2 ... API-N (Go/Fiber, без публикации портов)
|
||
│ │
|
||
└──────┬───────┘
|
||
▼
|
||
PostgreSQL ← users/chats/messages + message_idempotency
|
||
Redis ← общие сессии (AOF)
|
||
|
||
migrate — one-shot, RUN_MIGRATIONS / MIGRATE_ONLY
|
||
```
|
||
|
||
### 3.1. Компоненты и лимиты
|
||
|
||
| Компонент | Роль | Решение |
|
||
| --- | --- | --- |
|
||
| `haproxy` | LB и публичная точка входа | `server-template api 4 api:8080 resolvers docker`; health check `/health/ready` каждые 1 с, `fall 2` |
|
||
| `api` | бизнес-API | `deploy.replicas: ${API_REPLICAS:-2}`, `expose: 8080`, без `ports` |
|
||
| `migrate` | миграции | тот же образ, `MIGRATE_ONLY=true`, `restart: "no"` |
|
||
| `postgres` | источник истины | named volume `pgdata`, healthcheck, версия 16.10 |
|
||
| `redis` | общие сессии | AOF `everysec`, named volume `redisdata` |
|
||
| `k6` | нагрузка | профиль `load`, подключается только при явном запуске |
|
||
|
||
У API, PostgreSQL, Redis и HAProxy есть CPU/RAM-лимиты
|
||
(`deploy.resources.limits`, значения из `.env`). У API нет `container_name`,
|
||
поэтому Compose может масштабировать сервис.
|
||
|
||
### 3.2. Миграции
|
||
|
||
`app/cmd/server/main.go` поддерживает два режима:
|
||
|
||
- обычный API: `RUN_MIGRATIONS=false`, схемой занимается отдельный сервис;
|
||
- `MIGRATE_ONLY=true`: применить миграции, закрыть пул и выйти, не открывая
|
||
Redis.
|
||
|
||
Это убирает гонку миграций при старте нескольких реплик и при rolling update.
|
||
Миграция `0002_message_idempotency` аддитивная: старая версия приложения может
|
||
работать с уже созданной таблицей, новая версия требует её наличия. Поэтому
|
||
порядок «сначала migrate, потом новые API» безопасен.
|
||
|
||
### 3.3. `X-Instance-Id`
|
||
|
||
Middleware в `app/internal/app.go` ставит заголовок на каждый ответ, включая
|
||
health и ошибки. Значение берётся из `INSTANCE_ID`, а если он не задан — из
|
||
hostname процесса. В Compose hostname уникален для контейнера, поэтому
|
||
реплики различимы; значение не меняется в течение жизни процесса.
|
||
|
||
Если hostname получить нельзя и `INSTANCE_ID` не задан, конфигурация
|
||
завершается ошибкой. Раньше в этом случае молча подставлялось литеральное
|
||
значение `api`, из-за чего несколько процессов могли получить одинаковый
|
||
идентификатор.
|
||
|
||
### 3.4. Идемпотентность сообщений
|
||
|
||
Таблица `message_idempotency`:
|
||
|
||
- PK `(sender_id, chat_id, idempotency_key)` — ровно область «пользователь +
|
||
путь чата + ключ»; метод в текущем API только один;
|
||
- `request_hash` — SHA-256 текста сообщения;
|
||
- `message_id` — ссылка на уже созданное сообщение;
|
||
- `created_at`, `expires_at` — окно хранения (по умолчанию 24 часа).
|
||
|
||
Алгоритм в `app/internal/store/messages.go`:
|
||
|
||
1. Быстрый lookup по ключу. Если запись не истекла и hash совпал — вернуть тот же
|
||
`Message` с `201`.
|
||
2. Иначе открыть транзакцию, вставить сообщение с проверкой членства в чате,
|
||
вставить ключ через `ON CONFLICT`.
|
||
3. Если конкурентная реплика уже вставила этот ключ, транзакция текущего
|
||
запроса откатывается, и читается результат победившей реплики. При другом
|
||
hash — `409`.
|
||
4. Транзиентная ошибка не фиксирует ключ: транзакция откатывается, клиент может
|
||
повторить с тем же ключом.
|
||
|
||
Так один ключ создаёт ровно одно сообщение даже при параллельных запросах через
|
||
разные реплики. Повтор снова проходит аутентификацию и проверку доступа к чату.
|
||
|
||
### 3.5. HAProxy и graceful shutdown
|
||
|
||
- backend discovery: Docker DNS `127.0.0.11:53`, `server-template api 4`, поэтому
|
||
`docker compose up --scale api=N` не требует правки конфига;
|
||
- health check: `GET /health/ready`, `inter 1s`, `fall 2` — обнаружение отказа
|
||
около 2 секунд (при бюджете 10 секунд);
|
||
- `retries 2`, `option redispatch` — короткие ошибки соединения не роняют запрос;
|
||
- при SIGTERM приложение сначала перестаёт отдавать `200` на readiness, затем
|
||
ждёт до 10 секунд; у контейнера `stop_grace_period: 15s`;
|
||
- stats UI/CSV на `:8404/stats`, Prometheus на `:8404/metrics`.
|
||
|
||
### 3.6. Readiness и транзакции
|
||
|
||
`/health/ready` проверяет PostgreSQL и Redis и не захватывает прикладных
|
||
блокировок. `pgxpool.Ping` берёт соединение из пула и возвращает его через
|
||
`defer`; `store.Ping` ограничивает проверку двумя секундами.
|
||
|
||
Отдельно проверены транзакции в `CreateChat` и `CreateMessage`. Откат больше не
|
||
выполняется на неограниченном `context.Background()`: используется контекст с
|
||
таймаутом. Если PostgreSQL перестал отвечать, соединение закрывается, а
|
||
PostgreSQL трактует закрытие соединения как откат и снимает блокировки строк.
|
||
Это не даёт неудачной транзакции удерживать соединение пула и мешать readiness
|
||
других запросов. Единственная явная advisory-блокировка — миграционная; она
|
||
снимается в `defer` с собственным таймаутом.
|
||
|
||
## 4. Доказательства критериев
|
||
|
||
| Критерий | Команда/сценарий | Наблюдаемый результат | Файл |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke | `make test` | `PASS: lab3 public API scenario` | `evidence/grade-3-4.md` |
|
||
| Офлайн-проверки | `make check` | `PASS: offline skeleton...` | `evidence/grade-3-4.md` |
|
||
| OpenAPI | `make validate PYTHON=.venv/bin/python` | `PASS: full OpenAPI 3.1...` | `evidence/grade-3-4.md` |
|
||
| ≥2 реплики, одна сессия | 10 запросов `/health/live` через LB | 2 разных `X-Instance-Id` | `evidence/grade-3-4.md` |
|
||
| Остановка одной реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | 120–121 запись, 0–1 ошибка, восстановление 2.54–2.93 с | `evidence/grade-3-4.md` |
|
||
| Сохранность после restart | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | данные и bearer-токен сохранились | `evidence/grade-3-4.md` |
|
||
| Конкурентная идемпотентность | `make test-concurrency` | 12 запросов, 2 реплики, 1 сообщение, другой body → 409 | `evidence/grade-3-4.md` |
|
||
| CPU/RAM-лимиты, API без host ports | `compose.yaml`, `docker compose ps` | API только `expose`, лимиты заданы | `compose.yaml` |
|
||
| Rolling update под нагрузкой | `scripts/rolling-update.sh 2` + k6 20 VU/60 с | 41 605 итераций, 0 failed checks, p95 55.27 мс | `evidence/k6-rolling-20vu-60s.json` |
|
||
| Миграции однократно | `migrate` service, API `RUN_MIGRATIONS=false` | `migrate` завершился, API healthy | `compose.yaml`, `app/cmd/server/main.go` |
|
||
|
||
Проверки HTTP запускались из контейнера в сети стенда: в рабочей оболочке
|
||
published ports были изолированы от хоста. Это ограничение среды, а не
|
||
приложения; на обычной машине команды `make test`/`make test-failover`
|
||
запускаются с хоста.
|
||
|
||
## 5. Эксперименты и отказы
|
||
|
||
### 5.1. Отказ одной API-реплики
|
||
|
||
| Что сделано | Ожидание | Наблюдение | Восстановление |
|
||
| --- | --- | --- | --- |
|
||
| Остановлена одна API-реплика при живой второй | LB исключает её, подтверждённые данные и сессия целы | 2 реплики до отказа; 120–121 успешная запись; 0–1 краткая ошибка | 2.54–2.93 с до первой успешной записи |
|
||
| Вручную остановлена вторая реплика | Трафик переходит на оставшуюся | 1698 успешных записей, 1 ошибка; обе реплики наблюдались до отказа | вторая реплика восстановлена через `up` |
|
||
|
||
Ошибка на границе отказа ожидаема: клиент мог отправить запрос в момент, когда
|
||
процесс уже остановлен, но HAProxy ещё не убрал backend. Повтор с тем же
|
||
`Idempotency-Key` не создал дубль.
|
||
|
||
### 5.2. Rolling update под нагрузкой
|
||
|
||
`scripts/rolling-update.sh 2` собирает образ и поочерёдно заменяет контейнеры:
|
||
останавливает один, удаляет, создаёт replacement, ждёт health и только потом
|
||
переходит к следующему. Во время этого k6 писал сообщения 20 VU в течение 60 с.
|
||
|
||
| Метрика | Значение |
|
||
| --- | ---: |
|
||
| Всего запросов | 41 608 |
|
||
| Итераций | 41 605 |
|
||
| Ошибок проверок | 0 |
|
||
| p95 | 55.27 мс |
|
||
| p99 | 71.15 мс |
|
||
|
||
Это подтверждает, что последовательная замена не рвёт поток целиком: HAProxy
|
||
успевает исключить остановленный backend. Сырой summary:
|
||
`evidence/k6-rolling-20vu-60s.json`.
|
||
|
||
## 6. Ограничения
|
||
|
||
- Один Docker-host: потеря узла не переживается. HAProxy, PostgreSQL и Redis
|
||
остаются единичными точками отказа; API-реплики не делают БД
|
||
высокодоступной.
|
||
- PostgreSQL не реплицирован. При потере `pgdata` данные теряются; Redis AOF
|
||
спасает сессии от рестарта, но не от потери диска.
|
||
- Compose — не Swarm: rolling-скрипт делает поочерёдную замену, но не даёт
|
||
маршрутизации между узлами.
|
||
- Профиль k6 — write-only. Он выбран намеренно: проверяется запись,
|
||
идемпотентность и БД; чтение и смешанный профиль — отдельный эксперимент.
|
||
- `X-Instance-Id` здесь — hostname контейнера, не скрыт.
|
||
- Проверка пароля и ветка «пользователь не найден» имеют разное время
|
||
выполнения: для неизвестного username Argon2 не запускается. Теоретически
|
||
это позволяет перечислять имена по времени ответа. Контракт требует только
|
||
одинаковый `401` и challenge; в lab3 временная атака не устраняется.
|