82 lines
3.6 KiB
Markdown
82 lines
3.6 KiB
Markdown
# 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.
|
|
- URI, production config, state и backups имеют режим `0600`.
|
|
- Неизвестные URI/policy-параметры отклоняются, а не игнорируются.
|
|
- systemd следит за desired state без постоянно работающего Python-процесса.
|
|
- Отдельный nftables guard блокирует прямой forwarding `eth1 -> eth0`.
|
|
|
|
## Источники состояния
|
|
|
|
```text
|
|
/etc/vpn-egress/policy.json
|
|
/etc/vpn-egress/hysteria2.uri
|
|
│
|
|
▼
|
|
renderer 1.13.19
|
|
│
|
|
▼
|
|
/etc/sing-box/config.json
|
|
```
|
|
|
|
`/etc/sing-box/config.json` является генерируемым артефактом. Редактировать его
|
|
вручную после миграции нельзя.
|
|
|
|
## Основные команды
|
|
|
|
```bash
|
|
# 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://...'` запрещён специально.
|
|
|
|
## Документация
|
|
|
|
- [Архитектура](docs/architecture.md)
|
|
- [Конфигурация](docs/configuration.md)
|
|
- [Установка и миграция](docs/migration.md)
|
|
- [Эксплуатация](docs/operations.md)
|
|
- [Безопасность](docs/security.md)
|
|
- [Диагностика](docs/troubleshooting.md)
|
|
- [Тестирование](docs/testing.md)
|
|
- [Почему не поддерживается 1.14](docs/sing-box-1.14.md)
|
|
|
|
## Локальная проверка
|
|
|
|
Проект не имеет runtime-зависимостей вне Python stdlib.
|
|
|
|
```powershell
|
|
E:\python-31312\python.exe -m compileall -q src tests
|
|
```
|
|
|
|
Изолированная Windows-сборка Python в указанном каталоге не добавляет cwd в
|
|
`sys.path`, поэтому полный тестовый запуск выполняется так:
|
|
|
|
```powershell
|
|
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`.
|