Инженерия · Инфраструктура и надёжность

Как мы построили собственный туннель

Как мы построили tunnel.dtwin.uz на frp: небольшой шлюз, который управляет входом и поддоменами, сертификаты для каждого поддомена, выпущенные до показа ссылки, и клиент, который устанавливается даже там, где загрузки с GitHub зависают.

· 5 мин чтения

Чтобы показать то, что работает на вашем компьютере (ветку на ревью, приёмник вебхуков, демо для человека в другом городе), обычно берут хостинговый туннельный сервис. Такие сервисы работают, но каждый запрос идёт через чужую инфраструктуру, у бесплатных тарифов есть лимиты запросов и промежуточные страницы-предупреждения, а адрес принадлежит им. Мы хотели, чтобы туннель был нашим: наш домен, наш сервер и наши правила о том, что попадает в журнал.

Tunnel заработал на tunnel.dtwin.uz 2 ноября 2026 года. Эта статья — об инженерных решениях за ним, и большинство из них выросло из того, что не сработало с первого раза.

  1. ПодключениеКлиент сам подключается к серверу через обычный HTTPS WebSocket, поэтому проходит строгие офисные файрволы.
  2. АвторизацияПри каждом входе и каждом новом туннеле frp спрашивает наш шлюз, действителен ли токен и принадлежит ли поддомен этому пользователю.
  3. СертификатШлюз сразу запускает выпуск сертификата для нового поддомена и сообщает ссылку, только когда TLS готов.
  4. МаршрутизацияПосетители сначала попадают на шлюз, который применяет пароль, IP-правила и журнал, прежде чем передать трафик frp.
  5. РаспространениеКлиенты скачивают frp с нашего зеркала с закреплёнными SHA-256 и в запасе — с GitHub.
Рисунок 1

frp и шлюз, который принимает решения

Протокол туннелирования мы не писали. Основа — frp, на старте версии 0.71.1, зрелый обратный прокси с открытым кодом: серверный процесс принимает подключения клиентов, а каждый клиент открывает локальный порт под поддоменом. Чего во frp нет, так это понятия пользователя. Из коробки любой, у кого есть общий токен сервера, может занять любой поддомен.

Поэтому перед frp и рядом с ним стоит наш небольшой шлюз, написанный на Node без зависимостей. У него две задачи.

Он отвечает на вопросы frp. frp поддерживает серверные плагины по HTTP: на выбранных операциях он отправляет запрос на URL и ждёт разрешения или отказа. Мы регистрируем шлюз для Login и NewProxy. При каждом входе он проверяет личный токен пользователя, при каждом новом туннеле — что поддомен есть в списке разрешённых этому пользователю и не принадлежит кому-то другому. По умолчанию пользователь с именем alice может использовать alice и alice-*.

Он отвечает за сторону посетителя. Публичный трафик каждого туннеля сначала приходит на шлюз, а уже потом во frp. Именно здесь туннель можно поставить на паузу, закрыть паролем или ограничить списком IP-адресов, и здесь же пишется журнал запросов.

Личные токены выглядят как tn_<user>_<random>, показываются один раз и хранятся только как SHA-256-хеши. Общий токен frp никогда не раздаётся вручную: tunnel login обменивает на него личный токен через API шлюза. Отзыв личного токена сразу блокирует новые подключения, а уже подключённые туннели начинают получать от шлюза 403.

Клиент сам подключается через WebSocket на обычном HTTPS-порту. Значит, корпоративная сеть, где разрешён веб-сёрфинг, пропустит и туннель, а на стороне пользователя ничего открывать не нужно.

Сертификаты без wildcard

Очевидное решение — один wildcard-сертификат на *.tunnel.dtwin.uz. Для wildcard нужна проверка DNS-01, то есть автоматическое создание TXT-записей, а у нашего DNS-провайдера нет API. Мы выбрали отдельные сертификаты на каждый поддомен через on-demand TLS пограничного сервера. Перед выпуском он спрашивает frp, действительно ли имя зарегистрировано, поэтому никто не может заставить нас запрашивать сертификаты на случайные имена.

У выпуска по требованию есть цена: первый посетитель его ждёт. По нашим журналам пограничного сервера Let’s Encrypt тратил около 7,8 секунды от «получаю» до «получен» для нового имени. Первым исправлением был прогрев: через 1,5 секунды после того, как frp принял новый туннель, шлюз открывает TLS-соединение с пограничным сервером для этого имени, и выпуск начинается до того, как кто-то зайдёт. Этого оказалось мало. Ссылка печаталась сразу, и быстрый клик всё равно попадал на незавершённый сертификат: первое посещение тратило 5,71 секунды на TLS-рукопожатие.

Второе исправление перенесло ожидание туда, где ему место. В шлюзе появился эндпоинт готовности, который выполняет TLS-рукопожатие для имени, не отправляя ни одного запроса в приложение пользователя, а клиент опрашивает его, прежде чем напечатать ссылку:

Настройка Первое посещение
Только прогрев TLS-рукопожатие 5,71 с
Ссылка после готовности (клиент Windows) ссылка показана на 9,9 с; TLS 0,06 с, всего 0,13 с
Ссылка после готовности (клиент Linux) TLS 0,16 с
Рисунок 2

Пользователь один раз ждёт несколько секунд в терминале, где ожидание никого не удивляет. Посетитель не ждёт никогда. Для незарегистрированного имени эндпоинт через шесть секунд отвечает ready: false, потому что пограничный сервер отказывается выпускать для него сертификат.

Об одном побочном эффекте стоит знать: каждый сертификат попадает в публичные журналы Certificate Transparency, и сканеры, следящие за ними, появляются через считанные мгновения, проверяя пути вроде /wp-json и /xmlrpc.php. Новый туннель публичен с момента получения сертификата, независимо от того, поделились вы ссылкой или нет.

Сознательно меньше журналов

Шлюз ведёт журнал запросов, потому что «а вебхук вообще дошёл?» — самый частый вопрос при разработке через туннель. Он записывает только метаданные (время, метод, очищенный путь, статус, длительность, объёмы в байтах, тип контента, адрес клиента и user agent) и хранит их семь дней. Тела запросов и ответов, cookie и заголовки авторизации не сохраняются.

Та же сдержанность определяет и остальные возможности:

  • Пароль. tunnel lock ставит перед туннелем HTTP basic auth. Пароль хранится как scrypt-хеш, заголовок Authorization удаляется до того, как запрос дойдёт до приложения, а повторные ошибки замедляются.
  • Список разрешённых IP. tunnel allow принимает до 50 диапазонов IPv4 или IPv6, а me добавляет адрес машины, на которой выполнена команда. WebSocket-апгрейды тоже проверяются. Проверка читает адрес клиента, который выставляет наш пограничный сервер, и никогда — присланный самим клиентом.
  • Долгие запросы. Запрос может длиться до 600 секунд — это важно для медленных сборок и загрузки файлов, которые хостинговые туннели часто обрывают.

Есть и локальный инспектор запросов — небольшая программа на Go, которая показывает проходящий через туннель трафик и хранит его только в памяти на машине пользователя.

Установка там, где GitHub зависает

Клиент — это скрипт PowerShell для Windows и shell-скрипт для Linux и macOS, каждый ставится одной командой. Оба скачивают бинарник клиента frp. Загрузка с релизов GitHub оказалась ненадёжной из некоторых сетей в Узбекистане: передача начиналась и зависала.

Мы зеркалируем файлы релизов frp на своём сервере, и клиенты пробуют сначала зеркало, потом GitHub. Раз зеркало наше, оно не должно становиться обходом доверия. SHA-256 каждого бинарника закреплён в клиентских скриптах, и несовпадающая загрузка отклоняется, откуда бы она ни пришла.

Одну мелкую ошибку переносимости стоит записать для тех, кто пишет установщики на PowerShell. Когда Windows PowerShell 5 запускается изнутри PowerShell 7, модуль с Get-FileHash может не загрузиться. Теперь клиент считает SHA-256 собственной функцией, а не полагается на командлет.

Два дня спустя

Первый релиз покрывал HTTP-туннели. 4 ноября шлюз получил TCP-туннели (включаются для пользователя; каждый пользователь резервирует порт, и плагин frp принимает TCP-прокси только на зарезервированном за ним порту), ограничения частоты запросов для отдельных туннелей, проверку подписей вебхуков для GitHub, Telegram и произвольных HMAC-отправителей, правила для заголовков запросов и ответов и балансировку между несколькими клиентами под одним именем. Вход через Google и оповещения в Telegram есть в коде, но остаются выключенными, пока не настроены.

Ограничения

  • Сертификаты на каждый поддомен. Каждое новое имя стоит одного выпуска примерно на восемь секунд и появляется в публичных журналах. Wildcard запланирован — через делегирование DNS поддомена на сервер под нашим управлением с ACME-DNS.
  • Собственные домены с подтверждением владения запланированы, но не сделаны.
  • Это небольшой сервис. Он работает на инфраструктуре, которую мы уже обслуживаем, а не в глобальной пограничной сети, и не даёт никаких гарантий доступности.

Повторите сами

Клиентский скрипт открыт: посмотрите, как он закрепляет контрольные суммы frp, и замерьте TLS-рукопожатие с сервисом так же, как замеряли мы.

$ curl -fsSL https://tunnel.dtwin.uz/tunnel.sh | grep -in sha256
$ curl -s -o /dev/null -w 'tls=%{time_appconnect}s total=%{time_total}s\n' https://tunnel.dtwin.uz
Репозиторий
Репозиторий закрыт; команды используют только публичные инструменты.
Материалы
wonmortech/research

Источники

  1. tunnel.dtwin.uz
  2. github.com/fatedier/frp
  3. github.com/fatedier/frp/blob/dev/doc/server_plugin.md
  4. caddyserver.com/docs/automatic-https#on-demand-tls
  5. letsencrypt.org/docs/challenge-types/
  6. dtwinuz/tunnel #9
  7. dtwinuz/tunnel #10

Похожие материалы

Смотреть ещё