diff --git a/README.md b/README.md index 4b97ce3..c0a035c 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,7 @@ shell history. - [Безопасность](docs/security.md) - [Контракт sing-box 1.14.0](docs/sing-box-1.14.md) - [Тестирование](docs/testing.md) +- [Финальная приёмка 0.2.0](docs/acceptance-0.2.0.md) - [Диагностика](docs/troubleshooting.md) ## Локальная проверка diff --git a/docs/acceptance-0.2.0.md b/docs/acceptance-0.2.0.md new file mode 100644 index 0000000..c2825ee --- /dev/null +++ b/docs/acceptance-0.2.0.md @@ -0,0 +1,123 @@ +# Финальная приёмка vpn-egressctl 0.2.0 + +## Паспорт прогона + +- дата: 15 сентября 2026 года; +- статус: `PASS / PRODUCTION E2E VALIDATED`; +- gateway: `vpn-egress-gw`; +- `vpn-egressctl`: `0.2.0`; +- `sing-box`: `1.14.0`; +- сервер Hysteria2: `2.12.2`; +- obfs: Gecko; +- endpoint: `se.api.withen.pro:2053`; +- TUN: `tun-sb0`, `172.19.0.1/30`. + +Это отчёт о клиентском control plane и полном пути трафика через gateway. +Отдельная приёмка ядра HY2XS в него не включена. До прогона endpoint был +независимо проверен официальным клиентом Hysteria 2.12.2: QUIC/Hysteria +handshake, SOCKS5, HTTPS и двусторонний UDP-трафик прошли успешно. + +## Clean first apply + +После удаления старого failed state установлен новый production URI. + +```text +vpn-egressctl check +OK: se.api.withen.pro:2053, sing-box 1.14.0 + +vpn-egressctl sync +Configuration applied. +``` + +После применения: + +- `status=ok`; +- `service_active=true`; +- `config_drift=false`; +- `source_drift=false`; +- SHA-256 из state совпал с фактическим SHA-256 установленного config. + +Зафиксированный SHA-256 итогового config: + +```text +0d888e7793bd979d212b613542070ce9349a625ddace2a0727776072b66c96ae +``` + +`last_good_available=false` и `last_good_valid=false` после этого прогона — +ожидаемое состояние. У первого успешного clean apply нет предыдущего managed +config, а последующий no-op sync не создаёт rollback predecessor. + +## Runtime и gateway E2E + +- `sing-box.service` и `vpn-egress-guard.service` активны; +- `tun-sb0` поднят с адресом `172.19.0.1/30`; +- DNS через sing-box работает; +- Hysteria2 outbound работает; +- DNS resolution и реальный HTTPS-запрос с `vpn-egress-gw` прошли успешно; +- внешний адрес gateway через туннель: `212.113.101.200`. + +## Idempotency + +Повторный `vpn-egressctl sync` сообщил: + +```text +Desired state is already installed. +``` + +При этом `changed=false`, оба drift-флага остались `false`, SHA-256 config не +изменился, сервисы сохранили active state. Повторный E2E также прошёл с внешним +адресом `212.113.101.200`. + +## Клиент за br_vpn + +Для независимой проверки forwarding path создан временный клиент: + +- адрес: `10.30.0.20/24`; +- default gateway: `10.30.0.2`; +- доступность gateway: `3/3`, потерь нет; +- DNS-запрос обработан sing-box; +- TCP/HTTPS-трафик принят через TUN; +- выбран outbound `hysteria2[hy2-out]`; +- внешний адрес клиента: `212.113.101.200`. + +Проверенный путь: + +```text +10.30.0.20 + -> br_vpn + -> vpn-egress-gw / eth1 + -> tun-sb0 + -> sing-box 1.14.0 + -> Hysteria2 / Gecko + -> se.api.withen.pro:2053 + -> Internet +``` + +## Fail-closed / anti-leak + +До остановки sing-box клиент выходил с адреса `212.113.101.200`. После +успешного `systemctl stop`: + +- sing-box перешёл в inactive state; +- `vpn-egress-guard` остался active; +- прямой Internet access клиента отсутствовал; +- `curl` завершился с `rc=7`; +- выхода через обычный `eth0`/WAN не возникло. + +После запуска sing-box доступ восстановился, а внешний адрес снова стал +`212.113.101.200`. + +Статус anti-leak проверки: `PASS`. + +## Cleanup и итог + +После проверки удалены известные временные объекты: test namespace, veth, +официальный диагностический Hysteria binary, test configs, logs и pcap. +Production URI, config и state сохранены. Внутри `vpn-egress-gw` контрольный +`find` по использованным диагностическим шаблонам не вернул результатов. + +Подтверждены clean installation и first apply, генерация config, runtime +health, DNS, gateway E2E, idempotent no-op, E2E клиента за `br_vpn`, recovery +после запуска сервиса и fail-closed защита от прямого WAN. + +Итоговый статус: `PASS / PRODUCTION E2E VALIDATED`. diff --git a/docs/migration.md b/docs/migration.md index ada4adf..2526394 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -109,6 +109,9 @@ vpn-egressctl status --json vpn-egressctl doctor ``` +Фактический production-прогон этой процедуры и E2E клиента за `eth1` +зафиксирован в [отчёте о финальной приёмке 0.2.0](acceptance-0.2.0.md). + ## Возврат к 0.1.0 0.2.0 не выполняет downgrade. Возврат — отдельная ручная чистая установка: diff --git a/docs/testing.md b/docs/testing.md index a64c1f1..fee8a52 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -69,3 +69,12 @@ Server-side Gecko E2E выполняется с production-compatible HY2XS. Sal Platform hijack не обслуживает DNS, направленный на локальный LAN IP gateway. Такой сценарий допустим только после добавления отдельного DNS listener и не входит в acceptance версии 0.2.0. + +## Зафиксированный production acceptance + +15 сентября 2026 года версия 0.2.0 прошла финальный прогон с exact sing-box +1.14.0 и production-compatible HY2XS/Hysteria 2.12.2 endpoint в режиме Gecko. +Подтверждены gateway и forwarded-client E2E, DNS/HTTPS, idempotent no-op sync, +recovery после запуска сервиса и отсутствие прямого WAN при остановленном +sing-box. Полный состав и фактические результаты: [финальная приёмка +0.2.0](acceptance-0.2.0.md). diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 3e08bed..7769ec0 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -57,6 +57,20 @@ Backup и metadata рассогласованы или повреждены. А Проверить DNS, Gecko password, auth, SNI, certificate, UDP path и nftables. Успешный локальный healthcheck не заменяет forwarding E2E с `eth1`. +## Ранее наблюдавшиеся «UFO»-отказы + +Прежние необъяснённые отказы, условно обозначавшиеся как «UFO», не оказались +дефектом `vpn-egressctl 0.2.0`, renderer или sing-box 1.14.0. На том же gateway +и с тем же клиентским стеком endpoint Aéza сначала прошёл независимый E2E +официальным клиентом Hysteria 2.12.2, а затем полный production acceptance +`vpn-egressctl`. + +Это не отменяет диагностику каждого нового сбоя, но позволяет не считать старый +эпизод воспроизводимым дефектом control plane. При похожих симптомах сначала +сопоставлять endpoint/server state, credentials, certificate, UDP path и +nftables с [зафиксированным успешным прогоном](acceptance-0.2.0.md), не ослабляя +version, provenance и anti-leak gates. + ## DNS hijack не обслуживает LAN IP шлюза `dns_mode=hijack` перехватывает TCP/UDP 53 только к non-local destination. Если