Инфраструктура лабораторной 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 не входят в проведённые исследования этой инфраструктуры.
Подтверждённые результаты
- Приёмка уровней 3/4: 16 групп PASS; собственный стенд, версии и image ID, ограничения, миграции, pool/SQL timeouts, история 20 001 сообщений с EXPLAIN, expiry и отказы.
- Реальный вывод check/smoke/persistence и summary.json: IDs всех трёх контейнеров до/после перезапуска и сохранённые volumes.
- Демонстрация кэша и отказа Redis и эксперимент stampede: результаты предшествующих сборок с их собственными параметрами и ограничениями.
- Полный отчёт: реализация, соответствие критериям, запуск и границы проведённых проверок.
Эта инструкция основана на текущих конфигурационных файлах и сохранённых результатах. При её оформлении сервисы не запускались и не перезапускались, новые тесты не добавлялись.