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,122 @@
+# Установка и миграция
+
+Инструкция рассчитана на Debian 13 внутри `vpn-egress-gw`.
+
+## 1. Резервная копия
+
+До установки сохранить:
+
+```bash
+install -d -m 0700 /root/vpn-egress-migration
+cp -a /etc/sing-box/config.json /root/vpn-egress-migration/config.json.before
+cp -a /root/render-singbox-hy2.sh /root/vpn-egress-migration/
+cp -a /usr/local/sbin/vpn-egress-guard.sh /root/vpn-egress-migration/
+nft list ruleset > /root/vpn-egress-migration/nft.before.rules
+ip -4 rule show > /root/vpn-egress-migration/ip-rule.before.txt
+ip -4 route show table all > /root/vpn-egress-migration/ip-route.before.txt
+```
+
+## 2. Обновление sing-box
+
+Пакет имеет строгую зависимость `sing-box (= 1.13.19)`.
+
+```bash
+apt-get update
+apt-get install sing-box=1.13.19
+sing-box version
+```
+
+Если репозиторий SagerNet ещё не публикует 1.13.19, миграцию не продолжать и не
+обходить dependency/version gate.
+
+## 3. Установка пакета
+
+```bash
+dpkg -i vpn-egressctl_0.1.0_all.deb
+install -m 0600 -o root -g root \
+  /usr/share/vpn-egressctl/policy.json \
+  /etc/vpn-egress/policy.json
+systemctl daemon-reload
+```
+
+Проверить локальные значения policy до первого применения.
+
+## 4. Guard до VPN
+
+Старый unit находится в `/etc/systemd/system` и перекрывает package unit из
+`/usr/lib`. Сначала обратимо убрать старое определение:
+
+```bash
+systemctl stop vpn-egress-guard.service
+mv /etc/systemd/system/vpn-egress-guard.service \
+  /root/vpn-egress-migration/vpn-egress-guard.service.disabled
+systemctl daemon-reload
+systemctl enable --now vpn-egress-guard.service
+systemctl status vpn-egress-guard.service --no-pager
+nft list table inet vpn_egress_guard
+```
+
+Новый unit имеет `Before=sing-box.service`; это закрывает boot window, который
+существовал у старого `After=sing-box.service`.
+
+## 5. Dry run и первый import
+
+Для первого `check` URI ещё должен существовать. Создать файл без попадания
+secret в argv:
+
+```bash
+install -m 0600 -o root -g root /dev/null /etc/vpn-egress/hysteria2.uri
+read -r -s URI
+printf '%s\n' "$URI" > /etc/vpn-egress/hysteria2.uri
+unset URI
+
+vpn-egressctl check
+vpn-egressctl diff
+vpn-egressctl sync
+```
+
+Более простой вариант для интерактивного применения:
+
+```bash
+vpn-egressctl import --stdin
+```
+
+Команда сама запросит URI без echo, выполнит check/apply/healthcheck и при
+неуспехе восстановит старые URI и config.
+
+## 6. Включение watcher
+
+```bash
+systemctl enable --now vpn-egress-sync.path
+vpn-egressctl doctor
+```
+
+## 7. Вывод старого renderer из эксплуатации
+
+После успешного canary и rollback-теста:
+
+```bash
+mv /root/render-singbox-hy2.sh \
+  /root/vpn-egress-migration/render-singbox-hy2.sh.disabled
+```
+
+Удалять старый файл в день миграции не нужно: перемещение остаётся обратимым.
+Старый `/usr/local/sbin/vpn-egress-guard.sh` можно архивировать после проверки,
+что package-managed unit использует `vpn-egressctl guard-apply`.
+
+## 8. Acceptance
+
+Обязательные проверки:
+
+```bash
+vpn-egressctl status
+vpn-egressctl doctor
+sing-box check -c /etc/sing-box/config.json
+ip -4 rule show
+ip -4 route show table 2022
+nft list table inet vpn_egress_guard
+nft list table inet sing-box
+```
+
+В `config.json` и nftables не должно быть ни старого `185.156.108.141`, ни
+текущего `85.208.119.160`.