> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axottle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Runbook'и

> Пошаговые сценарии для критических алертов здоровья: нода critical, схема critical, недоступный шлюз, офлайн-агент и деградация региона — от симптома до проверки восстановления.

Эта страница — набор готовых сценариев (runbook'ов) для типовых критических алертов. Каждый устроен одинаково: **симптом → диагностика → предложенное действие → подтверждение → проверка восстановления → когда эскалировать**. Держитесь единого порядка диагностики и не чините симптом наугад.

<Info>Для кого: администратор панели, SRE, дежурный инженер. Требуемые права: сессия администратора.</Info>

<Warning>
  Все действия восстановления — это **предложения**, которые выполняются только после вашего подтверждения. Система не перезапускает службы и не меняет конфигурацию сама. Механика подтверждения — на странице [Восстановление](/ru/health/self-heal).
</Warning>

## Порядок диагностики

Всегда идите сверху вниз — так вы не будете перезапускать службу, когда на самом деле упала сеть:

**сеть → служба → зависимости → данные → восстановление**

1. **Сеть** — доступна ли нода/шлюз по сети (L1: достижимость, DNS, порты).
2. **Служба** — запущена ли серверная часть (L2, требует агента).
3. **Зависимости** — WARP, внешние прокси, CDN, условные связи и транзитные ноды.
4. **Данные** — что показывают диагностика, ленты инцидентов и журнал: что менялось перед сбоем.
5. **Восстановление** — только теперь выбирайте и подтверждайте действие.

## Runbook: нода в critical

<Steps>
  <Step title="Симптом">
    Нода показана как `critical` на дашборде. Причина в карточке: `entry_node_down`/`transit_node_down`, `remnanode_down`/`xray_down`, нода `disconnected` в Remnawave или агент `offline`.
  </Step>

  <Step title="Диагностика">
    Откройте страницу ноды и его историю проб (`GET .../nodes/{id}/probes`). По порядку: **сеть** — прошла ли достижимость (L1); **служба** — что говорит L2 (нужен онлайн-агент); **данные** — соберите логи через действие `view_remnanode_logs`/`view_xray_logs` (только чтение) и посмотрите журнал: не совпал ли сбой с недавним изменением.
  </Step>

  <Step title="Предложенное действие">
    Система предложит подходящее к причине: `drain_node` (убрать ноду из пула), `recheck` (если агент онлайн) и перезапуск службы с учётом runtime (`restart_remnanode` или `restart_xray`). Если агент оффлайн, кнопки перезапуска будут недоступны с подсказкой-причиной.
  </Step>

  <Step title="Подтверждение">
    Подтвердите нужное действие (`POST .../actions/{id}/confirm`). Если пользователей нужно немедленно увести с проблемного ноды — сначала `drain_node`, затем разбирайтесь со службой.
  </Step>

  <Step title="Проверка восстановления">
    Запустите `POST .../nodes/{id}/check`; убедитесь, что достижимость и служба вернулись в `ok`, а сводный статус ноды — `healthy`.
  </Step>

  <Step title="Когда эскалировать">
    Если после перезапуска службы нода снова падает, либо агент так и не выходит на связь, — соберите support bundle и эскалируйте по [Реагированию на инциденты](/ru/operations/incident-response).
  </Step>
</Steps>

## Runbook: схема (Connection Unit) в critical

<Steps>
  <Step title="Симптом">
    Схема показана `critical`. Возможные причины по кворуму: потерян кворум входных нод (`<50%` здоровых или 0 здоровых), недоступен шлюз, устойчивый отказ сквозной пробы со стороны ноды, дрейф конфигурации (`config_drift`).
  </Step>

  <Step title="Диагностика">
    Откройте карточку схемы и её диагностику (`GET .../connection-units/{id}/diagnostics`) — там свежие пробы, связанные записи журнала и метаданные нод. По порядку: **сеть** (шлюз и входные ноды достижимы?), **служба** (ноды отвечают на L2?), **зависимости** (транзит/маршруты/WARP/прокси), **данные** (что менялось: применение конфигурации, обновление, политика).
  </Step>

  <Step title="Предложенное действие">
    К causе `config_drift` система предложит `reapply_config` на уровне схемы, а к critical — дополнительно `rollback_unit_version`. По конкретным нодам будут предложения из runbook'а ноды (drain/restart/recheck).
  </Step>

  <Step title="Подтверждение">
    <Warning>
      В текущей сборке `reapply_config` и `rollback_unit_version` **не реализованы**: их подтверждение завершается ошибкой. Фактическое повторное применение конфигурации и откат версии выполняйте на страницах Connection Units — см. [Обзор Connection Units](/ru/connection-units/overview). Действия по нодам (`drain_node`, `restart_*`, `recheck`) работают штатно.
    </Warning>
  </Step>

  <Step title="Проверка восстановления">
    Запустите `POST .../connection-units/{id}/check` (один сквозной проход). Схема должна вернуться в `healthy`, а серия неуспешных проверок — обнулиться.
  </Step>

  <Step title="Когда эскалировать">
    Если кворум не восстанавливается после починки нод, либо дрейф конфигурации повторяется после повторного применения, — эскалируйте с приложением диагностики и журнала.
  </Step>
</Steps>

## Runbook: шлюз недоступен

<Steps>
  <Step title="Симптом">
    Схема в `critical` с причиной недоступности шлюза (`gateway_unreachable`). Пока шлюз недоступен, входные ноды не важны — путь для пользователя разорван.
  </Step>

  <Step title="Диагностика">
    Начните с **сети**: прошла ли базовая достижимость шлюза (L1 — DNS, TCP до нужных портов). Затем **служба** на ноде-шлюзе (L2), затем **зависимости** (не заблокирован ли путь фаерволом/провайдером). Сверьтесь с журналом: не было ли изменения сети или конфигурации.
  </Step>

  <Step title="Предложенное действие">
    Если gateway-нода сама недоступна — используйте runbook ноды (перезапуск службы с учётом runtime, `recheck`). Если проблема сетевая и находится вне ноды, восстановление выполняется на стороне инфраструктуры или провайдера.
  </Step>

  <Step title="Подтверждение">
    Подтвердите перезапуск службы, только если L2 показывает, что служба упала. Если сеть внешняя — сначала устраните её, действие в панели тут не поможет.
  </Step>

  <Step title="Проверка восстановления">
    `POST .../connection-units/{id}/check`: достижимость шлюза — `ok`, схема — `healthy`.
  </Step>

  <Step title="Когда эскалировать">
    Если шлюз доступен по сети, но схема остаётся critical, — это уже не «шлюз», разбирайтесь по runbook'у схемы. Если недоступность сетевая и вне вашего контроля — эскалируйте провайдеру/инфраструктуре.
  </Step>
</Steps>

## Runbook: агент offline

<Steps>
  <Step title="Симптом">
    Агент ноды показан `offline`; в ленте — инцидент по агенту, в Telegram — категория `agent_offline`. Агент помечается offline автоматически после 90 секунд без heartbeat.
  </Step>

  <Step title="Диагностика">
    Ключевой вопрос: нода жива, но молчит агент — или нода действительно упала? Смотрите **сеть**: пробы достижимости (L1) идут со стороны панели и **не зависят** от агента. Если L1 в порядке, а L2 недоступен — проблема, скорее всего, в самом агенте, а не в ноде.
  </Step>

  <Step title="Предложенное действие">
    Пока агент оффлайн, действия, требующие агента (перезапуски, сбор логов, установка WARP), **недоступны** — кнопки серые с причиной. Доступен `recheck` и, при необходимости увести трафик, `drain_node`.
  </Step>

  <Step title="Подтверждение">
    Если проба L1 успешна, обычно достаточно дождаться возврата агента и выполнить `recheck`. Восстановление агента как службы выполняется на хосте ноды (см. [Жизненный цикл ноды](/ru/nodes/lifecycle)).
  </Step>

  <Step title="Проверка восстановления">
    Как только heartbeat вернётся, агент и нода автоматически выйдут из `offline`. Подтвердите `recheck` и убедитесь, что нода — `healthy`.
  </Step>

  <Step title="Когда эскалировать">
    Если L1 тоже падает — это не только агент, а недоступность ноды: идите по runbook'у ноды. Если агент не поднимается на живом ноде — соберите support bundle и эскалируйте.
  </Step>
</Steps>

<Note>
  Помните: сами по себе офлайн-агенты не делают глобальный дашборд `critical` — максимум `degraded`. Реальную недоступность ноды независимо покажут его пробы достижимости.
</Note>

## Runbook: деградация региона (внешние пробы)

<Steps>
  <Step title="Симптом">
    Внешние региональные пробы (L5) сообщают о недоступности ноды «снаружи», хотя изнутри он выглядит живым. Причина — `external_regional_failure`.
  </Step>

  <Step title="Диагностика">
    Сопоставьте картину: **сеть** изнутри (L1/L4 со стороны панели) — в порядке? Если да, а внешняя проба падает — проблема на пути между регионом и нодой (блокировка, маршрутизация провайдера), а не в самой ноде. Проверьте, для каких блоков включён L5 и что говорят разные провайдеры. Если ни один провайдер не подключён, статус `external_probe_unavailable` — это не сбой.
  </Step>

  <Step title="Предложенное действие">
    Региональная блокировка обычно не лечится действием в панели: нода исправна, недоступен путь. Восстановление — на уровне маскировки/маршрутизации/инфраструктуры. Health здесь — сигнал и подтверждение возврата, а не кнопка «починить».
  </Step>

  <Step title="Подтверждение">
    Не перезапускайте службу «на всякий случай», если изнутри всё зелёное: это не устранит региональную недоступность. Действуйте по причине, а не по симптому.
  </Step>

  <Step title="Проверка восстановления">
    Повторите внешнюю пробу для затронутого блока; убедитесь, что регион снова видит ноду. Изнутри статус при этом мог и не меняться.
  </Step>

  <Step title="Когда эскалировать">
    Устойчивая региональная деградация при исправном ноде — повод для разбирательства с маскировкой/инфраструктурой и, при необходимости, эскалации.
  </Step>
</Steps>

## Проверка

После восстановления связанные предложения действий снимаются автоматически, а запись в ленте переходит в `auto_resolved`.

## Откат

Эта страница описывает процесс — откатывать нечего. Откаты конкретных действий восстановления описаны там, где эти действия выполняются:

* вывод ноды из пула (`drain_node`) отменяется действием `undrain_node` — см. [Восстановление](/ru/health/self-heal);
* повторное применение конфигурации и откат версии схемы — на страницах [Connection Units](/ru/connection-units/overview);
* подавление ноды снимается на странице [Подавление нод](/ru/health/suppression).

## Типовые ошибки

<AccordionGroup>
  <Accordion title="Перезапустил службу, а причина была в сети">
    Соблюдайте порядок: сеть → служба → зависимости. Если L1 падает, перезапуск службы не поможет — проблема ниже по стеку.
  </Accordion>

  <Accordion title="Ждал, что reapply_config/rollback починят схему">
    В текущей сборке эти действия не реализованы и завершаются ошибкой. Реальное повторное применение и откат версии — на страницах Connection Units.
  </Accordion>

  <Accordion title="Гонял recheck, а он не эскалирует к critical">
    Так и должно быть: ручная проверка делает один проход и не выставляет critical со стороны ноды. Устойчивый отказ фиксирует только плановая проверка (несколько попыток).
  </Accordion>
</AccordionGroup>

Связанные страницы: [Восстановление](/ru/health/self-heal), [Дашборд здоровья](/ru/health/dashboard), [Состояния и severity](/ru/health/states), [Реагирование на инциденты](/ru/operations/incident-response), [Жизненный цикл ноды](/ru/nodes/lifecycle), [Обзор Connection Units](/ru/connection-units/overview).

<Note>Проверено для версии Axottle текущей ветки. Дата проверки: 2026-07-11.</Note>