Files
mtusi2026lab2-fork/OPERATIONS.md
2026-10-23 14:09:32 +03:00

8.4 KiB
Raw Permalink Blame History

OPERATIONS — эксплуатация кратко

Формат: что — как — для чего.

Стенд

Что Как Для чего
Три сервиса: db (PostgreSQL 16.6), redis (Redis 7.4.1, кэш сессий), api docker compose --env-file .env up -d --build Один запуск воспроизводит весь стенд
Профили: test (контейнер с pytest), expiry (api-ttl с TTL 3 с на 8081) --profile test run --rm tests, --profile expiry up -d api-ttl Тесты и проверка expiry без venv на хосте
Версии закреплены (python:3.12.8, postgres:16.6, redis:7.4.1, пакеты с транзитивными) Dockerfile, compose.yaml, requirements*.txt Сборка через год даёт то же самое, а не «latest»
API стартует после healthy db; Redis не обязателен depends_on + повторные попытки подключения к БД в коде Холодный старт не падает; без Redis API работает
API работает не от root USER app в Dockerfile Взлом приложения не даёт прав root в контейнере

Запуск, остановка, рестарт

Действие Команда Что происходит с данными
Запуск docker compose --env-file .env up -d --build Том pgdata создаётся при первом запуске
Остановка docker compose --env-file .env stop Данные остаются; кэш Redis пропадает (это нормально)
Рестарт API, Redis и БД scripts/restart.sh (Windows: scripts\restart.bat), stop+start Данные и сессии остаются; хук для make test-persistence
Пересборка API docker compose --env-file .env up -d --build api Данные остаются
Удаление данных docker compose --env-file .env down -v Том pgdata удалён, всё пропадает

Миграции

  • Файлы app/migrations/NNNN_*.sql применяются по порядку при старте API; применённые записываются в schema_migrations.
  • Повторный запуск ничего не делает. pg_advisory_lock гарантирует, что миграции выполняет один экземпляр.
  • Вручную: docker compose --env-file .env exec api python -m app.migrate.
  • Изменение схемы — новый файл 0002_*.sql, старые файлы не редактируются.

Redis (кэш сессий)

Что Как Для чего
Ключ session:<SHA-256 токена> → JSON пользователя Проверка Bearer без запроса к PostgreSQL
TTL min(CACHE_TTL_SECONDS=60, остаток сессии по часам БД) Кэш не продлевает сессию
Logout DELETE в PostgreSQL, затем revoked в Redis; заполнение — SET NX Отозванный токен не возвращается из кэша
Persistence выключена (--save "", --appendonly no) Источник истины — PostgreSQL, кэш одноразовый
Память maxmemory 64mb, noeviction Отметки отзыва не вытесняются
Посмотреть docker compose --env-file .env exec redis redis-cli --scan --pattern 'session:*', INFO stats Диагностика попаданий и промахов
Сбросить docker compose --env-file .env exec redis redis-cli FLUSHDB Безопасно: следующий запрос заполнит кэш из БД

Секреты

Что Где Для чего
Пароль БД локальный .env (в .gitignore), в образ не зашит Секрет не попадает в Git и в образ
Шаблон env.lab2.template (без реального пароля) Оператор знает, какие значения задать
Пароли пользователей в БД только scrypt с солью Утечка БД не раскрывает пароли
Токены сессий у клиента — токен; в БД и Redis — SHA-256 Утечка БД или Redis не даёт войти
Логи без тел запросов, паролей, токенов, текста сообщений Логи можно показывать и хранить
Известные ограничения пароль БД виден в docker inspect api; Redis без пароля (только внутренняя сеть) Учебный стенд; код умеет DATABASE_URL_FILE и CACHE_URL_FILE

Здоровье

Адрес Значение Для чего
/health/live Процесс жив, зависимости не проверяются Оркестратор не убивает API из-за временного сбоя БД
/health/ready Миграции применены и PostgreSQL отвечает на SELECT 1: 200 или 503. Redis не учитывается Трафик не идёт туда, где обязательный путь не работает
HEALTHCHECK образа вызывает /health/ready docker compose ps показывает healthy
pg_isready, redis-cli ping healthcheck db и redis От db зависит старт API

Поведение при сбоях

Сбой Ответ Для чего
Redis недоступен Проверка токена идёт в PostgreSQL; таймаут 300 мс, затем кэш пропускается 5 с; ready 200 Кэш не превращается в точку отказа
Logout во время сбоя Redis 204; кэш помечен «грязным» → FLUSHDB при восстановлении Отозванный токен не оживает из старой записи
БД недоступна 503 unavailable без деталей; live 200, ready 503 Клиент понимает «временно», SQL и адреса не утекают
Не удалось проверить токен 503, запрос не пропускается Сбой не превращает запрос в анонимно-доверенный
Нет свободного соединения в пуле 503 через DB_POOL_TIMEOUT Запросы не копятся при перегрузке
Неожиданная ошибка 500 internal_error, детали только в логе Клиенту ничего лишнего, оператору — request_id
Рестарт БД Данные живы (том), пул пересоздаёт соединения (pool_pre_ping) Восстановление без рестарта API
SIGTERM (docker stop) Корректное завершение: закрываются пул БД и Redis Транзакции не обрываются

Логи

docker compose --env-file .env logs -f api. Строка запроса: request request_id=… method=… path=… status=… duration_ms=…. Сбои кэша: cache_unavailable type=… и cache: FLUSHDB after a lost revocation. По request_id (он же в X-Request-Id и в теле ошибки) запрос клиента находится в логе. Уровень логов задаёт LOG_LEVEL.

Конфигурация (.env → compose)

POSTGRES_USER/PASSWORD/DB — учётка БД; SESSION_TTL_SECONDS — срок сессии (для persistence-теста ≥ 300); SESSION_STORE=postgres; DB_POOL_SIZE, DB_MAX_OVERFLOW, DB_POOL_TIMEOUT — пул; CACHE_URL (пусто — кэш выключен), CACHE_TTL_SECONDS, CACHE_TIMEOUT_MS, CACHE_RETRY_SECONDS — кэш; LOG_LEVEL, APP_ENV. Всё задаётся окружением, поэтому один образ работает на любом стенде без пересборки.