Runbook реагирования на инциденты

Паспорт документа

• Статус документа: working reference
• Актуально на: 29 марта 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении production runtime, ownership-модели, мониторинга или rollback-процедуры
• Область применения: production-инциденты Qadam на текущем host-based контуре
• Связанные документы:
  • Runbook эксплуатации и деплоя
  • Runbook резервного копирования и восстановления
  • Environment matrix

Цель документа

Этот документ фиксирует канонический порядок действий при production-инциденте. Его задача — убрать импровизацию и сделать реакцию воспроизводимой для любой команды, которая сопровождает Qadam.

1. Уровни серьёзности

• SEV-1 — полная недоступность продукта или риск потери/компрометации данных.
• SEV-2 — критичный broken flow для значимой части пользователей, но без полной потери сервиса.
• SEV-3 — частичный сбой, деградация производительности или дефект без немедленного простоя ядра.

2. Первые 15 минут

1. Зафиксировать UTC-время начала инцидента.
2. Заморозить деплой и любые несвязанные ручные изменения на сервере.
3. Определить, что именно упало:
   • qadam-api
   • qadam-web
   • qadam-roadmap
   • nginx
   • PostgreSQL
   • Redis
   • TLS / домен
4. Проверить живые health endpoints.
5. Принять решение: hotfix, restart, rollback или restore.

3. Быстрая диагностика

Сервисы

systemctl status qadam-api qadam-web qadam-roadmap nginx
journalctl -u qadam-api -n 200 --no-pager
journalctl -u qadam-web -n 200 --no-pager
journalctl -u qadam-roadmap -n 200 --no-pager
journalctl -u nginx -n 200 --no-pager

Внешняя доступность

curl -I https://qadam.2fab.app
curl https://qadam.2fab.app/api/v1/health
curl -I https://qadam.2fab.app/api/docs
curl -I -u <login>:<password> https://qadam-roadmap.2fab.app
curl -u <login>:<password> https://qadam-roadmap.2fab.app/api/health

Сетевые сокеты

ss -ltnp | grep -E ':(80|443|3000|3001|5001|5432|6379)\b'

4. Типовые сценарии

API недоступен

Проверить:

• qadam-api.service;
• сборку /data/qadam-core/apps/api/dist/main.js;
• Prisma migrations;
• локальную доступность PostgreSQL и Redis;
• ошибки в journalctl -u qadam-api.

Если проблема в последнем релизе:

1. Откатить код к предыдущему рабочему коммиту.
2. Пересобрать qadam-core.
3. Перезапустить qadam-api.

Если проблема в данных или миграции:

1. Оценить, можно ли обойтись rollback кода.
2. Если нет, перейти к backup/restore runbook.

Product web недоступен

Проверить:

• qadam-web.service;
• наличие .next/standalone/apps/web/server.js;
• symlink на public и .next/static;
• API_URL и NEXT_PUBLIC_API_URL;
• ошибки в journalctl -u qadam-web.

Roadmap-портал недоступен

Проверить:

• qadam-roadmap.service;
• QADAM_PROJECT_ROOT=/data/qadam-core;
• QADAM_ROADMAP_STORAGE_DIR=/var/lib/qadam-roadmap;
• basic auth на уровне nginx;
• journalctl -u qadam-roadmap.

TLS или домен

Проверить:

systemctl status certbot.timer
certbot certificates
nginx -t
systemctl reload nginx

Auth или cookie-flow сломан

Проверить:

• JWT_SECRET и env drift;
• qadam_at, qadam_rt cookie behavior;
• POST /api/v1/auth/login, POST /api/v1/auth/refresh, GET /api/v1/auth/me;
• доменные ошибки ACCOUNT_BLOCKED, ACCOUNT_UNDER_REVIEW, INVALID_CREDENTIALS;
• совпадение runtime OpenAPI и docs/architecture/api-routes.md.

5. Когда делать rollback

Rollback обязателен, если выполняется хотя бы одно из условий:

• SEV-1, вызванный последним change package;
• критичный бизнес-flow перестал работать после релиза;
• hotfix не устраняет проблему в разумное время;
• ошибка связана с runtime drift или broken build, а не с внешней зависимостью.

Rollback выполняется по deployment-runbook.md, а при риске потери данных — совместно с backup-restore-runbook.md.

6. Что обязательно зафиксировать после инцидента

• время начала и окончания;
• уровень SEV;
• затронутые сервисы и домены;
• root cause или текущую гипотезу;
• какие действия сработали;
• нужен ли follow-up change package;
• требуется ли обновление current-state, deployment-runbook, environment-matrix или project/project-change-log.md.

7. Пост-инцидентные действия

После восстановления обязательно:

1. Обновить каноническую документацию, если инцидент выявил ложные допущения.
2. Добавить regression test, если сбой был вызван кодом.
3. Добавить запись в project/project-change-log.md, если был hotfix, rollback или изменение runtime.
4. Обновить project/execution-checkpoints.md, если статус крупного этапа изменился.

8. Чего нельзя делать

• Нельзя лечить инцидент ручной магией без фиксации действий.
• Нельзя менять production secrets и env без документирования.
• Нельзя выполнять разрушительные git-команды без понимания состояния рабочей директории.
• Нельзя объявлять инцидент закрытым без минимального smoke-check после восстановления.