feat: add declarative sing-box egress control plane

2026-08-27 00:58:52 +05:00
commit b8d19b2c3e
54 changed files with 3337 additions and 0 deletions
@@ -0,0 +1,61 @@
+# Диагностика
+
+Начинать с:
+
+```bash
+vpn-egressctl doctor
+vpn-egressctl status --json
+```
+
+## Unsupported sing-box version
+
+Установлена не `1.13.19`. Конфигурация не изменялась. Проверить:
+
+```bash
+sing-box version
+apt-cache policy sing-box
+```
+
+Не использовать ручной обход version gate.
+
+## sing-box rejected generated configuration
+
+Candidate удалён, production не менялся. Проверить package version, policy и
+логи oneshot. Секреты в отчёт не прикладывать.
+
+## Apply failed, previous configuration restored
+
+Автоматический rollback успешен. Проверить:
+
+```bash
+systemctl status sing-box --no-pager
+journalctl -u sing-box -u vpn-egress-sync.service -n 200 --no-pager
+vpn-egressctl doctor
+```
+
+## Critical rollback failed
+
+Не выполнять новый sync. Использовать `/var/lib/vpn-egress/last-good.json` или
+timestamped backup из консоли контейнера, затем `sing-box check` и restart.
+
+## Endpoint exclusion
+
+Если doctor сообщает, что A-запись endpoint находится в TUN exclusions, удалить
+публичный CIDR из policy и выполнить `check`, `diff`, `sync`. Не заменять его на
+новый IP.
+
+## Healthcheck request failed
+
+Проверить DNS, handshake Hysteria2, доступность health URL и nftables. Временно
+ставить `url: null` на production нельзя без отдельного решения: это скрывает
+неработающий data plane.
+
+## Watcher failed
+
+Некорректный файл URI не меняет рабочий config. Исправить его безопасным
+`vpn-egressctl import --stdin`, затем:
+
+```bash
+systemctl reset-failed vpn-egress-sync.service
+systemctl status vpn-egress-sync.path --no-pager
+```