TUIC QR-код не читается: форматы ссылок и типовые ошибки

TUIC (Tunnel to Internet via QUIC) — это современный прокси-протокол, использующий QUIC и TLS для быстрых и стабильных подключений. Многие пользователи используют QR-коды для быстрого импорта конфигурации в мобильные клиенты, но часто сталкиваются с проблемой: «QR-код не читается». В этой статье мы разберём возможные причины, форматы ссылок и дадим пошаговую инструкцию по диагностике и исправлению.

Почему QR-код TUIC не читается?

QR-код — это просто графическое представление текстовой строки. Если сканер не срабатывает, первая и самая вероятная причина — повреждение или некорректность самой строки, закодированной в QR. Но есть и другие сценарии:

• Слишком длинная ссылка — QR-код становится слишком плотным, мелкие модули плохо считываются.
• Ошибки кодирования — специальные символы в пароле или UUID неправильно экранированы.
• Клиент не поддерживает формат ссылки или требует иной URI-схему.
• Проблемы с камерой или сканером — фокусировка, освещение, повреждённый QR.
• Несовместимость версий протокола — например, сервер использует TUIC v1, а клиент ожидает v2.

Чаще всего проблема кроется в том, что ссылка, переданная в QR, не соответствует стандарту TUIC URI. Ниже мы рассмотрим правильный формат.

Форматы ссылок TUIC: как должен выглядеть профиль

TUIC использует URI-схему tuic://. Базовая структура ссылки такая:

tuic://UUID:password@server_address:port?parameter1=value1&parameter2=value2#profile_name

• UUID — обязательный идентификатор пользователя (Universally Unique Identifier).
• password — необязательный, но часто используемый пароль (указывается в конфиге сервера).
• server_address — IP или доменное имя сервера.
• port — порт для QUIC-соединения.
• Параметры — передаются через ? и разделяются &. Основные: congestion_control, udp_relay_mode, allow_insecure, sni, alpn, disable_nat и другие.
• fragment (после #) — имя профиля, отображаемое в клиенте.

Пример корректной ссылки (используйте заглушки):

tuic://00000000-0000-0000-0000-000000000000:password@example.com:2048?congestion_control=bbr&udp_relay_mode=native&allow_insecure=0&sni=example.com&alpn=h3#MyProfile

В UTI-ссылке параметры могут отличаться в зависимости от реализации. Некоторые клиенты, например sing-box, поддерживают расширенный JSON-формат, но QR-код обычно содержит именно URI.

Типовые ошибки при генерации и сканировании

1. Неправильное экранирование специальных символов

Если пароль или другие поля содержат символы вроде @, :, /, ?, &, их нужно URL-кодировать. Например, пароль p@ss:word должен быть передан как p%40ss%3Aword. Иначе ссылка будет невалидной, и QR не отсканируется или импортируется с ошибкой.

2. Отсутствие схемы tuic://

Некоторые генераторы добавляют только host и параметры, опуская tuic://. Без схемы клиент не понимает, какой протокол использовать, и QR игнорируется.

3. Лишние пробелы и невидимые символы

При копировании строки в генератор QR могут попасть переводы строк, пробелы или знаки табуляции. Они не видны глазу, но ломают синтаксис.

4. Несовместимость клиента с TUIC

Не все клиенты поддерживают TUIC. Например, стандартное приложение V2RayN не всегда понимает схему tuic://, нужен sing-box, NekoBox, v2rayNG (с поддержкой TUIC) или официальный клиент TUIC.

5. Слишком длинный URL

Максимальная длина QR-версии ограничена. При большом количестве параметров (особенно если в JSON) QR становится слишком плотным. Попробуйте сократить имя профиля или убрать необязательные параметры.

6. Проблемы с UUID

Некоторые клиенты требуют UUID в формате стандартного UUID (8-4-4-4-12). Если вы используете короткий идентификатор или случайную строку, TUIC может не запуститься.

Диагностика: клиент, сервер, сеть и DNS

Даже если QR корректно сканируется и профиль импортируется, подключение может не работать. Разделим диагностику на четыре уровня.

Клиент

• Проверьте, что вы используете актуальную версию клиента, поддерживающую TUIC. Для мобильных: NekoBox, sing-box, v2rayNG (последние сборки). Для десктопа: sing-box GUI, официальный TUIC-клиент.
• После импорта QR проверьте, что все поля заполнены верно: UUID, сервер, порт, пароль.
• Убедитесь, что выбран правильный тип протокола — TUIC (а не VLESS или Trojan).

Сервер

• Проверьте, что TUIC-сервер запущен и слушает ожидаемый порт (по умолчанию 2048/443).
• Проверьте, что UUID и пароль в конфигурации сервера совпадают с теми, что указаны в ссылке.
• Если сервер за Reverse Proxy или firewall, убедитесь, что UDP-порт открыт и доступен из интернета.

Сеть

• TUIC работает поверх QUIC (UDP). Убедитесь, что ваш сетевой провайдер не блокирует UDP или конкретный порт. Некоторые публичные Wi-Fi блокируют весь UDP.
• Попробуйте переключиться на мобильную сеть (4G/5G) и наоборот.
• В корпоративных сетях могут блокировать QUIC целиком — попробуйте использовать другой протокол или изменить порт.

DNS

• Если сервер задан доменом, убедитесь, что DNS резолвит его корректно. Попробуйте в клиенте вручную указать IP-адрес (если домен нестабилен).
• Используйте DNS-over-HTTPS или DNS-over-TLS в клиенте, чтобы избежать подмены адресов.
• Проверьте, что поле sni в ссылке совпадает с доменом сертификата (обычно тот же домен). При несовпадении добавьте allow_insecure=1 для теста, но в продакшене не рекомендуется.

Как исправить и проверить QR-код

Если вы сомневаетесь в корректности ссылки, следуйте этим шагам:

1. Сгенерируйте ссылку вручную по шаблону выше, проверьте каждый символ.
2. Используйте онлайн-декодер для QR (например, ZXing Decoder), чтобы увидеть, что именно закодировано.
3. Скопируйте строку в текстовый редактор, удалите лишние пробелы, перекодируйте спецсимволы через URL-кодировщик.
4. Сократите длину ссылки: уберите параметры, которые клиент может подставить по умолчанию (например, congestion_control, если не используется).
5. Если QR-код считывается телефоном, но клиент не может импортировать, попробуйте тот же QR на другом клиенте (например, NekoBox вместо v2rayNG).
6. Для десктопа можно использовать формат JSON из sing-box — он надёжнее для сложных конфигураций.

Никогда не публикуйте свои UUID или пароли в общий доступ — это компрометирует сервер.

Профилактика проблем с QR-кодами

• Генерируйте QR-код с помощью надёжного генератора (например, QRCode Monkey), выставляя высокое разрешение и не добавляя логотипы.
• Храните исходную ссылку в текстовом виде, чтобы всегда можно было пересоздать QR.
• Следите за обновлениями TUIC и клиентов — формат ссылок может меняться.
• При массовом распространении конфигурации проверяйте каждый QR перед отправкой.

Заключение

Чаще всего проблема «TUIC QR-код не читается» связана с элементарной ошибкой в ссылке: неправильная схема, неэкранированные символы или слишком длинная строка. Используйте приведённый чек-лист, чтобы быстро локализовать неисправность. Помните, что TUIC работает через QUIC (UDP), поэтому сетевые ограничения могут мешать даже при правильном QR.

Если ничего не помогает, обратитесь к официальной документации TUIC и клиента, а также проверьте настройки сервера. Возможно, вы используете устаревшую версию протокола.