prod/singbox_glue
5
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

release: prepare 0.2.0 for sing-box 1.14

Browse Source
This commit is contained in:
Crimson
2026-09-08 19:26:00 +05:00
parent 81ea89f7fa
commit 76dce5b47a
42 changed files with 1634 additions and 549 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/migration.md
+79 -116
View File
@@ -1,71 +1,72 @@
# Установка и миграция
# Чистая установка версии 0.2.0
Инструкция рассчитана на Debian 13 внутри `vpn-egress-gw`.
## Поддерживаемая модель
## 1. Резервная копия
In-place upgrade 0.1.0 → 0.2.0, автоматическая миграция policy/state и запуск
старого config под новым ядром не поддерживаются. Новый package `preinst`
отклоняет upgrade. Установка выполняется через удаление старого пакета,
архивирование его данных и настройку 0.2.0 с нуля.
До установки сохранить:
Описанные действия выполнять из console/maintenance-доступа. До успешного E2E
anti-leak guard должен оставаться в nftables.
## 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
systemctl disable --now vpn-egress-sync.path || true
systemctl stop sing-box.service
systemctl mask --runtime sing-box.service
nft list table inet vpn_egress_guard
```
Новый unit имеет `Before=sing-box.service`, а package-managed drop-in для
`sing-box.service` добавляет `Requires=` и `After=` от guard. Это закрывает boot
window и блокирует запуск sing-box, если совместно запущенный guard завершился с
ошибкой. Зависимость не является watchdog для ручного удаления nftables-таблицы;
текущее runtime-состояние проверяет `vpn-egressctl doctor`.
Если guard отсутствует, сначала восстановить защиту. Не продолжать переход с
работающим прямым forwarding `eth1 -> eth0`.
## 5. Dry run и первый import
## 2. Удалить старый package и архивировать данные
Для первого `check` URI ещё должен существовать. Создать файл без попадания
secret в argv:
```bash
apt-get remove vpn-egressctl
install -d -m 0700 /root/vpn-egress-0.1-archive
test ! -e /etc/vpn-egress || \
mv /etc/vpn-egress /root/vpn-egress-0.1-archive/etc-vpn-egress
test ! -e /var/lib/vpn-egress || \
mv /var/lib/vpn-egress /root/vpn-egress-0.1-archive/var-lib-vpn-egress
test ! -e /etc/sing-box/config.json || \
mv /etc/sing-box/config.json /root/vpn-egress-0.1-archive/config.json
```
Архив содержит secrets и должен оставаться `root:root 0700/0600`. Не копировать
старые `policy.json`, `state.json` или `last-good.json` обратно в 0.2.0.
## 3. Установить exact sing-box 1.14.0
```bash
apt-get update
apt-get install sing-box=1.14.0
sing-box version
```
Вывод должен содержать exact `1.14.0`, Linux environment, `with_quic` и
`with_gvisor`. Runtime mask не снимать: старый config уже архивирован, но новая
policy ещё не настроена.
## 4. Установить vpn-egressctl 0.2.0
```bash
dpkg -i vpn-egressctl_0.2.0_all.deb
systemctl daemon-reload
```
Если postinst сообщает о legacy state или unmanaged config, не обходить
проверку: архивировать указанный объект и повторить `dpkg --configure
vpn-egressctl`.
## 5. Настроить новую policy и Gecko URI
Редактировать новый `/etc/vpn-egress/policy.json` вручную. Из старой policy
можно перенести осознанно проверенные локальные значения, но нельзя заменять ею
новый файл целиком.
```bash
install -m 0600 -o root -g root /dev/null /etc/vpn-egress/hysteria2.uri
@@ -75,75 +76,37 @@ unset URI
vpn-egressctl check
vpn-egressctl diff
vpn-egressctl sync
```
Более простой вариант для интерактивного применения:
Проверить, что URI содержит `obfs=gecko`. `check` не запускает service.
## 6. Активировать защиту и config
```bash
vpn-egressctl import --stdin
systemctl enable --now vpn-egress-guard.service
nft list table inet vpn_egress_guard
systemctl unmask --runtime sing-box.service
vpn-egressctl sync
vpn-egressctl doctor
```
Команда сама запросит URI без echo, выполнит check/apply/healthcheck и при
неуспехе восстановит старые URI и config.
После первого успешного sync `last-good` ещё отсутствует — это ожидаемо.
## 6. Включение watcher
## 7. Acceptance и watcher
С workload за `eth1` проверить DNS, TCP, UDP, внешний VPN IP и отсутствие
прямого WAN при остановленном sing-box. Серверный Gecko E2E выполняется отдельно
владельцем HY2XS.
```bash
systemctl enable --now vpn-egress-sync.path
vpn-egressctl status --json
vpn-egressctl doctor
```
## 7. Вывод старого renderer из эксплуатации
## Возврат к 0.1.0
После успешного 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
systemctl show sing-box.service -p Requires -p After
```
В `config.json` и nftables не должно быть ни старого `185.156.108.141`, ни
текущего `85.208.119.160`.
С настоящего workload в `10.30.0.0/24` обязательно проверить:
1. DNS через шлюз;
2. TCP и UDP через VPN;
3. HTTPS-запрос к контролируемому endpoint или Cloudflare trace;
4. соответствие наблюдаемого public IP ожидаемому VPN egress;
5. повтор тех же проверок после restart sing-box.
Anti-leak проверяется только из консоли canary/staging, чтобы не потерять
удалённый доступ к production:
```bash
# На шлюзе:
systemctl stop sing-box.service
# На workload за eth1: запрос наружу должен завершиться ошибкой, а не пойти напрямую.
curl --fail --connect-timeout 5 https://www.cloudflare.com/cdn-cgi/trace
# На шлюзе:
systemctl start sing-box.service
vpn-egressctl doctor
```
0.2.0 не выполняет downgrade. Возврат — отдельная ручная чистая установка:
удалить 0.2.0, архивировать её состояние, установить exact старые packages и
только после этого восстановить согласованный snapshot 0.1.0. Нельзя запускать
config одной версии под бинарником другой.