From 4e67ba0306b6d26f83908112a326e991cb9f3ffb Mon Sep 17 00:00:00 2001 From: Grbisba Date: Fri, 6 Nov 2026 14:17:12 +0300 Subject: [PATCH] =?UTF-8?q?=D0=92=D0=B5=D1=80=D0=BD=D1=83=D0=BB=20=D0=BF?= =?UTF-8?q?=D0=BE=D1=82=D0=B5=D1=80=D1=8F=D0=BD=D0=BD=D1=8B=D0=B9=20infra/?= =?UTF-8?q?README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- infra/README.md | 233 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 infra/README.md diff --git a/infra/README.md b/infra/README.md new file mode 100644 index 0000000..23f4ca5 --- /dev/null +++ b/infra/README.md @@ -0,0 +1,233 @@ +# Инфраструктура лабораторной 2 + +Рабочая топология описана в корневом [docker-compose.yml](../docker-compose.yml). API собирается из исходников проекта +по [Dockerfile](../Dockerfile). Этот каталог содержит эксплуатационное описание решения; конфигурации сервисов остаются +в корне репозитория. + +[compose.example.yaml](../compose.example.yaml) — учебный worksheet, +а [contracts/infrastructure.json](../contracts/infrastructure.json) — требования к ролям. Для запуска используется +именно docker-compose.yml. Подробные инструкции подготовки окружения и описание реализации находятся +в [REPORT.md](../REPORT.md). + +## Сервисы и топология + +| Роль | Service name | Образ / версия | Healthcheck / readiness | Постоянное хранилище | Сеть и порты | Credentials | +|--------------------------|--------------|------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------| +| HTTP API | `api` | Локальная сборка `mtusi-messenger:lab2`; builder `golang:1.27.2-alpine3.23`, runtime `alpine:3.23.6` | Docker healthcheck вызывает `/health/ready`; обработчик проверяет HTTP-сервер и PING PostgreSQL с бюджетом 200 мс | Прикладные данные находятся в PostgreSQL; `./certs` смонтирован в `/run/certs` только для чтения | Внутри `0.0.0.0:8080`; на хосте `127.0.0.1:${HOST_PORT:-8080}` | Подключения к хранилищам из env; RSA-ключи из bind mount; клиентские запросы — Basic при входе и Bearer после входа | +| Источник истины | `postgres` | `postgres:17.11-alpine3.23` | `pg_isready` по TCP localhost с заданными пользователем и БД | `postgres_data:/var/lib/postgresql/data` | `postgres:5432` внутри сети, порт на хост не опубликован | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`; Compose получает имя БД из `POSTGRES_DATABASE` | +| Необязательный кэш чатов | `redis` | `redis:8.2.11-alpine3.22` | Аутентифицированный `redis-cli PING`, ожидается `PONG` | `redis_data:/data`; AOF включён | `redis:6379` внутри сети, порт на хост не опубликован | `REDIS_PASSWORD`; сервер запущен с `--requirepass`, API использует пользователя `default` и выбранную Redis DB | + +Compose создаёт проектную bridge-сеть `_default`; сервисы обращаются друг к другу по именам `postgres` и +`redis`. Отдельная сеть с `internal: true` не настроена. Именованные volumes получают префикс проекта: +`_postgres_data` и `_redis_data`. В стандартном запуске контейнер API явно называется `api`. + +PostgreSQL обязателен: `depends_on` API ожидает его `service_healthy` при запуске. Redis в `depends_on` API не включён; +ошибка стартового PING логируется, приложение продолжает работать через PostgreSQL. Его реквизиты подключения всё равно +должны присутствовать в конфигурации. + +API работает от UID/GID `65532:65532`. Политика перезапуска всех трёх сервисов — `unless-stopped`. Время штатной +остановки контейнера: API 10 секунд, PostgreSQL 60 секунд, Redis 30 секунд; HTTP graceful shutdown по умолчанию +ограничен 8 секундами. + +### Health и готовность + +- `/health/live` возвращает состояние HTTP-процесса и не проверяет хранилища. +- `/health/ready` возвращает 200 при работающем HTTP-сервере и доступном PostgreSQL; при отказе БД — 503. Redis не + влияет на readiness. +- Docker healthcheck API выполняется каждые 10 секунд, timeout 3 секунды, start period 5 секунд, retries 3. +- Healthcheck PostgreSQL выполняется каждые 5 секунд, timeout 3 секунды, start period 30 секунд, retries 12. +- Healthcheck Redis выполняется каждые 5 секунд, timeout 3 секунды, start period 5 секунд, retries 12. Пароль передаётся + redis-cli через `REDISCLI_AUTH` внутри контейнера, его значение в вывод не включается. + +Версии базовых образов закреплены тегами в Dockerfile и Compose. Тег собственного образа `mtusi-messenger:lab2` +обновляется при локальной сборке. ID образа, на котором прошла приёмка уровней 3/4: +`sha256:0effe11ab9f4d860b5b79d6096ff95325336c752c0d5ca335878ec89baf4f269`. Это идентификатор проверенной сборки, а не +утверждение о текущем содержимом локального тега или registry digest. Commit, SHA-256 исходников и параметры того +прогона находятся в [summary.json](../evidence/levels-3-4/summary.json). + +## Окружение и ключи + +Все команды ниже выполняются **из корня репозитория**. Нужны Docker Compose v2 с поддержкой `--wait`, OpenSSL и Make; +для проверок также Python 3.9+. На Linux для показанной настройки доступа к ключам нужна утилита `setfacl`. + +На первом запуске создать локальный `.env` из [.env.example](../.env.example), не перезаписывая существующий: + +```sh +umask 077 +cp -n .env.example .env +``` + +Перед запуском заменить оба password-placeholder на разные локальные пароли PostgreSQL и Redis. В REPORT.md +приведена [инструкция](../REPORT.md) автоматической генерации `.env` без вывода паролей. Оставить +`POSTGRES_RUN_MIGRATIONS=true`. Для стандартного Compose использовать `POSTGRES_HOST=postgres`, `REDIS_HOST=redis`, +внутренние порты 5432/6379 и `APP_PORT=8080`. `HOST_PORT` меняет только порт API на хосте; целевой порт публикации +закреплён на 8080. + +На чистом окружении создать ключи подписи JWT: + +```sh +umask 077 +if [ ! -e certs/private_key.pem ] && [ ! -e certs/public_key.pem ]; then + make key-gen +fi +test -f certs/private_key.pem && test -f certs/public_key.pem +chmod 600 certs/private_key.pem +chmod 644 certs/public_key.pem +``` + +Команда генерирует пару только при отсутствии обоих файлов. Если сохранилась только одна часть, сначала нужно восстановить согласованную пару; автоматически перезаписывать оставшуюся часть нельзя. Повторно генерировать уже используемую пару при обычном запуске или рестарте не нужно: прежние сессии требуют прежнего +ключа проверки подписи. Ключи не являются TLS-сертификатами; локальный API использует HTTP. + +На Linux предоставить контейнерному UID чтение файлов и доступ к каталогу: + +```sh +setfacl -m u:65532:rx certs +setfacl -m u:65532:r certs/private_key.pem certs/public_key.pem +``` + +На Docker Desktop отображение прав зависит от файлового backend. Проверка чтения из контейнера приведена в разделе +запуска. Приватный ключ не требуется делать общедоступным. В `.env` задаются контейнерные пути +`/run/certs/private_key.pem` и `/run/certs/public_key.pem`; bind mount доступен только для чтения, а +`create_host_path: false` не позволяет незаметно создать отсутствующий каталог. + +`.env`, каталог `certs/`, локальные `secrets/`, данные и volumes исключены из Git правилами [.gitignore](../.gitignore). +Пароли передаются через environment контейнеров; Docker secrets в этом Compose не используются. Не сохранять полный +вывод `docker compose config` или credentials в отчёт; для проверки конфигурации достаточно `config --quiet`. + +### Основные параметры + +| Настройка | Значение и поведение | +|-------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `POSTGRES_RUN_MIGRATIONS`, `POSTGRES_VERSION_TABLE` | `true`, `versions` в примере; включают миграции API и учёт их версии | +| `POSTGRES_MAX_CONNECTIONS` | Максимум соединений пула API, по умолчанию 10 | +| `POSTGRES_CONNECT_TIMEOUT` | По умолчанию 500 мс | +| `POSTGRES_QUERY_TIMEOUT` | По умолчанию 2 секунды; контекст бизнес-запроса и statement_timeout соединений приложения | +| `SESSION_TTL_SECONDS` | Положительное целое число секунд; в примере 3600. Имеет приоритет над legacy `JWT_REFRESH_TOKEN_LIFETIME`; при отсутствии обеих переменных — 3600 секунд | +| `REDIS_DB` | По умолчанию 0; ключи кэша находятся в выбранной DB | +| Таймауты Redis | Dial/read/write/pool по 200 мс; отдельный бюджет GET/SET/PING 300 мс; повторы команд отключены | +| `APP_READ_TIMEOUT`, `APP_WRITE_TIMEOUT`, `APP_IDLE_TIMEOUT` | По умолчанию 5, 10 и 60 секунд | + +Параметры Compose и содержимое `.env.example` не заменяют настройки уже существующего хранилища. Например, замена +`POSTGRES_PASSWORD` в `.env` не меняет пароль роли, ранее созданной в сохранённом PostgreSQL volume. При повторном +использовании данных сохранять согласованные реквизиты, имя БД и ключи JWT. + +## Bootstrap и повторный запуск + +На новом volume entrypoint PostgreSQL создаёт роль и БД из environment. Схему приложения создаёт API: +SQL-миграции [service/migrations](../service/migrations) встроены в бинарник через `go:embed` и применяются Tern до +запуска HTTP-сервера. Отдельного SQL-bootstrap в Compose нет. + +Пять миграций создают `users`, `refresh_tokens`, `chats`, `chat_members`, `messages`, ограничения и индексы. Таблица +`versions` хранит версию Tern. При повторном запуске применяются только ещё не выполненные миграции; данные не +пересоздаются и не заполняются повторно. Обычный старт не создаёт экспериментальные fixtures. При ошибке миграции API +завершает запуск с ошибкой. Отключать миграции на пустом volume нельзя, если схема не подготовлена отдельно. + +Redis запускается с `appendonly yes` и `appendfsync everysec`. Отдельного bootstrap кэша нет: первый доступный участнику +GET чата читает PostgreSQL и сохраняет `chat:` в Redis. Значение содержит метаданные и MemberIDs. Чат хранится без +TTL; обязательный API не меняет состав участников. При добавлении таких изменений потребуется инвалидация, чтобы +кэшированная проверка доступа не устаревала. + +Сессии находятся в PostgreSQL, поэтому Redis не является единственным хранилищем аутентификации. Ошибки чтения/записи +кэша обходятся через PostgreSQL. AOF и volume позволяют сохранять кэш при проверенном корректном stop/start, но не +заменяют backup PostgreSQL и не доказывают сохранность при потере питания. + +Собрать API, проверить доступ к ключам и запустить сервисы: + +```sh +docker compose --env-file .env config --quiet +docker compose --env-file .env build api +docker compose --env-file .env run --rm --no-deps --entrypoint sh api \ + -c 'test -r /run/certs/private_key.pem && test -r /run/certs/public_key.pem' +docker compose --env-file .env up -d --no-build --wait --wait-timeout 120 +curl --fail --silent --show-error http://127.0.0.1:8080/health/live +curl --fail --silent --show-error http://127.0.0.1:8080/health/ready +docker compose --env-file .env ps -a +``` + +При изменённом `HOST_PORT` заменить порт в curl. Повторный `up` использует прежние volumes. После изменения исходников +нужна новая сборка API; после изменения environment — пересоздание соответствующего контейнера, а не только `start`. + +Выборочные логи приложения: + +```sh +docker compose --env-file .env logs --tail 100 api +``` + +## Перезапуск, проверки отказов и остановка + +[Restart-hook](../scripts/restart.sh) сначала проверяет конфигурацию и собирает API, затем останавливает API, +пересоздаёт PostgreSQL и Redis с прежними volumes, ждёт healthchecks и пересоздаёт API. Ключи и `.env` должны быть +подготовлены заранее; hook их не генерирует и volumes не удаляет. + +Обычный полный перезапуск: + +```sh +./scripts/restart.sh +``` + +Hook поддерживает `COMPOSE_ENV_FILE` (по умолчанию `.env`), `COMPOSE_OVERRIDE_FILE` (дополнительный файл при наличии) и +стандартный `COMPOSE_PROJECT_NAME`. Для параллельных стендов одного project name недостаточно: override должен также +заменить фиксированное имя контейнера API, опубликованный порт и bind mount ключей. Это реализовано +в [автоматизированном runner](../scripts/verify_lab2.py). + +Публичные проверки выполняют реальные операции с синтетическими данными указанного стенда: + +```sh +make check +make test BASE_URL=http://127.0.0.1:8080 +make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080 +``` + +Проверить все критерии на отдельном проекте, сохраняя новый прогон отдельно от уже приложенных доказательств: + +```sh +python3 scripts/verify_lab2.py --port 18084 --output evidence/levels-3-4-repeat +``` + +Runner создаёт собственные ключи, пароли и volumes, проверяет миграции, полный рестарт, expiry и отказы. В конце +проверочный проект останавливается без удаления volumes; основной стенд на 8080 не перезапускается. + +Для отдельной проверки отказа Redis используются команды ниже. Между stop и start авторизованный GET должен +обслуживаться из PostgreSQL. После start дождаться готовности Redis и повторить запрос; действительный Bearer-токен не +следует сохранять в журналы команд или evidence. + +```sh +docker compose --env-file .env stop redis +docker compose --env-file .env start redis +``` + +При остановленном PostgreSQL действующая сессия получает 503, анонимный и неверный Bearer — 401; readiness возвращает +503, liveness остаётся 200. После восстановления БД прежняя сессия продолжает работать. Подробная безопасная проверка +этого сценария выполняется runner на отдельном стенде. + +Обычная остановка всего проекта сохраняет volumes и локальные ключи: + +```sh +docker compose --env-file .env down +``` + +**Намеренный сброс учебных данных:** следующая команда удаляет оба именованных volume текущего проекта, включая +пользователей, сообщения, сессии и кэш. Она не используется в restart-hook и не является обычным перезапуском: + +```sh +docker compose --env-file .env down --volumes +``` + +При потере ключей JWT записи сессий в PostgreSQL сами по себе недостаточны для проверки ранее подписанных токенов. +Volumes и ключи нужно сохранять согласованно. Backup → restore, потеря диска, HA и многорепличный failover не входят в +проведённые исследования этой инфраструктуры. + +## Подтверждённые результаты + +- [Приёмка уровней 3/4](../evidence/levels-3-4/README.md): 16 групп PASS; собственный стенд, версии и image ID, + ограничения, миграции, pool/SQL timeouts, история 20 001 сообщений с EXPLAIN, expiry и отказы. +- [Реальный вывод check/smoke/persistence](../evidence/levels-3-4/checks.txt) + и [summary.json](../evidence/levels-3-4/summary.json): IDs всех трёх контейнеров до/после перезапуска и сохранённые + volumes. +- [Демонстрация кэша и отказа Redis](../evidence/redis-cache.md) + и [эксперимент stampede](../evidence/cache-stampede/README.md): результаты предшествующих сборок с их собственными + параметрами и ограничениями. +- [Полный отчёт](../REPORT.md): реализация, соответствие критериям, запуск и границы проведённых проверок. + +Эта инструкция основана на текущих конфигурационных файлах и сохранённых результатах. При её оформлении сервисы не +запускались и не перезапускались, новые тесты не добавлялись.