singbox_glue / vpn-egressctl

vpn-egressctl — локальный декларативный control plane для шлюза vpn-egress-gw. Он получает реквизиты подключения из защищённого Hysteria2 URI, объединяет их с локальной инфраструктурной политикой и полностью генерирует конфигурацию sing-box.

Проект намеренно поддерживает только sing-box 1.13.19. Версии 1.13.12, другие patch-релизы и вся ветка 1.14 отклоняются до изменения файлов.

Что решает проект

IP Hysteria2-сервера отсутствует в route_exclude_address и nftables policy.
Смена DNS A-записи не требует перегенерации конфигурации.
Смена credential выполняется одной безопасной командой через stdin.
Перед установкой candidate проверяется реальным sing-box check.
Запись атомарна; после неуспешного restart/healthcheck выполняется rollback.
Policy, URI, production config, state и backups имеют root:root 0600, защищённые каталоги — root:root 0700.
Неизвестные URI/policy-параметры отклоняются, а не игнорируются.
systemd следит за desired state без постоянно работающего Python-процесса.
Отдельный nftables guard блокирует прямой forwarding eth1 -> eth0.
sing-box.service требует успешного запуска guard через package-managed drop-in.

Источники состояния

/etc/vpn-egress/policy.json
/etc/vpn-egress/hysteria2.uri
             │
             ▼
      renderer 1.13.19
             │
             ▼
/etc/sing-box/config.json

/etc/sing-box/config.json является генерируемым артефактом. Редактировать его вручную после миграции нельзя.

Основные команды

# URI не попадает в argv и shell history.
sudo vpn-egressctl import --stdin

sudo vpn-egressctl check
sudo vpn-egressctl diff
sudo vpn-egressctl sync
sudo vpn-egressctl status
sudo vpn-egressctl doctor
sudo vpn-egressctl rollback

Позиционный vpn-egressctl import 'hysteria2://...' запрещён специально.

Документация

Локальная проверка

Проект не имеет runtime-зависимостей вне Python stdlib.

E:\python-31312\python.exe -m compileall -q src tests

Изолированная Windows-сборка Python в указанном каталоге не добавляет cwd в sys.path, поэтому полный тестовый запуск выполняется так:

E:\python-31312\python.exe -c "import sys,unittest; sys.path[:0]=[r'F:\projects\singbox_glue\src',r'F:\projects\singbox_glue']; s=unittest.defaultTestLoader.discover(r'F:\projects\singbox_glue\tests'); r=unittest.TextTestRunner(verbosity=2).run(s); raise SystemExit(not r.wasSuccessful())"

На Linux достаточно make check.

3.8 KiB Raw Blame History