chore(home): mirror from kalinamall (b0abf99) with papatramp URLs

2026-07-14 20:43:55 +10:00
commit 10704e0f88
40 changed files with 7253 additions and 0 deletions
@@ -0,0 +1,40 @@
+# SAC ingest: таймауты и fallback
+
+Документ для эксплуатации **ssh-monitor** с `UseSAC=fallback` или `exclusive` при нагрузке на SAC (массовый update агентов, deploy backend).
+
+См. также: [ingest-mass-update-backlog.ru.md](https://git.papatramp.ru/PapaTramp/security-alert-center/src/branch/main/docs/ingest-mass-update-backlog.ru.md) (SAC + ops).
+
+## `SAC_TIMEOUT_SEC`
+
+Таймаут **connect** и **max-time** для `curl` к SAC (`/health`, `POST /api/v1/events`).
+
+| Сценарий | Рекомендация |
+|----------|--------------|
+| Обычная нагрузка | **45** (дефолт в `ssh-monitor.conf.example` и при миграции с 12) |
+| Массовый restart агентов, тяжёлый ingest на SAC | **60–90** на время окна обслуживания |
+| SAC на том же хосте перезапускается (`sac-deploy`) | Кратковременные отказы POST — норма; не поднимать таймаут «навсегда» без причины |
+
+На стороне SAC (nginx) для ingest задан `proxy_read_timeout 120s` на `POST /api/v1/events`. Агентский таймаут **не обязан** равняться 120: достаточно, чтобы POST не обрывался раньше типичного ответа API. При `SAC_TIMEOUT_SEC` меньше nginx-лимита агент уйдёт в spool и `sac-fail.count`, а не «висит» минутами.
+
+Проверка после смены:
+
+```bash
+sudo ssh-monitor --check-config
+sudo ssh-monitor --check-sac
+```
+
+## `sac-fail.count` и режим `fallback`
+
+При ошибке POST ingest счётчик в `SAC_FAIL_COUNT_FILE` увеличивается. После **`SAC_FALLBACK_FAILURES`** подряд (по умолчанию 5) агент перестаёт слать в SAC и шлёт только в локальный Telegram, пока `/health` снова не станет OK.
+
+**Сброс счётчика:** любой успешный POST (в т.ч. heartbeat) обнуляет `sac-fail.count`.
+
+**Shutdown / SIGTERM (с 2.3.2-SAC):** при остановке монитора (`systemctl stop`, restart во время SAC-update) неудачный lifecycle POST **не увеличивает** счётчик — иначе после штатного restart пачки хостов агент ложно уходит в Telegram-fallback.
+
+Lifecycle при SAC-update по-прежнему **пропускается**, если существует state-file `agent-update-in-progress` (см. `update_ssh_monitor.sh`).
+
+## Операционные правила
+
+1. Не совмещать `sudo /opt/sac-deploy.sh` и массовое «Обновить ssh-monitor» по многим хостам в одно окно.
+2. Обновлять Linux-хосты **пачками по 2–3**.
+3. На зрелых хостах — **`UseSAC=exclusive`**, если локальный Telegram при fallback не нужен.