TUIC server: минимальная схема сервера и обязательные параметры

Что такое TUIC и зачем нужна минимальная схема

TUIC — это протокол проксирования поверх QUIC, использующий UDP в качестве транспорта. Он спроектирован для уменьшения задержки и повышения стабильности в условиях нестабильной сети. Для запуска сервера не нужно разбираться во всех опциях — достаточно правильно указать несколько обязательных полей. Минимальная схема помогает быстро проверить работоспособность, а уже затем добавлять расширенные настройки: контроль перегрузки, несколько пользователей, ограничения по IP и тому подобное.

Обязательные параметры сервера TUIC

Чтобы TUIC server запустился, в конфигурации обязательно должны быть:

• listen — адрес и порт, на котором сервер принимает входящие QUIC-соединения. Обычно это 0.0.0.0:443, но можно использовать любой свободный UDP-порт.
• users — список пользователей. В минимальной версии это одна пара «uuid» и «password». UUID — уникальный идентификатор клиента, password — секретная строка, которую клиент передаёт при аутентификации. В некоторых версиях используется только uuid, без отдельного пароля.
• certificate — путь к файлу TLS-сертификата. Сертификат нужен для организации шифрования QUIC.
• private_key — путь к приватному ключу, соответствующему сертификату. Без него сервер не сможет установить TLS-соединение.

В зависимости от версии протокола (v0.8, v1, v2) названия полей могут отличаться. Например, в ранних версиях auth выполнялась только по UUID, а в новых появилось разделение на uuid и password. Поэтому важно проверять документацию той версии, которую вы используете.

Схема минимального конфигурационного файла

Рассмотрим пример из официального репозитория (значения заменены на плейсхолдеры):

{
  "server": {
    "listen": "0.0.0.0:443",
    "users": {
      "password1": "00000000-0000-0000-0000-000000000001"
    },
    "certificate": "/etc/tuic/cert.pem",
    "private_key": "/etc/tuic/key.pem"
  }
}

Внимание: в более новых ветках TUIC (например, ветка dev или версии v1.x) используется другой формат, в котором могут быть дополнительные поля, такие как alpn или congestion_control. Если вы используете docker-образ, проверьте его тег и документацию.

Настройка клиента: что указать обязательно

Клиент TUIC — это, как правило, приложение типа Sing-box, NekoRay или Clash.Meta. Все они имеют схожую модель настройки. Обязательные параметры:

• server — IP-адрес или домен вашего сервера.
• server_port — тот же UDP-порт, который вы указали в listen. Важно, чтобы порт был доступен по UDP, а не TCP.
• uuid и/или password — должны совпадать с данными, указанными в секции users на сервере.
• tls — параметры TLS-соединения: enabled: true, server_name (домен или IP, которое совпадает с сертификатом), alpn — часто требуется «h3».

Пример для Sing-box (используется только UUID):

{
  "type": "tuic",
  "tag": "tuic-out",
  "server": "example.com",
  "server_port": 443,
  "uuid": "00000000-0000-0000-0000-000000000001",
  "password": "password1",
  "congestion_control": "bbr",
  "tls": {
    "enabled": true,
    "alpn": ["h3"]
  }
}

Если вы используете только UUID без пароля, убедитесь, что секция password либо отсутствует, либо совпадает с серверной. Не смешивайте понятия — TUIC v2 допускает пару UUID/password, а в некоторых клиентах password необязателен.

QUIC, UDP, TLS: как это работает в TUIC

Протокол TUIC работает поверх QUIC, который, в свою очередь, использует UDP. QUIC обеспечивает мультиплексирование потоков, контроль перегрузки и встроенное шифрование. TLS в TUIC выполняет двойную функцию: аутентификация сервера и установление безопасного канала. Именно поэтому сертификат и ключ обязательны. Если на сервере используется самоподписанный сертификат, клиент должен быть настроен на доверие к нему (например, указать certificate в tls) либо явно включить insecure. В большинстве клиентов insecure по умолчанию выключен — это сделано для безопасности.

Так как QUIC работает через UDP, важно, чтобы файрвол, DPI и другие сетевые устройства пропускали не только TCP, но и UDP. Многие провайдеры блокируют UDP-трафик на высоких портах, поэтому при диагностике обращайте внимание на этот аспект.

Пошаговая проверка и диагностика

Предположим, сервер настроен, но клиент не подключается. Выполните следующие шаги:

1. Проверьте, что процесс TUIC запущен и нет ошибок в логах. Частые ошибки — «certificate not found» или «private key not found».
2. Проверьте доступность UDP-порта с клиента. Можно использовать утилиту nc -u -v ваш_сервер порт, но она не покажет ошибки TLS. Лучше использовать клиент TUIC и смотреть логи на стороне сервера.
3. Убедитесь, что клиент использует UDP, а не TCP. Некоторые клиенты могут пытаться подключиться по TCP, что заведомо не сработает.
4. Проверьте DNS-резолвинг: если указан домен, он должен указывать на IP вашего сервера. Также сертификат должен быть выпущен для этого домена или IP (если используется IP, подпись сертификата должна содержать IP-адрес).
5. Сверьте UUID и password. Между клиентом и сервером не должно быть лишних пробелов или регистрозависимых символов.

Если все шаги не дали результата, используйте tcpdump на сервере для фильтрации QUIC-пакетов:

tcpdump -i eth0 udp port 443

Так вы увидите, доходят ли пакеты от клиента до сервера.

Разделяем проблемы: клиент, сервер, сеть и DNS

Диагностику удобно разбить на четыре уровня:

• Сервер — корректность конфигурации, доступность файлов, отсутствие ошибок в логах.
• Сеть — открыт ли UDP-порт, не блокируется ли QUIC файрволом или пакетным фильтром. Иногда провайдеры блокируют QUIC на уровне DPI.
• DNS — для клиента важен резолвинг домена. Если домен резолвится в неправильный IP, соединение не установится. Проверьте записи A/AAAA.
• Клиент — настройки, версия клиента, корректность параметров TLS и ALPN. Иногда клиент использует неправильный ALPN, например, «http/1.1» вместо «h3».

Помимо этого, не забывайте о времени. Если вы только что выпустили TLS-сертификат, проверьте его валидность (срок действия, цепочка).

Частые ошибки и их избегание

1. Ошибка в пути к сертификату. Сервер не запускается, если не может прочитать файлы. Проверьте права доступа и абсолютные пути.
2. Путаница между UUID и password. В разных версиях TUIC эти поля могут называться по-разному. Один и тот же идентификатор должен быть и на сервере, и на клиенте.
3. Отсутствие ALPN h3. Многие клиенты по умолчанию используют ALPN «http/1.1». Для TUIC ожидается «h3». Если клиент не поддерживает настройку ALPN, соединение может завершаться с ошибкой handshake.
4. Блокировка UDP. Даже если TCP-порт открыт, UDP может быть заблокирован. Это типичная ситуация в офисных и корпоративных сетях. Для проверки используйте мобильный интернет или другую сеть.

Также стоит помнить, что TUIC не поддерживает резервные каналы — поэтому при недоступности по UDP, соединение не переключится на TCP автоматически.

Заключение

Минимальная схема TUIC server включает всего четыре обязательных параметра: адрес прослушивания, данные пользователя (UUID и пароль), TLS-сертификат и приватный ключ. Этого достаточно для запуска сервера и проверки соединения. При возникновении проблем последовательно проверяйте сервер, сеть, DNS и клиент. Всегда сверяйтесь с официальной документацией той версии TUIC, которую вы используете, так как формат конфигурации может меняться.