Ошибки и пошаговые проверки
Начните с безопасных команд без изменения системы, найдите стадию сбоя и только затем меняйте конфигурацию.
Пять команд до изменения конфига
Они не создают TUN и не меняют маршруты, кроме обычного чтения состояния системы. Сохраните точную первую ошибку — последующие сообщения часто являются её следствием.
$ qeli --version
$ sudo qeli check-config --config /etc/qeli/server.conf
$ sudo systemctl status qeli --no-pager
$ sudo journalctl -u qeli -n 200 --no-pager
$ sudo ss -lntup | grep qeli
Симптом → вероятная область
| Симптом | Проверьте сначала | Следующий шаг |
|---|---|---|
| Служба постоянно перезапускается | check-config, journal, TUN/bind collision | Запуск сервера ↓ |
| Клиент получает timeout | Порт, firewall, transport tcp/udp, публичный адрес | Handshake ↓ |
| Соединение есть, AUTH отклонён | user/pass, profiles, enabled, lockout | Handshake ↓ |
| Туннель поднят, интернета нет | gateway, NAT, ip_forward, firewall | Сеть ↓ |
| Мелкие сайты работают, загрузки зависают | MTU, MSS clamp, PMTU black-hole | Сеть ↓ |
| IP открывается, домен — нет | dns.enabled, dns.push_servers, режим DNS клиента | Сеть ↓ |
| Панель отвечает 403 | allowed_ips или allowed_origins | Панель ↓ |
| Панель за proxy отвечает 404/уходит в корень | base_path, trusted proxy, срез префикса | Панель ↓ |
| Реконнект после сна слишком долгий | Версия клиента, смена сети, battery policy | Клиенты ↓ |
Служба не запускает рабочий профиль
Проверка 0.8.1 выявляет синтаксис, неизвестные ключи, пользователей, пересечения IPv4/IPv6-пулов, одинаковые TUN, bind-коллизии, недостижимый REALITY target и несовместимые roaming/recordizer-политики.
sudo qeli check-config --config /etc/qeli/server.confпроверить до restartsudo journalctl -u qeli -b --no-pagerжурнал текущей загрузкиsudo ip tuntap showсуществующие TUN/TAP и конфликт имёнsudo ss -lntupкто уже занял портgetent passwd qeliсуществует ли сервисный пользовательПосле ручного редактирования восстановите владельца файлов: служба и панель должны читать и атомарно обновлять /etc/qeli. Для установки из .deb типовой владелец — qeli:qeli.
От listener до AUTH
Разделите сбой по стадии: нет TCP/UDP-соединения, не совпал wire-режим, не прошёл pinning/REALITY или сервер отклонил пользователя.
| Стадия | Что сверить |
|---|---|
| Connect | Публичный host:port, TCP/UDP, firewall и проброс порта |
| Wire mode | proto, mode, obfs_key, QUIC toggle |
| REALITY / H-1 | key, reality_sid, sni, target reachability |
| AUTH | user, pass, enabled, profiles, expire_at, quota |
| Lockout | sudo qeli list-blocked / sudo qeli unblock <ip> |
$ sudo qeli show-identity --config /etc/qeli/server.conf
# key клиента должен совпасть с профилем, к которому он подключается
Маршруты, NAT, MTU и DNS
Если handshake завершён и TUN поднят, ищите проблему в таблице маршрутов, forwarding, NAT/firewall, MTU или резолвере.
$ sudo qeli show-routes <user>
$ ip route show
$ sudo sysctl net.ipv4.ip_forward
$ sudo iptables-save | grep -iE 'qeli-nat|MASQUERADE|TCPMSS'
$ ping -c 3 10.9.0.1
$ getent hosts example.com
| Наблюдение | Что означает |
|---|---|
| Нет маршрута к TUN-пулу | Клиент не завершил настройку интерфейса или маршрут конфликтует |
| Пингуется tun.address, интернет — нет | Проверьте gateway=true, NAT, ip_forward и FORWARD |
| Малые ответы проходят, большие зависают | Типичный PMTU black-hole: MSS clamp или MTU слишком велики |
| IP работает, DNS-имя — нет | Сверьте dns.push_servers, dns.listen и локальный режим dns |
| Push виден в логе, маршрута нет | Проблема платформенного применения, прав или конфликта таблиц ОС |
Панель: 403, 404 и отсутствие доступа
| Симптом | Что исправить |
|---|---|
| VPN работает, :8080 не слушает | Задайте password_hash через set-web-password; панель fail-closed даже на loopback |
| 403 уже при открытии страницы | Ваш source IP не входит в allowed_ips |
| Страница открывается, сохранение даёт 403 | Добавьте браузерный host[:port] в allowed_origins |
| За proxy получаете 404 или редирект в / | Согласуйте base_path и X-Forwarded-Prefix; не срезайте префикс при заданном base_path |
| Apply & Restart не работает | sudo qeli install-polkit |
| Не создаётся QR существующего пользователя | Проверьте владельца users.conf и наличие /var/lib/qeli/panel-secret.key |
Особые случаи клиентов
| Платформа | Типовой случай | Действие |
|---|---|---|
| Android | protect() failed | Отключите конфликтующий always-on VPN/блокировку соединений без VPN |
| Android | Долгий возврат после сна | Используйте клиент 0.8.1, оставьте roaming=auto и проверьте ограничения батареи производителя |
| Windows / macOS | Push gateway/metric не применён | CIDR всё равно привязывается к TUN; смотрите поясняющую строку в логе |
| macOS | После удаления остался DNS туннеля | Запустите штатное отключение/очистку клиента и проверьте системный DNS |
| Windows/macOS в одной LAN с сервером | Реконнект-петля при full-tunnel | Задайте local равным LAN-IP клиента: несущий сокет пойдёт к серверу on-link без асимметричного /32 через шлюз |
Debug-лог и QELI_TRACE
Debug включайте только на время воспроизведения. QELI_TRACE записывает форму пакетов и тайминг без payload и адресов; файл всё равно проверьте перед публикацией.
$ sudo systemctl edit qeli
# добавьте:
[Service]
Environment=RUST_LOG=debug
Environment=QELI_TRACE=/tmp/qeli-server.csv
$ sudo systemctl daemon-reload
$ sudo systemctl restart qeli
Полный каталог сообщений и ошибок
В репозитории разобраны стадии соединения, точные строки журнала, UDP/REALITY-ошибки и дополнительные платформенные сценарии.