OpenSpec: исследование + tavily-proxy-setup, local-extractor (spec-driven для инфраструктуры)

2026-09-29 09:15:01 +00:00 · 2026-09-06 12:12:33 +00:00
commit d1a19ba6cd
26 changed files with 1669 additions and 0 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-06
@@ -0,0 +1,38 @@
+# Design: add-vpn-tunnel-proxy
+
+## Approach
+
+Использовать существующий systemd-юнит `telegram-tunnel.service` (SSH -D :1080 → VPS01). Добавить:
+- `Restart=always`, `RestartSec=5` в юнит
+- `WantedBy=multi-user.target` + `systemctl enable`
+- Healthcheck: cron-скрипт или systemd-таймер, проверяющий `curl --socks5-hostname 127.0.0.1:1080 https://api.tavily.com` (HTTP 200 = жив). Молчит, если всё ок; шумит только при падении (по предпочтению пользователя — тихие watchdogs).
+
+## Files
+
+- `/etc/systemd/system/telegram-tunnel.service` — модифицировать (Restart, enable)
+- `/opt/hermes/.hermes/scripts/tunnel_healthcheck.sh` — новый скрипт-вотчдог
+- `/opt/hermes/README.md` — обновить (порт 1080, юнит, healthcheck)
+
+## Commands
+
+```bash
+# Применение
+sudo systemctl daemon-reload
+sudo systemctl enable --now telegram-tunnel.service
+
+# Проверка
+systemctl is-active telegram-tunnel.service
+curl -s -o /dev/null -w "%{http_code}" --socks5-hostname 127.0.0.1:1080 https://api.tavily.com
+```
+
+## Rollback
+
+```bash
+sudo systemctl disable telegram-tunnel.service
+# восстановить исходный юнит из бэкапа
+```
+
+## Risks
+
+- SSH-ключ должен быть доступен сервису (owner root) — проверить права
+- VPS01 недоступен → туннель падает → healthcheck молчит/шумит по порогу
@@ -0,0 +1,24 @@
+## Why
+
+Нужен постоянный SOCKS5-туннель до VPS01 для обхода региональных блокировок (Tavily API, Telegram). Сейчас туннель поднимается вручную (SSH -D :1080), что ненадёжно: после ребута теряется, нет мониторинга, нет автозапуска.
+
+## What Changes
+
+- Создать systemd-юнит `telegram-tunnel.service` (уже существует) → **BREAKING**: перевести на автозапуск + watchdog
+- Добавить автозапуск при старте (systemctl enable)
+- Добавить проверку живости туннеля (systemd watchdog + healthcheck curl через туннель)
+- Задокументировать порт 1080 и ключ SSH в README
+
+## Capabilities
+
+### New Capabilities
+- `tunnel-proxy`: Постоянный SOCKS5-туннель до VPS01 с автозапуском и мониторингом
+
+### Modified Capabilities
+- (нет)
+
+## Impact
+
+- systemd: новый юнит + enable
+- SSH: ключ /mnt/yandex-disk/.ssh_box/timewebVPS
+- README.md в /opt/hermes (порты)
@@ -0,0 +1,30 @@
+# Delta for tunnel-proxy
+
+## ADDED Requirements
+
+### Requirement: Persistent SOCKS5 Tunnel
+The system MUST maintain a persistent SOCKS5 proxy tunnel from the host to VPS01, listening on 127.0.0.1:1080.
+
+#### Scenario: Tunnel starts on boot
+- GIVEN the host boots
+- WHEN systemd starts telegram-tunnel.service
+- THEN the tunnel listens on 127.0.0.1:1080
+- AND the SSH connection is established with key /mnt/yandex-disk/.ssh_box/timewebVPS
+
+#### Scenario: Tunnel dies
+- GIVEN the tunnel process exits unexpectedly
+- WHEN systemd detects failure
+- THEN the service restarts automatically (Restart=always)
+
+### Requirement: Tunnel Health Monitoring
+The system MUST verify tunnel liveness at least every 60 seconds.
+
+#### Scenario: Health check passes
+- GIVEN the tunnel is running
+- WHEN checking connectivity through 127.0.0.1:1080
+- THEN curl through the proxy returns HTTP 200 for a known endpoint
+
+#### Scenario: Health check fails
+- GIVEN the tunnel is down
+- WHEN the watchdog fires
+- THEN a notification is raised (no routine "all ok" messages)
@@ -0,0 +1,14 @@
+# Tasks
+
+## 1. Модифицировать юнит telegram-tunnel.service
+- [x] 1.1 Добавить Restart=always, RestartSec=5 (бэкап юнита перед правкой)
+- [x] 1.2 Включить автозапуск: sudo systemctl enable telegram-tunnel.service
+- [x] 1.3 Перезагрузить и проверить: systemctl is-active telegram-tunnel.service
+
+## 2. Healthcheck
+- [x] 2.1 Создать /opt/hermes/.hermes/scripts/tunnel_healthcheck.sh (curl через :1080 → tavily; молчит при ок)
+- [x] 2.2 Добавить в cron (no_agent) или systemd-таймер на 60s
+- [x] 2.3 Проверить: скрипт возвращает тишину при живом туннеле, сообщение при мёртвом
+
+## 3. Документация
+- [x] 3.1 Обновить /opt/hermes/README.md: порт 1080, юнит, healthcheck, ключ SSH