Docs: add docs and drafts

2026-05-22 19:13:05 +03:00
parent 4a5db6e2bc
commit 893996f0c9
2 changed files with 367 additions and 0 deletions
@@ -0,0 +1,82 @@
+# Алерты на проблемные контейнеры
+
+## Контекст
+
+Случай с wakapi: при старте упали миграции, контейнер встал в restart-loop и
+несколько дней крутился по кругу — никто не узнал. Из этого две проблемы:
+
+1. Контейнеры могут бесконечно перезапускаться при ошибке.
+2. Нет алертов о таких ситуациях.
+
+## Что есть и что использовать
+
+- **Netdata** — Docker-collector через cgroups + Docker API: состояние,
+  restart count, healthcheck status. Алерты в `health.d/*.conf`, нотификации
+  через `health_alarm_notify.conf` (Telegram/Discord/email/ntfy).
+- **Dozzle** — только для просмотра логов после факта, нормальных алертов нет.
+- **Caddy** — мог бы участвовать в healthcheck снаружи, но это отдельный слой.
+
+## План — три слоя
+
+### 1. Healthchecks в compose (фундамент)
+
+Без них Docker считает контейнер «running», пока процесс жив, — wakapi с
+падающими миграциями этому условию удовлетворял. Добавить в каждый
+`docker-compose.yml.j2`:
+
+```yaml
+healthcheck:
+  test: ["CMD", "wget", "-q", "-O-", "http://localhost:PORT/health"]
+  interval: 30s
+  timeout: 5s
+  retries: 3
+  start_period: 60s   # окно на миграции — failed-проверки до истечения не считаются
+```
+
+`start_period` — ключевая штука для случая wakapi: даём миграциям отработать,
+до его истечения healthcheck не убивает контейнер.
+
+### 2. Алерты через Netdata (главное)
+
+Два разных сигнала:
+
+- **Restart loop** — алерт на `docker.container_state` или счётчик
+  перезапусков (растёт > N за M минут). Это и есть «контейнер крутится по
+  кругу».
+- **Unhealthy** — после healthcheck выше алерт на
+  `docker.container_health_status != healthy` дольше M минут.
+
+Канал нотификаций: один, проще всего Telegram-бот. Настройка в
+`health_alarm_notify.conf`.
+
+### 3. Restart policy — что менять (или не менять)
+
+Скорее **оставить `unless-stopped`**. Альтернативы и их минусы:
+
+- `on-failure:5` — Docker сам остановит после 5 попыток. Минус: после ребута
+  сервера сервис не поднимется (только `always`/`unless-stopped` встают на
+  старте докера). Серьёзный регресс для домашнего сервера.
+- Внешний sidecar, слушающий `docker events` и останавливающий контейнер
+  после N рестартов в окне — лишняя сложность ради того, что уже сделает
+  алерт.
+
+Лучше: алерт пришёл → решаем вручную, остановить или чинить.
+
+## Опционально (вне netdata)
+
+- **Uptime Kuma** — внешний HTTP-чек по публичным URL. Ловит случаи, когда
+  контейнер «здоров», но прокся/DNS/Caddy сломаны. Свои нотификации, дашборд.
+  Не дублирует netdata, проверяет с другой стороны.
+
+## Шаги при реализации
+
+1. Добавить healthcheck + start_period в compose-шаблоны (начать с wakapi,
+   потом по списку).
+2. Проверить, что netdata собирает Docker-метрики (collector включён).
+3. Настроить один канал нотификаций (Telegram/ntfy/email — выбрать).
+4. Написать пару алертов: restart-loop и unhealthy.
+
+## Открытые вопросы
+
+- Какой канал нотификаций использовать.
+- Добавлять ли Uptime Kuma сразу или потом.