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

Начинать с:

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

## Unsupported sing-box version

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

## In-place upgrades are not supported

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

## State from another release / unmanaged configuration

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

## 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`.