From 4382f9c0ff92c00a7eb86350c299236c9eb2d8b6 Mon Sep 17 00:00:00 2001 From: kpa39l Date: Tue, 8 Sep 2026 16:58:45 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B7=D0=B0=D0=BA=D1=80=D1=8B=D1=82?= =?UTF-8?q?=D0=B8=D0=B5=20=D1=81=D0=B5=D1=81=D1=81=D0=B8=D0=B8=202026-09-0?= =?UTF-8?q?8=20=E2=80=94=20STATUS/TODO/WALKTHROUGH/PRD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- PRD.md | 36 ++++++++++++++++++++++++ STATUS.md | 45 ++++++++++++++++++++++++++++++ TODO.md | 17 ++++++++++++ WALKTHROUGH.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 173 insertions(+) create mode 100644 PRD.md create mode 100644 STATUS.md create mode 100644 TODO.md create mode 100644 WALKTHROUGH.md diff --git a/PRD.md b/PRD.md new file mode 100644 index 0000000..e97282a --- /dev/null +++ b/PRD.md @@ -0,0 +1,36 @@ +# PRD — Мониторинг кластера + +## Цель +Единый стек мониторинга всех серверов и сервисов (Garage, tproxy, инфраструктура) +на bigbox с веб-доступом через Grafana, без публикации служебных портов наружу. + +## Пользователи +- estorozhenko (admin) — полный доступ +- гостевая учётка (readonly) — просмотр дашбордов (пароль 1qazXSW2) + +## Функциональные требования +- Метрики: Garage-кластер (3 ноды), система каждой ноды (CPU/память/диск/сеть/доступность), + tproxy (sessions/streams/traffic/backend errors), blackbox (ICMP RTT) +- Сеть: по каждому физическому интерфейсу на каждой ноде отдельный график + (RX/TX вместе) + утилизация канала (%) +- Дашборды: per-node (Node ) + Garage Cluster + Vinograd WAN + tproxy +- Алерты: garage (down/unstable), tproxy, vinograd WAN — правила в alerts.yml +- Логи: promtail → Loki → Grafana (retention 7d) + +## Нефункциональные +- Порт node-exporter и admin-эндпоинты НЕ публикуются наружу (наследие: vps03 — + только WG; garage :3903 — только WG-подсеть; tproxy :8081 — loopback+туннель) +- Катастрофоустойчивость: git gitverse (источник истины) + gitea pull-mirror на bigbox +- Retention: 30d (прометеевский TSDB) + +## Границы (НЕ делаем) +- Трейсы (до них «не доросли») +- Мониторинг сети за роутером (кроме ICMP-пробы vinograd) +- Панель авторизации вне Grafana + +## Критерии готовности +- [x] Все ноды и сервисы в Prometheus (up) +- [x] Дашборды: per-node + garage + vinograd-wan + tproxy видны в Grafana +- [x] Алерты доставляются в Grafana Alerts +- [x] README/EXPERIENCE/PLAN/STATUS/TODO/WALKTHROUGH актуальны +- [ ] Разные admin_token/metrics_token; пароль Grafana; уведомления (Telegram) \ No newline at end of file diff --git a/STATUS.md b/STATUS.md new file mode 100644 index 0000000..d45e43f --- /dev/null +++ b/STATUS.md @@ -0,0 +1,45 @@ +# Мониторинг кластера — Статус + +Обновлено: 2026-09-08 (сессия @session:default/20260908_142639_b2d5b4) + +## Текущее состояние +Стек мониторинга на bigbox (/opt/monitoring): Prometheus 2.53 + Grafana 11.1 + +Loki + promtail. Собирает: Garage-кластер (vps01/bigbox/vps02 :3903), системы +всех 4 нод (node-exporter :9100 по WireGuard), tproxy (vps03, loopback-туннель). +Дашборды: **4 per-node** (Node vps01/vps02/vps03/bigbox) + Garage Cluster + +Vinograd WAN + tproxy-панели. vps03 подключён к WG (10.8.0.3), порты наружу +не светятся. Все 4 node-таргета up. Всё в git (gitverse + gitea mirror). + +## Сделано (за сессию 2026-09-08) +- vps03 подключён к WireGuard: 10.8.0.3/24, hub vps01 (5.129.217.146:51820), + пиры добавлены на vps01/bigbox/vps02 (AllowedIPs пира vps01 расширен до + `10.8.0.1/32, 10.8.0.3/32` для возвратного трафика — грабль зафиксирован) +- node-exporter установлен на vps03 (apt), слушает 10.8.0.3:9100 (наружу 77.67.89.154:9100 закрыт) +- prometheus.yml: job `node` → 4 таргета (10.8.0.1/2/3/4:9100), все up +- Дашборды: **отдельный на каждую ноду** (uid node-), в каждом: + availability + disk free + memory + load + **Net RX/TX (bytes/s)** + + **Net utilization (%)** (физические интерфейсы, контейнерные исключены) +- README.md/EXPERIENCE.md обновлены (грабли: node_network_* метрики, speed=-125000 на виртуалках) + +## В работе / Следующие шаги +- [ ] Разные admin_token / metrics_token в Garage (совпадают) +- [ ] Поменять пароль Grafana с дефолтного (пользователь estorozhenko, пароль сменён вручную) +- [ ] Уведомления алертов (Telegram/почта) +- [ ] Проверить визуально дашборды Node в Grafana (после 1-2ч данных) + +## Как запустить / проверить +```bash +cd /opt/monitoring && docker compose ps # стек +curl -s "http://127.0.0.1:9090/api/v1/targets?state=any" | python3 -m json.tool # node ×4 up +# Grafana: http://bigbox:3001 (или https://grafana.nixg.ru) → дашборды Node vps01/02/03/bigbox +``` + +## Ключевые артефакты +- /opt/monitoring/docker-compose.yml, prometheus.yml, alerts.yml +- /opt/monitoring/grafana/dashboards/node-.json (4 шт), garage-cluster.json, vinograd-wan.json +- /opt/monitoring/grafana/provisioning/datasources/datasources.yml, dashboards/dashboards.yml +- README.md, EXPERIENCE.md, PLAN.md (в этом каталоге), STATUS.md/TODO.md/WALKTHROUGH.md + +## Открытые вопросы +- Нужен ли утилизация для vps01/vps02 с реальной скоростью линка (сейчас хардкод 1Гбит/с) +- Оставлять ли tproxy-tunnel.service (SSH-туннель) — vps03 уже в WG, туннель не нужен \ No newline at end of file diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..03c9c26 --- /dev/null +++ b/TODO.md @@ -0,0 +1,17 @@ +# TODO — Мониторинг кластера + +Формат: | дата | задача | статус | закрыта в | +|---|---|---|---| +| 2026-09-08 | vps03: установить node-exporter | ✅ закрыта | @session:default/20260908_142639_b2d5b4 | +| 2026-09-08 | vps03: подключить к WireGuard (10.8.0.3) | ✅ закрыта | @session:default/20260908_142639_b2d5b4 | +| 2026-09-08 | bigbox/vps02: AllowedIPs пира vps01 += 10.8.0.3/32 (возвратный трафик) | ✅ закрыта | @session:default/20260908_142639_b2d5b4 | +| 2026-09-08 | prometheus.yml: таргет 10.8.0.3:9100 (job node ×4) | ✅ закрыта | @session:default/20260908_142639_b2d5b4 | +| 2026-09-08 | Дашборд per-node (Node vps01/vps02/vps03/bigbox, uid node-*) | ✅ закрыта | @session:default/20260908_142639_b2d5b4 | +| 2026-09-08 | Сеть по интерфейсам: RX/TX + утилизация канала (node_network_*, speed) | ✅ закрыта | @session:default/20260908_142639_b2d5b4 | +| 2026-09-08 | EXPERIENCE.md/README.md: грабли (WG, node_network_*, speed=-125000) | ✅ закрыта | @session:default/20260908_142639_b2d5b4 | +| 2026-09-08 | Git: push в gitverse + mirror gitea | ✅ закрыта | @session:default/20260908_142639_b2d5b4 | +| — | admin_token / metrics_token в Garage — разные | 🔵 открыта | | +| — | Пароль Grafana (ручной, пользователь) | 🔵 открыта | | +| — | Уведомления алертов (Telegram/почта) | 🔵 открыта | | +| — | Утилизация vps01/vps02 с реальной скоростью (хардкод 1Гбит) | 🔵 открыта | | +| — | Удалить tproxy-tunnel.service (vps03 в WG, туннель не нужен) | 🔵 открыта | | \ No newline at end of file diff --git a/WALKTHROUGH.md b/WALKTHROUGH.md new file mode 100644 index 0000000..6719c15 --- /dev/null +++ b/WALKTHROUGH.md @@ -0,0 +1,75 @@ +# WALKTHROUGH — Мониторинг кластера (капитанский журнал) + +Хронология. Цель — воспроизводимость с нуля. Подробные грабли — в EXPERIENCE.md. + +## 2026-09-08 — vps03 в WG + per-node дашборды (сессия @session:default/20260908_142639_b2d5b4) + +### Задача +Мониторинг vps03 (77.67.89.154, Debian 13) без публикации порта наружу; +на каждую ноду отдельный дашборд с сетью по интерфейсам (RX/TX + утилизация). + +### Шаг 1. WireGuard vps03 +1. Сгенерировать ключ vps03 на bigbox: `wg genkey | tee priv | wg pubkey | tee pub` + (получили `HBTzrS86SZ+...`). +2. На vps03: `apt install wireguard-tools`, `/etc/wireguard/wg0.conf`: + ``` + [Interface] + Address = 10.8.0.3/24 + PrivateKey = + + [Peer] + PublicKey = + Endpoint = 5.129.217.146:51820 + AllowedIPs = 10.8.0.0/24 + ``` + `systemctl enable --now wg-quick@wg0`. + ⚠️ Грабль: `printf "PrivateKey = ..."` в heredoc съел пробел (`PrivateKey=...`) → + wg-quick падал. Исправлять прямой перезаписью файла. +3. На vps01 (hub): `wg set wg0 peer allowed-ips 10.8.0.3/32` + + добавить блок [Peer] в /etc/wireguard/wg0.conf (навсегда, cp .bak сначала). +4. На bigbox/vps02: тот же `wg set ... allowed-ips 10.8.0.3/32` + в файл. +5. **Грабль-звезда:** ping vps03→vps01 работает, а vps03→bigbox/vps02 — нет. + Причина: WireGuard дропает пакеты, чей src НЕ в AllowedIPs пира. У bigbox/vps02 + в AllowedIPs пира vps01 было только `10.8.0.1/32`. Решение: расширить до + `10.8.0.1/32, 10.8.0.3/32` (runtime `wg set` + файл). После этого ping OK + (vps03→bigbox 113ms, vps03→vps02 86ms). + +### Шаг 2. node-exporter vps03 +1. `apt install prometheus-node-exporter`, `/etc/default/prometheus-node-exporter`: + `ARGS="--web.listen-address=10.8.0.3:9100"` (не 127.0.0.1 — иначе по WG не достать; + не `*:` — наружу светится). +2. Проверка: `ss -tlnp | grep 9100` → 10.8.0.3:9100; `curl http://77.67.89.154:9100` → refused. +3. prometheus.yml: в job `node` добавлен таргет `10.8.0.3:9100` (relabel host=vps03). + `docker compose restart prometheus`, проверить `api/v1/targets` → node ×4 up. + +### Шаг 3. Per-node дашборды +1. Обнаружение: в node-exporter 1.9 (apt/Debian 13) метрики сети называются + `node_network_receive_bytes_total{device=...}` / `node_network_transmit_bytes_total`, + скорость линка — `node_network_speed_bytes` (Б/с). +2. Генератор `/tmp/gen_nodes_dash.py` (Python) → `grafana/dashboards/node-.json` + (uid `node-`, title "Node "): панели Availability (stat up), + Disk free GB (`node_filesystem_avail_bytes{fstype!~"tmpfs|overlay|squashfs"}`), + Memory (`node_memory_MemAvailable_bytes`), Load (load1/5/15), + Net RX/TX (`rate(...[5m])`), Net utilization + `(rx+tx)*8/speed*100`. +3. Физические интерфейсы: vps01=eth0, vps02=enp3s0, vps03=ens1, bigbox=eno1. + Контейнерные (docker0/veth*/br-*) исключены. +4. **Грабль скорости:** на виртуалках vps01/vps02 `node_network_speed_bytes` = **-125000** + (sysfs speed=-1 → exporter умножает на 125000). На физических (vps03/bigbox) = 1.25e+08. + Решение: для vps01/vps02 в формуле утилизации константа `125000000` Б/с (1 Гбит), + для vps03/bigbox — сама метрика. +5. Provisioning подхватывает дашборды автоматом (~30с, перечитывает папку). + Проверка: `docker cp grafana:/var/lib/grafana/grafana.db /tmp/gf.db`, + `SELECT uid,title FROM dashboard WHERE uid LIKE 'node-%'` → 4 строки. +6. Общий nodes.json удалён — заменён на 4 per-node дашборда. + +### Шаг 4. Git +- `git add -A && git commit` (2 коммита: WG+дашборды; EXPERIENCE-грабли) +- `git push origin master` → gitverse (6e48fd8, eaafb1f) +- gitea mirror-sync: `curl -X POST -H "Authorization: token " + http://127.0.0.1:3000/api/v1/repos/estorozhenko/monitoring/mirror-sync` → 200 + +### Итог проверки +- `api/v1/targets?state=any` → node ×4 up (10.8.0.1/2/3/4) +- grafana.nixg.ru/api/health → 200 +- Дашборды node-vps01/02/03/bigbox — в БД Графаны \ No newline at end of file