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,70 @@
+# Конфигурация
+
+## Policy schema version 1
+
+Production-образец находится в `config/policy.json`. Неизвестные и отсутствующие
+ключи являются ошибкой.
+
+### `sing_box`
+
+- `binary`: абсолютный путь к бинарнику;
+- `config_path`: production JSON;
+- `service`: systemd service;
+- `required_version`: допускается только `1.13.19`.
+
+### `runtime`
+
+- `uri_path`: desired-state secret;
+- `state_dir`: state и backups;
+- `lock_path`: межпроцессная блокировка;
+- `backup_keep`: число timestamped backups, от 1 до 100.
+
+### `network`
+
+Здесь явно фиксируются интерфейсы, TUN CIDR, MTU, exclusions, таблица 2022,
+начальный rule index 9000, marks `0x2023`/`0x2024`/`0x2025`, NFQUEUE 100 и
+fallback rule 32768.
+
+Публичные адреса не должны добавляться в `route_exclude_address`. Локальные
+подсети `10.20.0.0/24`, `10.30.0.0/24` и loopback сохраняются.
+
+### `dns`
+
+Текущий контракт:
+
+- UDP bootstrap `1.1.1.1:53`, bind `eth0`;
+- DoH `1.1.1.1:443/dns-query`, SNI `cloudflare-dns.com`;
+- DoH detour `hy2-out`;
+- только `ipv4_only`.
+
+### `healthcheck`
+
+По умолчанию выполняется HTTPS-запрос к Cloudflare trace и ожидается HTTP 200 с
+маркером `ip=`. Этот запрос идёт после запуска sing-box и подтверждает не только
+состояние systemd, но и рабочий data plane.
+
+`url: null` оставляет только проверку `systemctl is-active`. Это допустимо для
+изолированного стенда, но слабее production-проверки.
+
+## Поддерживаемая часть Hysteria2 URI
+
+Поддерживаются:
+
+- `hysteria2://` и `hy2://`;
+- percent-encoded auth, включая `username:password`;
+- DNS, IPv4, bracketed IPv6 и IDNA;
+- port 443 по умолчанию;
+- одиночный port и официальный multi-port/ranges;
+- `sni`, `insecure=0|1`;
+- `obfs=salamander&obfs-password=...`;
+- fragment как необязательное display name.
+
+Отклоняются `gecko`, `pinSHA256`, `ech`, client modes, неизвестные и
+повторяющиеся параметры. Причина для `pinSHA256`: Hysteria URI и sing-box
+1.13.19 используют разные виды certificate hash. `ech` будет добавлен только
+после доказанного преобразования формата config list.
+
+## Bandwidth
+
+`up_mbps=50` и `down_mbps=200` являются локальной политикой и намеренно не
+принимаются из URI.