Files

Инфраструктура лабораторной 2

Рабочая топология описана в корневом docker-compose.yml. API собирается из исходников проекта по Dockerfile. Этот каталог содержит эксплуатационное описание решения; конфигурации сервисов остаются в корне репозитория.

compose.example.yaml — учебный worksheet, а contracts/infrastructure.json — требования к ролям. Для запуска используется именно docker-compose.yml. Подробные инструкции подготовки окружения и описание реализации находятся в 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-сеть <project>_default; сервисы обращаются друг к другу по именам postgres и redis. Отдельная сеть с internal: true не настроена. Именованные volumes получают префикс проекта: <project>_postgres_data и <project>_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.

Окружение и ключи

Все команды ниже выполняются из корня репозитория. Нужны Docker Compose v2 с поддержкой --wait, OpenSSL и Make; для проверок также Python 3.9+. На Linux для показанной настройки доступа к ключам нужна утилита setfacl.

На первом запуске создать локальный .env из .env.example, не перезаписывая существующий:

umask 077
cp -n .env.example .env

Перед запуском заменить оба password-placeholder на разные локальные пароли PostgreSQL и Redis. В REPORT.md приведена инструкция автоматической генерации .env без вывода паролей. Оставить POSTGRES_RUN_MIGRATIONS=true. Для стандартного Compose использовать POSTGRES_HOST=postgres, REDIS_HOST=redis, внутренние порты 5432/6379 и APP_PORT=8080. HOST_PORT меняет только порт API на хосте; целевой порт публикации закреплён на 8080.

На чистом окружении создать ключи подписи JWT:

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 чтение файлов и доступ к каталогу:

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. Пароли передаются через 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 встроены в бинарник через 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:<UUID> в Redis. Значение содержит метаданные и MemberIDs. Чат хранится без TTL; обязательный API не меняет состав участников. При добавлении таких изменений потребуется инвалидация, чтобы кэшированная проверка доступа не устаревала.

Сессии находятся в PostgreSQL, поэтому Redis не является единственным хранилищем аутентификации. Ошибки чтения/записи кэша обходятся через PostgreSQL. AOF и volume позволяют сохранять кэш при проверенном корректном stop/start, но не заменяют backup PostgreSQL и не доказывают сохранность при потере питания.

Собрать API, проверить доступ к ключам и запустить сервисы:

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.

Выборочные логи приложения:

docker compose --env-file .env logs --tail 100 api

Перезапуск, проверки отказов и остановка

Restart-hook сначала проверяет конфигурацию и собирает API, затем останавливает API, пересоздаёт PostgreSQL и Redis с прежними volumes, ждёт healthchecks и пересоздаёт API. Ключи и .env должны быть подготовлены заранее; hook их не генерирует и volumes не удаляет.

Обычный полный перезапуск:

./scripts/restart.sh

Hook поддерживает COMPOSE_ENV_FILE (по умолчанию .env), COMPOSE_OVERRIDE_FILE (дополнительный файл при наличии) и стандартный COMPOSE_PROJECT_NAME. Для параллельных стендов одного project name недостаточно: override должен также заменить фиксированное имя контейнера API, опубликованный порт и bind mount ключей. Это реализовано в автоматизированном runner.

Публичные проверки выполняют реальные операции с синтетическими данными указанного стенда:

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

Проверить все критерии на отдельном проекте, сохраняя новый прогон отдельно от уже приложенных доказательств:

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.

docker compose --env-file .env stop redis
docker compose --env-file .env start redis

При остановленном PostgreSQL действующая сессия получает 503, анонимный и неверный Bearer — 401; readiness возвращает 503, liveness остаётся 200. После восстановления БД прежняя сессия продолжает работать. Подробная безопасная проверка этого сценария выполняется runner на отдельном стенде.

Обычная остановка всего проекта сохраняет volumes и локальные ключи:

docker compose --env-file .env down

Намеренный сброс учебных данных: следующая команда удаляет оба именованных volume текущего проекта, включая пользователей, сообщения, сессии и кэш. Она не используется в restart-hook и не является обычным перезапуском:

docker compose --env-file .env down --volumes

При потере ключей JWT записи сессий в PostgreSQL сами по себе недостаточны для проверки ранее подписанных токенов. Volumes и ключи нужно сохранять согласованно. Backup → restore, потеря диска, HA и многорепличный failover не входят в проведённые исследования этой инфраструктуры.

Подтверждённые результаты

Эта инструкция основана на текущих конфигурационных файлах и сохранённых результатах. При её оформлении сервисы не запускались и не перезапускались, новые тесты не добавлялись.