forked from mtusi2026/mtusi2026lab2
8.4 KiB
8.4 KiB
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. Всё задаётся окружением, поэтому один образ работает на любом стенде без пересборки.