Этап 6 tproxy: конкретные шаги (nft 8081 для bigbox 178.176.197.2 + job prometheus), опыт в EXPERIENCE, README

EXPERIENCE.md

@@ -124,7 +124,62 @@ grafana.nixg.ru {
 - В логах caddy много ошибок renew для старых доменов — они имеют
   уже выпущенные сертификаты в caddy_data, работает всё.
 
-## Проверка результата
+## Опыт: tproxy-server (WEB Proxy для Telegram Desktop) на vps03
+
+> Дата: 2026-08-31
+> Ситуация: развернули telegramdesktop/tproxy-server на vps03 (77.67.89.154,
+> Debian 13): Caddy → tproxy-server:8080 → MTProxy:2398.
+> Домен vps03.nixg.ru (HTTPS), порты 80/443 открыты из интернета.
+
+### A. Архитектура и порты
+
+- Внешний вход: `https://vps03.nixg.ru:443` → Caddy → `127.0.0.1:8080` (tproxy-server)
+  → `127.0.0.1:2398` (MTProxy).
+- tproxy-server config: `/etc/tproxy-server/config.json` (600 root:tproxy).
+- Профили/секреты: `/etc/tproxy-server/profiles.json` — массив профилей,
+  **можно несколько секретов** (max_profiles: 32 в config). systemd читает их
+  через `LoadCredential=profiles.json:/etc/tproxy-server/profiles.json`
+  (файл должен быть 600 root, иначе падает — тест
+  TestLoadAcceptsSystemdCredentialReadPermissions).
+- Формат секрета: 16 байт = 32 hex (`openssl rand -hex 16`), либо 17 байт
+  с префиксом `dd` (fake-TLS-режим).
+- Добавить секрет: дописать профиль в profiles.json, `chmod 600`, `chown root:tproxy`,
+  `systemctl restart tproxy-server` → в логе `profiles=N`, readyz 200.
+- Отозвать секрет: убрать профиль из profiles.json + restart.
+
+### B. Admin-эндпоинты (только loopback 127.0.0.1:8081)
+
+| Эндпоинт | Ответ |
+|---|---|
+| /healthz | всегда `ok` 200 (процесс жив) |
+| /readyz | 200 `ready` / 503 `backend unavailable` — TCP-проба ко ВСЕМ backend-профилям (у нас 127.0.0.1:2398) |
+| /metrics | Prometheus-формат (text/plain version 0.0.4), 13 счётчиков |
+
+Метрики (все с префиксом `tproxy_`): sessions_live, streams_live,
+backend_dials_in_flight, pending_bytes, pending_items, sessions_created_total,
+sessions_closed_total, streams_opened_total, streams_rejected_total,
+backend_dial_failures_total, bytes_up_total, bytes_down_total, limit_hits_total.
+
+Ключевые для алертов: `backend_dial_failures_total` (рост = бэкенд недоступен),
+`limit_hits_total` (DDOS/перегруз), `sessions_live` (активность).
+
+### C. Подключение к Prometheus (стек /opt/monitoring, bigbox)
+
+- vps03 НЕ в WG (10.8.0.0/24 = vps01/bigbox/vps02), поэтому прямого доступа
+  к 8081 с bigbox нет. Prometheus в стеке — `network_mode: host` (видит внешние IP).
+- План: nft-правило на vps03 (разрешить TCP 8081 с publIP bigbox 178.176.197.2),
+  job 'tproxy' в prometheus.yml, targets ['77.67.89.154:8081'].
+- ВАЖНО: admin-эндпоинты слушают только loopback. Открывать наружу ТОЛЬКО
+  по источнику (ip saddr bigbox), не публиковать всем.
+- readyz ходит ко ВСЕМ профилям: если добавить профиль с мёртвым бэкендом —
+  readyz станет 503 (фича, учтена при алертах).
+
+### D. Грабли установки (уже в INSTALL_NOTES.md проекта tproxy-web)
+
+- MTProxy-бинарь падал 203/EXEC: `chmod 755 /opt/MTProxy/objs/bin` + chown
+  root:mtproxy + chmod 750. (см. /opt/hermes/tproxy-web/INSTALL_NOTES.md)
+- `go test ./...` флакал на TestLoadAcceptsSystemdCredentialReadPermissions
+  при запуске от root — обходится запуском тестов от не-root или пропуском.
 
 ```
 # все три ноды отдают метрики:

PLAN.md

@@ -53,6 +53,75 @@
 - [ ] Дашборд: статус нод, занятость диска, блоки, репликация
 - [ ] Уведомления алертов (например, в Telegram/почту)
 
+## Этап 6. Метрики tproxy-server (vps03) — TODO 🔄
+
+WEB Proxy для Telegram Desktop развёрнут на vps03 (77.67.89.154, Debian 13):
+Caddy → tproxy-server:8080 → MTProxy:2398. Admin-эндпоинты:
+
+- `http://127.0.0.1:8081/readyz`  → 200 `ready` / 503 `backend unavailable`
+  (TCP-проба ко всем backend-профилям, у нас 127.0.0.1:2398)
+- `http://127.0.0.1:8081/healthz` → всегда `ok` (процесс жив)
+- `http://127.0.0.1:8081/metrics` → Prometheus-формат (текст, version 0.0.4)
+
+Метрики tproxy (счётчики из `internal/server/server.go` serveMetrics):
+
+| Метрика | Смысл |
+|---|---|
+| tproxy_sessions_live / streams_live | активные сессии/потоки |
+| tproxy_backend_dials_in_flight | исходящие к MTProxy в полёте |
+| tproxy_pending_bytes / _items | очередь ожидающих данных |
+| tproxy_sessions_created_total / closed_total | создано/закрыто (суммарно) |
+| tproxy_streams_opened_total / rejected_total | открыто/отклонено потоков |
+| tproxy_backend_dial_failures_total | **ошибки коннекта к MTProxy** (рост = проблема) |
+| tproxy_bytes_up_total / down_total | трафик вверх/вниз (всего) |
+| tproxy_limit_hits_total | срабатывания лимитов |
+
+Задача:
+
+- [ ] Обеспечить доступ Prometheus (bigbox) к `:8081` на vps03.
+      vps03 НЕ в WG-сети (10.8.0.0/24 = vps01/bigbox/vps02).
+      Варианты:
+      a) открыть 8081 на vps03 для IP bigbox в nft (правило в
+         `/etc/tproxy-server/firewall.nft` или отдельный файл) — самый простой;
+      b) добавить vps03 в WG (если хочется закрытый контур);
+      c) node-exporter + textfile-коллектор — не наш случай (метрики уже в HTTP).
+      Рекомендация: (a).
+      **Конкретные шаги (рекомендуемый вариант a):**
+      - [ ] На vps03 (77.67.89.154) добавить nft-правило, разрешающее TCP 8081
+            с публичного IP bigbox **178.176.197.2** (проверить актуальный IP
+            bigbox перед выполнением: `curl -s https://api.ipify.org`):
+            ```
+            nft add rule inet filter input ip saddr 178.176.197.2 tcp dport 8081 accept
+            ```
+            (или внести в `/etc/tproxy-server/firewall.nft`, если он в авто-загрузке)
+      - [ ] Проверить с bigbox:
+            `curl -s http://77.67.89.154:8081/metrics | head`
+            → должен вернуть метрики tproxy (не timeout/refused).
+      - [ ] Добавить job 'tproxy' в `/opt/monitoring/prometheus.yml`:
+            ```yaml
+            - job_name: 'tproxy'
+              static_configs:
+                - targets: ['77.67.89.154:8081']
+                  labels:
+                    host: vps03
+                    service: tproxy
+            ```
+      - [ ] `docker compose restart prometheus` в /opt/monitoring,
+            проверить `up{job="tproxy"}` на 127.0.0.1:9090 = 1.
+- [ ] (Опционально) blackbox-job для внешнего HTTPS-чека vps03.nixg.ru:
+      `probe_success` — контролирует Caddy+сайт снаружи.
+- [ ] Дашборд в Grafana: сессии, трафик (bytes_up/down rate), ошибки бэкенда.
+- [ ] Алерт: `tproxy_backend_dial_failures_total` растёт, или `/readyz` 503
+      (можно ч/з blackbox по HTTP :8081, если открыт).
+
+Заметки:
+- `/metrics` и admin-эндпоинты слушают ТОЛЬКО loopback (127.0.0.1:8081). При
+  открытии наружу — резать по источнику (IP bigbox) в nft, не публиковать всем.
+- readyz сделает TCP-пробу К КАЖДОМУ профилю — если добавить второй профиль
+  с мёртвым бэкендом, readyz станет 503 (это фича).
+- Секреты WEB Proxy (profiles.json) к мониторингу отношения не имеют — в
+  метрики не попадают.
+
 ## Риски / заметки
 
 - Перезапуск нод кластера безопасен, но делать по очереди.

README.md

@@ -115,6 +115,20 @@ curl -X POST -H "Authorization: token GITEA_TOK" \
 | GarageResyncErrors | `garage_block_resync_error_count > 0` (10м) | warning |
 | GarageNodeUnstable | RPC health down (5м)           | warning |
 
+## tproxy-server (vps03) — метрики WEB Proxy (этап 6, в работе)
+
+tproxy-server (Telegram Desktop WEB Proxy) развёрнут на **vps03** (77.67.89.154),
+admin-эндпоинты на loopback :8081: `/healthz`, `/readyz`, `/metrics`
+(Prometheus-формат, 13 счётчиков `tproxy_*`). vps03 НЕ в WG-сети, поэтому
+для scrape с bigbox нужно:
+
+1. nft-правило на vps03: разрешить TCP 8081 с publIP bigbox **178.176.197.2**
+   (`nft add rule inet filter input ip saddr 178.176.197.2 tcp dport 8081 accept`)
+2. job `tproxy` в prometheus.yml: `targets: ['77.67.89.154:8081']`
+3. `docker compose restart prometheus`, проверить `up{job="tproxy"}`
+
+Подробности — в PLAN.md (этап 6) и EXPERIENCE.md.
+
 ## Катастрофоустойчивость
 
 Проект хранится в **двух** git-репозиториях — на случай поломки bigbox: