# Диагностика

Начинать с:

```bash
vpn-egressctl doctor
vpn-egressctl status --json
```

## Unsupported sing-box version

Установлена не exact `1.14.0` либо отсутствуют `with_quic`/`with_gvisor`.
Конфигурация не изменялась. Не обходить version gate.

## Cross-release upgrades are not supported

Пакет 0.2.0 устанавливается поверх другого релиза. Старый package остаётся
установленным; выполнить clean-install runbook из `docs/migration.md`.
Повторная установка ровно 0.2.0 поддерживается, если state и config согласованы.

## State from another release / unmanaged configuration

Обнаружены сохранённые файлы 0.1.0 или конфиг вне управления 0.2.0. Остановить
sing-box, убедиться в наличии guard, переместить старые данные в защищённый архив
и повторить `dpkg --configure vpn-egressctl`. Не редактировать старый state так,
чтобы обойти проверку. Даже побайтово идентичный candidate не делает unmanaged
config принадлежащим этому релизу.

## sing-box rejected generated configuration

Candidate удалён, production не менялся. Проверить exact package version, URI и
policy. Не прикладывать URI/config к отчёту без удаления secrets.

## Apply failed, previous configuration restored

Same-release rollback успешен. Проверить service/journal и выполнить doctor.

## Automatic rollback also failed

Если это первое clean apply, предыдущего управляемого config нет — восстановить
нечего. sing-box должен оставаться остановленным, а guard активным. При наличии
last-good проверить его `.meta`; не запускать файл вручную при несовпадении
версии или SHA.

## Configuration metadata checksum does not match

Backup и metadata рассогласованы или повреждены. Автоматический rollback
правильно заблокирован. Использовать другой version-matched backup только через
консоль и после `sing-box check`.

## Endpoint exclusion

Удалить публичный endpoint CIDR из policy. Не заменять его новым A-адресом.

## Healthcheck request failed

Проверить DNS, Gecko password, auth, SNI, certificate, UDP path и nftables.
Успешный локальный healthcheck не заменяет forwarding E2E с `eth1`.

## Ранее наблюдавшийся transport failure на старом endpoint

Ранее наблюдавшиеся таймауты на старом server endpoint не оказались
воспроизводимым дефектом `vpn-egressctl 0.2.0`, renderer или sing-box 1.14.0.
Официальный клиент Hysteria 2.12.2 на том же gateway также не мог установить
соединение с проблемным endpoint. После перехода на независимый endpoint тот же
gateway и клиентский стек успешно прошли сначала direct Hysteria2 E2E, а затем
полный 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. Если
LAN-клиент обращается к адресу самого gateway, например `10.20.0.1:53`, нужен
отдельный DNS listener/service. Не добавлять `dns_address` вручную и не
возвращать route rule как workaround: это меняет проверенный контракт renderer.