Описание

Общее описание функционала

CLI-клиент позволяет опубликовать локальный сервис по HTTP, HTTPS, TCP или UDP через туннель и получить для него URL туннеля. Он подходит для удалённого доступа, демонстраций, временного предоставления доступа к стенду и сценариев, где нужен быстрый запуск без веб-интерфейса. Клиент подключается к сервису ForTunnels на https://fortunnels.ru, работает с токеном или логином и паролем, а если на сервере доступен гостевой режим, может создать туннель и без учётной записи. Для соединения используются WebSocket, QUIC или DTLS в зависимости от настроек и условий сети.

Как пользователь может использовать

• Разработчик публикует локальный веб-сервер и получает URL туннеля для быстрого доступа извне.
• Пользователь открывает доступ к локальной базе, сервису или тестовому стенду без отдельного проброса портов.
• Пользователь выбирает WebSocket, если сеть пропускает только обычные HTTPS-соединения.
• Пользователь переключается на QUIC или DTLS, когда нужен альтернативный транспорт для ограниченной сети.
• Пользователь настраивает TCP- или UDP-туннель для сервисов, которые не работают как обычный веб-сайт.
• Пользователь включает режим ожидания stay, чтобы туннель оставался активным во время демонстрации или тестирования.
• Пользователь использует watch, когда нужно отслеживать изменения состояния туннеля без ручного перезапуска.
• Пользователь передаёт секреты через флаги, файлы, стандартный ввод или переменные окружения, чтобы не хранить их в командной строке.
• Явные параметры командной строки (в том числе -login и -pass) имеют приоритет над сохранённым в fortunnels.yml CLI-токеном.
• Пользователь скачивает готовый бинарник со страницы загрузок продукта или ставит клиент через поддерживаемый пакетный менеджер.

Как это реализовано в сервисе

Пользователь запускает CLI с адресом локального сервиса и параметрами подключения. Клиент проходит аутентификацию или использует гостевой режим, создаёт туннель в сервисе и получает URL туннеля. Затем он открывает выбранный канал передачи данных и направляет через него внешний трафик к локальному сервису. Если режим работы не даёт отдельного сигнала о завершении, клиент периодически проверяет состояние туннеля и завершает работу, когда доступ больше не нужен или туннель больше не действует. Ошибки подключения, ограничений и недоступного транспорта выводятся в консоли понятным для пользователя сообщением.

Справочник API

Создание туннеля (плоскость управления)

Клиент использует тот же REST API, что и дашборд: POST /api/tunnels с телом JSON (протокол, целевой адрес, опции авторизации туннеля и т.д.). Требуется заголовок Authorization: Bearer <token> или сессионная кука после входа — в зависимости от режима.

Гостевое создание (если включено на сервере): тот же маршрут без заголовка авторизации; в ответе — URL туннеля, срок жизни и лимиты.

Статус туннеля

GET /api/tunnels?id=<tunnel_id> — используется CLI для опроса жизненного цикла в режимах stay (HTTP/TCP expose-local/UDP), пока процесс удерживает туннель.

Удаление

DELETE /api/tunnels?id=<tunnel_id> — при поддержке сервером и политикой доступа.

Точные поля запроса и ответа совпадают с публичной справкой API сервера и типами в клиентском протоколе.

Транспорт данных

После создания туннеля клиент открывает WebSocket GET /ws (с параметрами режима и tunnel_id в строке запроса) или альтернативный транспорт (QUIC / DTLS) согласно флагам CLI и конфигурации сервера.

Ошибки

Ошибка аутентификации

Сообщение о неверном логине/пароле или просроченном токене; код выхода ненулевой. Нужно обновить учётные данные или получить новый токен.

Отказ в создании туннеля

Ответ API с телом JSON: поле error или message с человекочитаемым текстом (квота, запрещённый протокол, неверные параметры). Исправить параметры или тариф.

«Tunnel was removed. Exiting.»

Туннель удалён на сервере, истёк или доступ отозван; опрос GET /api/tunnels?id=... вернул признак отсутствия или 401. Запустить клиент заново и при необходимости создать новый туннель.

Ошибка сети / таймаут

Нет связи с сервисом ForTunnels. Проверить подключение к сети и DNS для fortunnels.ru.

Недостаточная длина PSK

При включённом шифровании потока PSK короче минимума — клиент завершится с ошибкой валидации до создания туннеля.

Ограничения

• CLI зависит от версии сервера: новые поля API могут требовать обновления клиента.
• Режим guest и лимиты гостевых туннелей задаются на сервере; пользователь не может продлить TTL или сбросить квоту из CLI.
• QUIC/DTLS могут быть недоступны, если сервер или сеть их блокирует; тогда используйте WebSocket.
• Опрос статуса в stay-режиме создаёт периодический трафик к API; при очень большом числе процессов учитывайте лимиты.
• Сообщения об ошибках в консоли не локализованы вне дашборда; язык зависит от версии клиента и ответов сервиса.

Описание

Общее описание функционала

CLI-токен — персональный токен для подключения CLI-клиента ForTunnels к аккаунту пользователя. Он позволяет один раз настроить клиент на рабочей машине и дальше запускать туннели командами вроде fortunnels http 8080 без ручной передачи токена в каждом запуске.

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

Как пользователь может использовать

• Разработчик создаёт CLI-токен на своём ноутбуке и настраивает CLI один раз, чтобы быстро запускать HTTP-туннели к локальному приложению.
• Инженер использует отдельные CLI-токены для разных рабочих машин, чтобы при потере доступа к одной машине отозвать только её токен.
• Пользователь копирует готовую команду fortunnels config add-authtoken ... из дашборда и не редактирует YAML вручную.
• Пользователь проверяет локальный файл конфигурации командой fortunnels config check, прежде чем запускать туннель.
• Пользователь удаляет старый CLI-токен из дашборда, когда меняет устройство или больше не использует CLI на конкретной машине.
• Пользователь на бесплатном тарифе видит, что создание CLI-токена недоступно, и может перейти к смене тарифа из подсказки в интерфейсе.
• Пользователь на Pro или Enterprise создаёт и отзывает CLI-токены как обычно.
• Команда поддержки или администратор может попросить пользователя отозвать CLI-токен, если есть подозрение, что он был скомпрометирован.
• Пользователь хранит CLI-токен в стандартном для своей ОС месте: Linux, macOS и Windows используют разные пути, но CLI выбирает их автоматически.

Как это реализовано в сервисе

Пользователь создаёт CLI-токен в дашборде, сервис показывает секретное значение только в момент создания, а затем хранит у себя только безопасное представление токена. Когда CLI отправляет запрос на создание туннеля, сервис распознаёт персональный токен, связывает запрос с аккаунтом владельца и применяет обычные правила доступа, тарифов и блокировок.

Локальная команда конфигурации записывает CLI-токен в файл на машине пользователя. При запуске туннеля CLI читает этот файл, если токен не был передан более явным способом через флаг, файл секрета, stdin или переменную окружения.

Как использовать через CLI-клиент

После создания CLI-токена в дашборде сохраните его в локальной конфигурации клиента:

fortunnels config add-authtoken <ваш_токен>

Проверить, что файл конфигурации читается корректно:

fortunnels config check

Дальнейшие запуски туннелей (fortunnels http 8080, fortunnels tcp 22 и другие протоколы) подхватят токен автоматически; явная передача -token или переменной FORTUNNELS_TOKEN имеет более высокий приоритет. Подробнее — документация CLI-клиента.

Справочник API

Дашборд: управление токенами

Пользователь управляет CLI-токенами из дашборда. Эти маршруты требуют активной браузерной сессии. Для небезопасных методов используется защита CSRF, как и для других действий дашборда.

Получить список токенов

GET /api/me/authtokens

На бесплатном тарифе без возможности CLI-токен в плане: HTTP 403, JSON code: feature_disabled, feature_id: authtoken.

Успешный ответ:

{
  "authtokens": [
    {
      "id": 1,
      "name": "Laptop",
      "prefix": "ft_abc123",
      "created_at": "2026-05-31T21:00:00Z",
      "last_used_at": "2026-05-31T21:10:00Z",
      "expires_at": null
    }
  ]
}

Полное значение токена в списке не возвращается.

Создать токен

POST /api/me/authtokens

На бесплатном тарифе без возможности CLI-токен в плане: HTTP 403, JSON code: feature_disabled, feature_id: authtoken, текст authtoken requires a paid plan.

Тело запроса:

{
  "name": "Laptop",
  "expires_at": "2026-12-31T00:00:00Z"
}

Поля name и expires_at необязательны.

Успешный ответ:

{
  "id": 1,
  "name": "Laptop",
  "prefix": "ft_abc123",
  "authtoken": "ft_..."
}

Поле authtoken показывается только один раз — в ответе на создание.

Отозвать токен

DELETE /api/me/authtokens/{id}

Успешный ответ: 204 No Content.

CLI: локальная конфигурация

CLI поддерживает команды:

fortunnels config add-authtoken YOUR_FORTUNNELS_TOKEN
fortunnels config check

config add-authtoken записывает токен в конфигурационный файл. config check проверяет наличие файла, корректность YAML, версию схемы и наличие agent.authtoken. Команда не обращается к серверу.

Формат файла:

version: 3

agent:
  authtoken: YOUR_FORTUNNELS_TOKEN

Пути по умолчанию:

• Linux: ~/.config/fortunnels/fortunnels.yml
• macOS: ~/Library/Application Support/fortunnels/fortunnels.yml
• Windows: %LOCALAPPDATA%\fortunnels\fortunnels.yml

Переменная FORTUNNELS_CONFIG задаёт пользовательский путь к конфигурационному файлу.

CLI: запуск туннеля

После настройки CLI использует CLI-токен из конфигурации при командах:

fortunnels http 8080

Более явные источники учётных данных имеют приоритет над конфигурационным файлом: флаг --token, затем --login с паролем (--pass, файл, stdin или FORTUNNELS_PASSWORD), затем --token-file, stdin и переменная FORTUNNELS_TOKEN. Сохранённый в fortunnels.yml CLI-токен используется только если выше ничего не задано.

Если одновременно указаны --login и токен в fortunnels.yml, клиент игнорирует файл и входит по логину и паролю; в stderr выводится предупреждение. Если используется только устаревший или недействительный токен из файла, клиент завершает работу с ошибкой (локально для просроченного JWT или после ответа сервера для недействительного ft_*) и подсказывает обновить или удалить agent.authtoken.

Ошибки

Ошибки дашборда

• HTTP 401: пользователь не вошёл в аккаунт или сессия истекла. Нужно войти в дашборд заново.
• HTTP 400: запрос на создание токена некорректен, например указан неверный формат expires_at. Нужно исправить данные и повторить действие.
• HTTP 403: действие заблокировано политикой доступа, CSRF-проверкой или ограничением тарифа. При code: feature_disabled и feature_id: authtoken сообщение указывает, что CLI-токен недоступен на текущем плане (authtoken requires a paid plan); нужно сменить тариф или обратиться к администратору.
• HTTP 404: пользователь пытается отозвать несуществующий токен или токен, который ему не принадлежит. Нужно обновить список токенов.
• HTTP 409: достигнут лимит активных токенов. Нужно отозвать старый токен и создать новый.
• HTTP 500: внутренняя ошибка сервиса. Нужно повторить позже или обратиться в поддержку.

Ошибки CLI-конфигурации

• No configuration file at ...: файл конфигурации не найден. Нужно создать его вручную или выполнить fortunnels config add-authtoken <token>.
• config version must be 3: версия схемы в YAML не поддерживается. Нужно указать version: 3.
• agent.authtoken is required: в конфигурации нет токена. Нужно добавить agent.authtoken.
• Ошибка парсинга YAML: файл имеет некорректный синтаксис. Нужно исправить отступы и структуру YAML.
• LOCALAPPDATA is not set на Windows: CLI не смог определить стандартный путь. Нужно задать LOCALAPPDATA или FORTUNNELS_CONFIG.

Ошибки запуска туннеля с CLI-токеном

• HTTP 401 при создании туннеля: токен неверный, отозван, истёк или не принят сервером. Нужно создать новый токен в дашборде и обновить локальную конфигурацию.
• HTTP 403 при создании туннеля: аккаунт заблокирован или действие запрещено тарифом/политикой доступа. Нужно проверить статус аккаунта и ограничения тарифа.
• Сообщение о недоступном сервере: CLI не смог подключиться к серверу ForTunnels. Нужно проверить сеть и DNS для fortunnels.ru.

Ограничения

Одноразовый показ токена

Полное значение CLI-токена показывается только сразу после создания. Если пользователь закрыл окно или не сохранил токен, нужно создать новый токен и отозвать старый.

Локальная проверка конфигурации

fortunnels config check проверяет только локальный файл: путь, YAML, версию схемы и наличие agent.authtoken. Команда не подтверждает, что токен действителен на сервере.

Ручная защита локального файла

CLI записывает конфигурационный файл с ограниченными правами, но пользователь отвечает за безопасность своей машины, резервных копий и синхронизаций домашней директории.

Лимит активных токенов

У аккаунта есть ограничение на количество активных токенов. Если лимит достигнут, нужно отозвать неиспользуемые токены.

Тарифный план

Функция CLI-токен доступна только когда она включена в активный тариф пользователя (по умолчанию — платные планы Pro и Enterprise). На Free дашборд не загружает список токенов и блокирует создание и отзыв; прямые запросы к API управления токенами возвращают отказ с кодом feature_disabled.

Приоритет источников токена

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

Отзыв не завершает уже запущенный процесс мгновенно

Отзыв токена запрещает будущую аутентификацию этим токеном. Уже созданный туннель может завершиться по обычным правилам жизненного цикла соединения и серверных проверок.

Описание

Общее описание функционала

Функциональность отвечает за публичный доступ к вашим HTTP- и HTTPS-приложениям через туннель: внешний клиент обращается к поддомену URL туннеля на домене сервиса (например label.fortunnels.ru), а запрос перенаправляется на целевой хост и порт, который вы указали при создании туннеля. Для одноуровневого поддомена URL туннеля на домене сервиса для туннелей зарегистрированных пользователей нужен владелец, администратор или гостевой туннель; сессия или токен должны позволять сервису определить пользователя (cookie сессии на родительском домене или Authorization: Bearer). Для привязанного пользовательского домена по-прежнему допускается публичный доступ по знанию имени хоста — без проверки владения сессией, как «ссылка-возможность»; после этого по-прежнему применяются списки доступа по IP, лимиты и тариф. Проверка владельца, гостевого режима и администратора для поддомена на домене сервиса выполняется до списков доступа по IP и лимитов. Сервис проверяет, существует ли туннель и разрешён ли запрос. Дополнительно могут применяться ограничения по IP, частоте запросов и условиям тарифа (квоты и включённые возможности). При недоступности целевого приложения или срабатывании ограничений клиент получает понятный по смыслу ответ об ошибке вместо успешного ответа от вашего приложения.

Как пользователь может использовать

• Разработчик поднимает API или веб-интерфейс локально и открывает его коллегам или тестовой среде по выданному URL туннеля, не выставляя машину в интернет напрямую.
• Интегратор проверяет вебхуки или OAuth-редиректы: внешний сервис шлёт запросы на адрес туннеля, а трафик доходит до локального стенда.
• Владелец туннеля делится URL туннеля на поддомене сервиса с коллегами и интеграциями.
• Владелец на платном тарифе в дашборде туннелей переключает колонку «Публичный», чтобы скрыть HTTP/HTTPS-туннель от анонимных посетителей или снова открыть его; подробнее — приватные HTTP-туннели.
• Для приложений на Next.js и похожих SPA URL туннеля на поддомене обычно работает прозрачно для типовых запросов, включая загрузку _next-ресурсов, fetch, WebSocket, EventSource и sendBeacon.
• Пользователь с гостевым туннелем (доступный всем) демонстрирует прототип заказчикам без входа в аккаунт у них; при этом приватные туннели остаются доступны только владельцу и уполномоченным ролям.
• Администратор в личном кабинете (/dashboard/tunnels) видит в списке только свои туннели; полный обзор всех пользователей — в админ-консоли на выделенном админ-хосте. Отладка чужого туннеля через Inspector по прямой ссылке из админ-консоли по-прежнему доступна.
• Клиент API или скрипт автоматизации дергает те же URL туннелей, что и браузер, для проверки поведения за прокси (заголовки, редиректы, тело ответа).
• Пользователь сталкивается с временной приостановкой туннеля и видит, что сервис недоступен до возобновления, вместо «тихого» ответа от старого кэша.
• Владелец плана с лимитами отслеживает, что при исчерпании квоты или отключённой возможности запросы к туннелю отклоняются с явным сигналом, а не проксируются «в никуда».
• Пользователь с ограничениями по IP или частоте запросов понимает по ответу сервиса, что доступ временно или постоянно ограничён политикой безопасности или защитой от злоупотреблений.
• Посетитель основного сайта сервиса и посетитель URL туннеля получают согласованное поведение по протоколу (например, ожидаемые редиректы на HTTPS там, где это задумано продуктом).
• Поддерживаются долгоживущие соединения WebSocket через тот же обратный прокси, при условии корректных таймаутов на публичном входе.
• Если приложение критически зависит от service worker, офлайн-кэша или фонового перехвата запросов, убедитесь, что оно корректно обслуживается с корневого пути на выданном публичном хосте.
• Нужны формализованные истории уровня продукта — см. пользовательские истории HTTP/HTTPS.

Как это реализовано в сервисе

Входящий HTTP-запрос сначала попадает на публичную точку входа: по заголовку Host определяется, к какому туннелю относится запрос; затем проверяется, что туннель существует и находится в состоянии, допускающем обработку. Для одноуровневого поддомена на домене сервиса (URL туннеля вида label.<домен_сервиса>) для туннелей с владельцем выполняется проверка доступа (владелец, гость, администратор) до списков доступа по IP. Для хоста, привязанного как пользовательский домен (отдельная привязка в хранилище), публичный доступ по знанию имени хоста сохраняется; затем по-прежнему применяются списки доступа по IP, лимиты и тарифные проверки владельца. В API списков и чтения туннелей для гостей по-прежнему может использоваться скрытие факта существования чужих туннелей (404), что не отменяет описанную модель прокси. После этого могут учитываться сетевые списки доступа, ограничение интенсивности запросов и условия тарифа владельца. Если все проверки пройдены, запрос пересылается на целевой адрес туннеля как обратный прокси: сохраняется метод, тело и заголовки в допустимых пределах, устанавливается соединение с пулом повторного использования соединений к цели. Ответ целевого приложения возвращается клиенту; при ошибках на любом этапе (не найден туннель, отказ в доступе, перегрузка лимитами, недоступность цели, тайм-аут) формируется ответ об ошибке на стороне сервиса до завершения или вместо проксирования.

Как использовать через CLI-клиент

HTTP- или HTTPS-туннель запускается из CLI с указанием локального адреса приложения. Краткая форма — порт как позиционный аргумент; явно — флаги -protocol и -local.

Пример для локального веб-сервера на порту 8080:

fortunnels http 8080

или:

fortunnels -protocol http -local 127.0.0.1:8080

После успешного создания клиент выводит URL туннеля; процесс остаётся активным, пока вы его не остановите. Для доступа от имени аккаунта передайте токен (-token), логин и пароль (-login) или заранее сохраните CLI-токен (fortunnels config add-authtoken …). Режим отслеживания состояния туннеля — флаг -watch. Полный перечень флагов транспорта и протоколов — в документации CLI-клиента.

Справочник API

Публичное проксирование

• GET https://{subdomain}.{domain}/* — проксирование HTTP-запросов к целевому туннелю по поддомену из URL туннеля (в ответе API — поле public_url)
• GET https://{custom_domain}/* — маршрутизация по привязанному пользовательскому домену

Поддерживаются все HTTP-методы (GET, POST, PUT, DELETE и др.). Заголовки, тело и параметры запроса сохраняются при пересылке.

Управление туннелями (API)

• POST /api/tunnels — создание туннеля с протоколом HTTP/HTTPS
• GET /api/tunnels?id=<id> — получение информации о туннеле (или GET /api/tunnels со списком)
• PATCH /api/tunnels — обновление конфигурации туннеля; в теле JSON укажите id и действие (пауза, транспорт, TLS, регенерация URL, редиректы и т.д.)
• DELETE /api/tunnels?id=<id> — удаление туннеля

Для HTTP/HTTPS-туннелей поддерживается действие set_public_subdomain: в теле JSON указываются id, action: "set_public_subdomain" и поле public_subdomain (метка поддомена). Ограничения: валидация метки, уникальность хоста, зарезервированные имена, при включённых тарифах — возможность custom-public-subdomain, отдельный лимит частоты смены метки, максимальный размер тела PATCH. Коды ответов: см. раздел Ошибки возможности «Свой поддомен» в документации.

Для зарегистрированных пользователей с тарифными планами при создании туннеля возможны ответы 403 с JSON-кодами: user_suspended (аккаунт заблокирован) или quota_exceeded с полем quota: max_concurrent_tunnels (превышен лимит одновременных туннелей). Поле expires_at в ответе может отражать ограничение срока жизни туннеля по плану.

Запрос создания туннеля

{
  "protocol": "http",
  "target_addr": "127.0.0.1:8000"
}

Поле user_id в теле создания не используется в публичном API: владелец определяется сессией или Bearer-токеном. В self-hosted/dev-окружениях оператор может задавать учётные записи через админ-инструменты, но клиентам панели и CLI поле передавать не нужно.

Ответ создания туннеля

{
  "id": "a1b2c3d4e5f6g7h8",
  "protocol": "http",
  "target_addr": "127.0.0.1:8000",
  "public_url": "http://xyz789.fortunnels.ru",
  "created_at": "2024-01-01T12:00:00Z",
  "expires_at": "2024-01-01T14:00:00Z"
}

Поддомен URL туннеля генерируется независимо от id туннеля для повышения безопасности (в ответе API — поле public_url).

Список и детали туннеля (GET /api/tunnels, GET /api/tunnels?id=<id>)

Ответ списка и одиночного туннеля включает поля created_at, expires_at, bytes_used, traffic_limit_bytes и объект limit_indicators — компактные индикаторы лимитов для интерфейса (без отдельного запроса на строку).

limit_indicators

| Поле | Описание |

|------|----------|

| as_of | Момент расчёта на сервере (RFC3339) |

| lifetime | Оставшееся время жизни туннеля из created_at / expires_at |

| traffic | Per-tunnel трафик из bytes_used / traffic_limit_bytes (для гостевых туннелей); для зарегистрированных владельцев — unavailable (месячный egress аккаунта не показывается как per-tunnel cap) |

| http_rpm | Оставшаяся ёмкость HTTP-запросов в минуту по плану в текущем окне |

Состояния каждого индикатора: limited, unlimited, unavailable, zero_limit, exhausted, expired.

Снимок http_rpm носит информационный характер и не расходует лимит запросов при чтении; фактическое ограничение применяется при обработке HTTP-запросов к туннелю.

Для не-админов поля user_id и owner_login по-прежнему опускаются в теле туннеля; limit_indicators не содержит owner/account/plan идентификаторов.

Область списка для администратора

Один и тот же endpoint GET /api/tunnels возвращает разный набор туннелей в зависимости от того, откуда администратор открыл интерфейс:

| Контекст | Где в продукте | Что в списке |

|----------|----------------|--------------|

| Личный кабинет | /dashboard/tunnels на основном домене | Только туннели, принадлежащие этому администратору (как у обычного пользователя) |

| Админ-консоль | /tunnels на выделенном админ-хосте (например admin.fortunnels.ru; в локальной разработке — /admin/tunnels) | Все туннели всех пользователей |

В личном кабинете администратор не видит чужие туннели в списке, счётчиках и пагинации. В админ-консоли по-прежнему доступен полный обзор флота; в списке для чужих туннелей могут отображаться поля владельца (owner_login, user_id).

Исключение: открытие конкретного туннеля или Inspector по прямой ссылке (в том числе переход из админ-консоли на /dashboard/tunnels/{id}/inspector для чужого туннеля) по-прежнему разрешено администратору — это не расширяет список в личном кабинете.

CLI и прочие API-клиенты без контекста админ-консоли получают лично-кабинетный список (только свои туннели).

Пример фрагмента:

{
  "limit_indicators": {
    "as_of": "2026-06-05T12:00:00Z",
    "lifetime": {
      "state": "limited",
      "used_seconds": 120,
      "remaining_seconds": 480,
      "total_seconds": 600,
      "reset_at": "2026-06-05T14:00:00Z"
    },
    "traffic": {
      "state": "limited",
      "used_bytes": 256,
      "remaining_bytes": 768,
      "total_bytes": 1024
    },
    "http_rpm": {
      "state": "limited",
      "used_requests": 3,
      "remaining_requests": 7,
      "total_requests": 10,
      "reset_at": "2026-06-05T12:01:00Z"
    }
  }
}

Поле remaining_requests в http_rpm — оставшаяся ёмкость HTTP requests/min в текущем окне (не current_http_requests_per_minute).

Ошибки

413 Payload Too Large

Когда возникает: Тело запроса PATCH /api/tunnels/{id} превышает лимит размера (внутренний порог для JSON-действий с туннелем).

Что делать: Уменьшить тело запроса; для set_public_subdomain достаточно компактного JSON с полями id, action, public_subdomain.

400 Bad Request

Когда возникает: Невалидный формат ID туннеля, некорректный запрос, попытки path traversal (../ в путях), невалидная метка public_subdomain, зарезервированное имя поддомена, действие только для HTTP/HTTPS.

Что делать: Проверить корректность URL и ID туннеля. Убедиться, что путь не содержит недопустимых последовательностей.

403 Forbidden

Когда возникает: ACL запретил доступ, требуется аутентификация, пользователь обращается к чужому туннелю.

Что делать: Проверить права доступа и настройки ACL туннеля. Убедиться, что аутентификация валидна и пользователь имеет право доступа к туннелю.

404 Not Found

Когда возникает: Туннель не найден, невалидный путь или ID туннеля.

Что делать: Проверить корректность ID туннеля и URL. Убедиться, что туннель существует и не истёк.

429 Too Many Requests

Когда возникает: Превышен лимит запросов (глобальный, на пользователя или на туннель).

Что делать: Снизить частоту запросов. Заголовок Retry-After указывает, когда можно повторить запрос.

502 Bad Gateway

Когда возникает: Целевой сервис недоступен, подключение не удалось (connection refused, timeout).

Что делать: Убедиться, что локальный сервис запущен и доступен по адресу, указанному при создании туннеля. Повторить запрос после восстановления сервиса.

503 Service Unavailable

Когда возникает: Туннель приостановлен; туннель возобновлён в панели, но клиент ещё не переподключился («Туннель возобновляется»); или временные проблемы на стороне сервера.

Что делать: Проверить статус туннеля через API. Если туннель возобновлён — подождать несколько секунд (клиент переподключается после паузы). Возобновить туннель при необходимости.

504 Gateway Timeout

Когда возникает: Превышен таймаут запроса к целевому сервису.

Что делать: Проверить доступность и нагрузку локального сервиса. Увеличить таймаут в конфигурации туннеля при необходимости.

Описание

Общее описание функционала

Инспектор TCP-трафика даёт владельцу TCP-туннеля просматривать историю TCP-соединений, проходящих через туннель: адреса клиента и цели, длительность, объём трафика, состояние завершения и при необходимости укороченный захват потока в текстовом или шестнадцатеричном виде. Данные доступны в дашборде на странице инспектора туннеля (вкладка TCP) и через API с поддержкой потоковой подписки (SSE) для живых обновлений.

Как пользователь может использовать

• Разработчик отлаивает нестабильное TCP-приложение: открывает инспектор, сортирует соединения по времени, находит обрывы и ошибки.
• Пользователь проверяет, что внешний клиент действительно доходит до указанного целевого адреса, сверяя IP и порты в списке.
• Пользователь переключает отображение текст/hex для просмотра коротких текстовых протоколов поверх TCP.
• Пользователь фильтрует соединения по состоянию (активные, закрытые, ошибка) для фокуса на проблемных сессиях.
• Администратор при поддержке пользователя просматривает те же метаданные в рамках полномочий продукта.
• Инженер подписывается на SSE-поток, чтобы видеть новые соединения в реальном времени во время теста.

Как это реализовано в сервисе

При установке и закрытии TCP-соединения через туннель сервис фиксирует событие и сохраняет его в базе вместе с ограниченным объёмом перехваченных байт. Запросы из интерфейса дашборда или API проходят проверку владельца туннеля (или права администратора), затем возвращают страницу списка или одну запись. Поток событий рассылает новые записи подписчикам; частота опроса ограничивается лимитами сервера. В публичном развёртывании инспектор доступен только при корректной аутентификации и настройке режима работы, отличного от небезопасной отладочной конфигурации.

Справочник API

Список соединений

GET /api/v1/inspector/tcp/connections

Параметры:

• tunnel_id (обязательный) — ID туннеля
• from — начало периода (RFC3339)
• to — конец периода (RFC3339)
• state — фильтр по состоянию: active, closed, error
• limit — лимит (по умолчанию 50)
• offset — смещение

Ответ: { "connections": [...], "pagination": { "limit", "offset", "count", "has_more" } }

Получение соединения

GET /api/v1/inspector/tcp/connections/:id

Параметры:

• format — text | hex (опционально, для формата stream_capture)

Ответ: объект TCPConnectionEvent с полями id, tunnel_id, client_ip, client_port, target_addr, started_at, ended_at, duration_ms, bytes_in, bytes_out, state, error_msg, stream_capture / stream_capture_text / stream_capture_hex

SSE-поток

GET /api/v1/inspector/tcp/connections/stream?tunnel_id=...

События: { "type": "tcp_connection", "data": TCPConnectionEvent }

Ошибки

Справочник ошибок

| Код | Сообщение | Условие |

|-----|-----------|---------|

| 401 | Unauthorized | Отсутствует или недействительна авторизация |

| 403 | Forbidden | Пользователь не имеет доступа к туннелю |

| 404 | TCP connection not found | Соединение не найдено |

| 503 | Service Unavailable | Сервис инспектора недоступен |

Ограничения

Известные ограничения

• Захват потока ограничен (по умолчанию 32 КБ на соединение)
• Guest-пользователи не имеют доступа к TCP-инспектору
• Клиентский IP в dataplane-пути может быть недоступен (отображается как «dataplane»)
• Отображение потока в текстовом формате может содержать замены для невалидного UTF-8

Риски конфигурации

• tls_insecure_skip_verify: При создании/изменении HTTPS-туннелей можно отключить проверку TLS-сертификата бэкенда. Это делает трафик уязвимым к MITM. Использовать только для доверенных внутренних целей (localhost, dev-сертификаты). Никогда не включать для ненадёжных или публичных бэкендов.

Описание

Общее описание функционала

TCP-туннелирование открывает локальный TCP-сервис (SSH, база данных, произвольный бинарный протокол) для доступа с интернета через инфраструктуру туннеля. Трафик передаётся как поток байт с мультиплексированием по надёжному транспорту между клиентом и сервером; поддерживаются режим публичного порта на стороне сервиса и сценарий expose-local (внешний порт на сервере), когда внешние клиенты подключаются к выделенному порту, а агент пробрасывает соединение на локальную машину. Для протоколов с TLS на стороне приложения платформа не расшифровывает полезную нагрузку на границе (в отличие от HTTP(S)-туннеля с терминацией TLS на входе).

Как пользователь может использовать

• Разработчик открывает SSH к домашней машине для удалённой отладки.
• Команда подключается к общей базе данных на стенде разработчика через выданный host:port.
• Пользователь поднимает туннель к промышленному устройству или SCADA по TCP.
• Пользователь использует режим expose-local (внешний порт на сервере), чтобы внешний партнёр подключился к порту на сервере туннелей, а трафик ушёл на 127.0.0.1 у владельца.
• Пользователь полагается на автоматические повторы при кратковременных обрывах транспорта между CLI и сервером.
• Администратор ограничивает доступ списками IP на уровне туннеля.
• Пользователь сравнивает с HTTP(S)-туннелем: для «короткой ссылки в браузере» чаще подходит HTTP-маршрут; для сквозного TLS приложения — TCP-туннель (см. пользовательские истории TCP).
• На macOS пользователь может сочетать expose-local TCP с локальным слушателем на 127.0.0.1 (например nc или опционально socat) для интерактивной TCP-сессии поддержки и отладки (см. US-12 и раздел Ограничения).

Как это реализовано в сервисе

Клиент регистрирует туннель на плоскости управления и получает публичный адрес:порт или инструкции для режима expose-local. Плоскость данных устанавливает защищённый канал между сервером и CLI, через который байты копируются между сокетом в интернете и локальным приложением. Сервер выделяет порты из настроенного диапазона, применяет лимиты на соединения и уважает паузу туннеля. Контроль доступа и тарифные ограничения применяются на этапе установления соединения и при создании туннеля так же, как для других протоколов.

Как использовать через CLI-клиент

TCP-туннель создаётся с протоколом tcp и адресом локального TCP-сервиса. Пример для SSH на порту 22:

fortunnels tcp 22

или:

fortunnels -protocol tcp -local 127.0.0.1:22

Транспорт данных по умолчанию — WebSocket; альтернативы -dp quic и -dp dtls описаны в документации CLI-клиента.

Справочник API

Создание туннеля

POST /api/tunnels

Пример тела:

{
  "protocol": "tcp",
  "target_addr": "127.0.0.1:22"
}

Ответ содержит id, public_addr (или эквивалент host:port) и метаданные создания.

Требуется аутентификация, если на сервере не разрешён только гостевой режим.

Чтение и удаление

• GET /api/tunnels?id={id} — получить один туннель (или GET /api/tunnels для списка).
• PATCH /api/tunnels — обновить туннель; в теле JSON укажите id и поля/действие.
• DELETE /api/tunnels?id={id} — удалить туннель.

Публичный вход

Внешний клиент открывает TCP на выданный public host:port; сервер сопоставляет поток с туннелем и клиентским агентом.

CLI

См. справку fortunnels для режима tcp и expose-local; глобальные флаги сервера, аутентификации и транспорта (-dp ws/quic/dtls) общие с другими протоколами.

Ошибки

Отказ в подключении

Целевой localhost порт закрыт — внешний клиент или CLI получают обрыв или сообщение об ошибке прокси в зависимости от стадии.

Превышен лимит одновременных соединений

Новые подключения к туннелю отклоняются или ожидают освобождения слота согласно политике сервера и тарифа.

ACL

Подключение с заблокированного IP отклоняется на входе туннеля.

Квоты и тариф

Создание или использование туннеля может быть отклонено с JSON 403 (квота, функция недоступна) по тем же правилам, что и HTTP-туннели.

Аутентификация

401 при обращении к API без учётных данных там, где они обязательны.

Ограничения

• Дополнительная задержка и джиттер по сравнению с прямым TCP неизбежны из-за туннелирования.
• Пул публичных портов ограничен настройками сервиса; исчерпание диапазона блокирует новые TCP-туннели.
• При паузе туннеля публичные соединения не обслуживаются до возобновления и переподключения клиента.
• Режим expose-local зависит от поддержки в CLI и на сервере; сетевой путь отличается от классического «публичный порт на сервере → локальный сервис».
• Не гарантируется сохранение долгих idle-соединений при агрессивных таймаутах NAT и прокси на пути.
• На macOS поведение интерактивной TCP-сессии зависит от выбранных утилит (BSD nc vs GNU netcat, опционально socat): это не SSH; полноценный TTY и сигналы не гарантируются. Рекомендуется слушать только 127.0.0.1, а не 0.0.0.0. Типовой порядок: (1) запустить локальный слушатель, например nc -l 127.0.0.1 7777; (2) поднять TCP-туннель на этот порт; (3) удалённый клиент подключается к выданному публичному host:port.

Описание

Общее описание функционала

Инспектор HTTP-трафика сохраняет события HTTP/HTTPS-запросов, прошедших через туннель: метод, путь, код ответа, задержку и выборочные заголовки/тело в пределах политики приватности и размера. Владелец туннеля просматривает журнал в дашборде на странице инспектора и может повторить отдельный запрос в безопасном режиме с ограничениями на подмену пути и заголовков.

Как пользователь может использовать

• Разработчик отлаивает API: находит неудачный запрос в списке, открывает детали и сравнивает с ответом бэкенда.
• Пользователь фильтрует события по туннелю, времени и пагинации, чтобы не загружать весь журнал.
• Пользователь подписывается на поток событий (SSE) для живого просмотра во время ручного теста.
• Пользователь запускает повтор запроса события в режиме «через облако» или «локально» с допустимыми правками тела/метода в рамках ограничений сервера.
• Администратор при поддержке просматривает те же события в рамках полномочий.

Как это реализовано в сервисе

При проксировании HTTP-запроса сервис записывает нормализованное событие в хранилище инспектора (при включённой функции и настройках захвата). Запросы к API списка и детали проходят аутентификацию и проверку владения туннелем. Повтор запроса выполняется в изолированном контуре с валидацией переопределений (запрет опасных заголовков и абсолютных URL в пути, лимит размера тела), чтобы снизить риск злоупотреблений. В боевом режиме доступ к инспектору не должен быть открыт без входа; в отладочном режиме правила могут отличаться — это задача оператора развёртывания.

Справочник API

Список событий

GET /api/v1/inspector/events

Параметры (имена уточняйте по ответу сервера): tunnel_id, фильтры времени, пагинация limit / offset или курсор.

Ответ: JSON со списком событий и метаданными пагинации.

Одно событие

GET /api/v1/inspector/events/{id}

id должен быть URL-encoded в клиенте.

Поток SSE

GET /api/v1/inspector/events/stream?tunnel_id=...

Подписка на новые события; tunnel_id в query также передавать в закодированном виде при необходимости.

Повтор запроса

POST /api/v1/inspector/events/{eventId}/replay

Тело JSON: { "mode": "cloud" | "local", "overrides": { ... опционально } }.

• cloud — повтор выполняется на сервере Fortunnels и уходит через публичный edge туннеля (как внешний клиент). Подходит для проверки маршрута end-to-end на fortunnels.ru.
• local — повтор отправляется из процесса сервера напрямую к target_addr туннеля, минуя публичный ingress. Подходит для self-hosted отладки backend без внешнего DNS.

Поля overrides (правки метода, пути, заголовков и тела) ограничены сервером: нельзя подставить абсолютный URL в path, запрещённые заголовки и слишком большое тело (лимит порядка десятков килобайт).

Ошибки

401 Unauthorized

Нет сессии или токена для инспектора (в боевом режиме).

403 Forbidden

Нет доступа к туннелю события.

400 Bad Request

Некорректные параметры списка или недопустимые правки запроса при повторе (путь, заголовки, размер тела).

404 Not Found

Событие не найдено или недоступно.

503 Service Unavailable

Инспектор отключён или хранилище недоступно.

Ограничения

• Захват может не включать полное тело запроса/ответа или маскировать чувствительные поля по политике сервера.
• Повтор запроса не гарантирует идентичный побочный эффект на бэкенде; использовать только на тестовых стендах с осторожностью.
• Большие журналы требуют фильтрации по времени и туннелю.
• В dev-режиме сервера правила аутентификации к инспектору могут быть слабее, чем в продакшене.

Описание

Общее описание функционала

Инспектор UDP-трафика позволяет владельцу UDP-туннеля просматривать проходящие датаграммы: направление (к клиенту или к бэкенду), адреса, размер полезной нагрузки, время и при необходимости укороченное содержимое пакета с текстовой/шестнадцатеричной подсказкой и эвристическим разбором известных протоколов. Данные накапливаются на стороне сервиса и доступны через API и вкладку инспектора у туннеля. Гостевой режим не имеет доступа к UDP-инспектору.

Как пользователь может использовать

• Разработчик отлаивает DNS, игровой UDP или кастомный протокол: открывает инспектор туннеля, вкладку UDP, фильтрует по времени и направлению, смотрит цепочку запрос/ответ между клиентом и локальным сервисом.
• Пользователь ищет конкретный поток по flow_key или подстроке адреса, чтобы отделить один клиент от другого.
• Администратор при расследовании инцидента запрашивает датаграммы пользователя по user_id (через админские параметры API), не смешивая чужие туннели без полномочий.
• Инженер подписывается на поток событий (SSE) для живого мониторинга во время нагрузочного теста.
• Пользователь открывает карточку датаграммы по идентификатору, чтобы увидеть полные метаданные и анализ полезной нагрузки, если она сохранена и не обрезана политикой размера.
• Сопровождение сверяет, что после изменения конфигурации туннеля трафик действительно доходит до бэкенда, сравнивая метки времени и направления в списке.

Как это реализовано в сервисе

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

Справочник API

Список датаграмм

GET /api/v1/inspector/udp/datagrams

Основные параметры запроса:

• tunnel_id — фильтр по туннелю (для не-админа обычно обязателен для осмысленной выборки и проверки доступа)
• from, to — границы времени (RFC3339)
• direction — направление потока
• flow_key — ключ потока
• addr_contains — подстрока в адресе
• search, search_payload, field_contains — расширенный поиск (при поиске по полезной нагрузке действуют более строгие лимиты выборки)
• limit, offset — пагинация

Ответ: JSON с массивом datagrams и объектом pagination (лимит, смещение, признак наличия следующих страниц).

Для администратора допускается параметр user_id для выборки в разрезе другого пользователя (см. поведение сервера в продакшене).

Одна датаграмма

GET /api/v1/inspector/udp/datagrams/{id}

id — UUID записи.

Ответ: метаданные записи; при наличии сохранённой полезной нагрузки — поля вроде payload, hex_dump, utf8_preview, analysis, а также parsed_summary / metrics, если заполнялись.

Поток SSE

GET /api/v1/inspector/udp/datagrams/stream

Опционально tunnel_id для фильтрации событий.

События с типом, соответствующим UDP-датаграммам (например udp_datagram), с телом в формате JSON.

Ошибки

401 Unauthorized

Пользователь не аутентифицирован или используется гостевой доступ — для UDP-инспектора он не допускается.

403 Forbidden

Аутентифицированный пользователь не имеет права на указанный туннель (чужой туннель без роли администратора).

400 Bad Request

Некорректные параметры фильтра (например, невалидный JSON в field_contains) или отсутствует идентификатор датаграммы в пути там, где он обязателен.

404 Not Found

Запись с указанным UUID не найдена или недоступна текущему пользователю.

429 Too Many Requests

Сработали лимиты частоты для API инспектора UDP.

503 Service Unavailable

Сервис инспектора отключён или хранилище недоступно.

500 Internal Server Error

Внутренняя ошибка при чтении или кодировании ответа. Повторить позже.

Ограничения

• Полезная нагрузка датаграммы обрезается на уровне сервера: длинные пакеты в списке и в деталях могут отображаться не полностью; точный предел задаётся конфигурацией сервера.
• Поиск, включающий содержимое полезной нагрузки, дороже обычного списка; сервер может снижать максимальный limit выборки.
• Разбор протоколов носит эвристический характер и не заменяет специализированные анализаторы.
• В режиме разработчика правила аутентификации к инспектору могут отличаться от боевого режима; в продакшене требуется строгая аутентификация и настроенные лимиты.

Описание

Общее описание функционала

UDP-туннелирование пересылает датаграммы между локальным UDP-сервисом и клиентами в интернете через инфраструктуру туннеля. Подходит для DNS, syslog, игровых протоколов и других сценариев, где важна низкая задержка и модель «без установления соединения», с пониманием, что потери и порядок остаются на совести UDP. Сервер выделяет публичный UDP-порт в заданном диапазоне и сопоставляет потоки по правилам сессий и ключей потока.

Как пользователь может использовать

• Разработчик публикует локальный DNS-резолвер или тестовый UDP-сервис для команды.
• Администратор собирает syslog или метрики с удалённых хостов на локальный коллектор.
• Пользователь подключается к игровому или стриминговому UDP-сервису за NAT.
• Пользователь задаёт в CLI локальный UDP listen и целевой адрес на стороне сервера согласно документации.
• Пользователь учитывает таймаут неактивности и максимальный размер датаграммы, настроенные оператором.

Как это реализовано в сервисе

Клиент создаёт туннель с протоколом udp и использует выбранный транспорт для передачи трафика; в параметрах запуска или сопутствующих сообщениях задаётся соответствие локального порта и удалённого назначения. Сервер слушает UDP на выделенном порту из диапазона конфигурации, классифицирует пакеты по туннелю и потоку и пересылает их через защищённый канал к агенту, который отправляет датаграммы локальному приложению. Неактивные потоки могут очищаться по таймеру; превышение размера датаграммы отсекается. Тарифы и списки доступа по IP применяются там, где продукт их подключает для UDP.

Как использовать через CLI-клиент

Основной сценарий — публикация локального UDP-сервиса (как в ngrok):

fortunnels udp 9000
fortunnels udp 192.168.1.10:9000

Клиент создаёт туннель, подключается к data-plane по WebSocket/smux и пересылает входящие датаграммы с публичного UDP-порта на локальный адрес.

Расширенный режим reverse-proxy (оба флага обязательны):

fortunnels udp 53 -udp-listen :5353 -udp-dst 127.0.0.1:53

Укажите учётные данные (токен, -login или сохранённый CLI-токен), если подключаетесь не в гостевом режиме. Подробности флагов -udp-listen и -udp-dst — в документации CLI-клиента.

Справочник API

Создание туннеля

POST /api/tunnels

Пример:

{
  "protocol": "udp",
  "target_addr": "127.0.0.1:5353"
}

Ответ: идентификатор туннеля и публичный UDP-адрес (схема udp://host:port или поля host/port — как возвращает ваш сервер).

Статус и удаление

GET / DELETE по контракту API туннелей с идентификатором (см. актуальные пути в справочнике сервера).

CLI

fortunnels в режиме udp с флагами локального прослушивания и удалённого назначения (см. -udp-listen, -udp-dst в справке клиента).

Инспектор UDP

Просмотр записанных датаграмм: GET /api/v1/inspector/udp/datagrams (отдельная возможность продукта; требует прав зарегистрированного пользователя, не гостя).

Ошибки

Датаграмма слишком большая

Пакет превышает udp_max_payload_bytes сервера — отбрасывается или не пересылается (наблюдаемо как отсутствие ответа на стороне UDP).

Нет свободного порта

Не удаётся выделить порт из udp_port_range — создание туннеля завершается ошибкой API.

Таймаут неактивности

Поток UDP закрыт после простоя; следующая датаграмма может инициализировать новый поток или быть потеряна в зависимости от клиента.

401 / 403 на API

Создание или управление без прав или при запрете протокола политикой.

Ограничения

• UDP не гарантирует доставку и порядок; приложение должно это учитывать.
• NAT и файрволы могут ограничивать входящий UDP к клиенту агента.
• Диапазон публичных портов и лимиты размера задаются конфигурацией; нет отдельного глобального «выключателя UDP» в современной модели — доступ контролируется диапазоном, ACL и протоколом туннеля.
• Устаревшие флаги вроде -udp-enabled у сервера не используются; их наличие в скриптах приведёт к ошибке запуска.

Описание

Общее описание функционала

Гостевой доступ позволяет создать туннель без регистрации и входа: пользователь сразу получает URL туннеля к локальному сервису. Это снижает порог для демонстраций, быстрых вебхуков и разовых задач. Гостевой туннель живёт ограниченное время, имеет лимит объёма трафика и не даёт полноценного управления в дашборде; зарегистрированные пользователи получают расширенные возможности и контроль.

Как пользователь может использовать

• Новый пользователь запускает CLI без логина и получает URL для демо локального сайта коллегам.
• Разработчик проверяет вебхук стороннего сервиса, отправляя URL гостевого туннеля во внешнюю систему.
• Посетитель открывает выданный URL туннеля в браузере без аккаунта на платформе и видит ответ локального сервиса владельца туннеля.
• Пользователь исчерпывает лимит времени или трафика и создаёт новый гостевой туннель для следующей задачи.
• Пользователь решает зарегистрироваться, чтобы получить постоянные туннели, список в дашборде и функции тарифа.

Как это реализовано в сервисе

Запрос на создание туннеля без учётных данных обрабатывается плоскостью управления как особый тип учётной записи: выдаются короткоживущие параметры (срок жизни, потолок трафика), туннель появляется в той же подсистеме маршрутизации, что и именованные туннели. Публичный вход проксирует HTTP(S) или другие протоколы по правилам продукта; гость не видит инспектор и административные разделы. После истечения срока или лимита туннель перестаёт принимать трафик; управление «списком гостевых туннелей» в интерфейсе не предусмотрено — идентификация идёт по выданному URL.

Как использовать через CLI-клиент

Если на сервере включён гостевой режим, туннель можно создать без входа и без CLI-токена — укажите адрес сервиса и локальный порт приложения:

fortunnels http 8080

Клиент создаст краткоживущий туннель с лимитами времени и трафика; URL туннеля появится в выводе. Для TCP или UDP используйте соответствующий протокол (fortunnels tcp 22, fortunnels udp 53 с нужными UDP-флагами). Ограничения гостевого режима описаны выше; полный список флагов — в документации CLI-клиента.

Справочник API

Создание гостевого туннеля

POST /api/tunnels

Тело JSON: те же поля, что и для обычного создания (protocol, целевой адрес и т.д.), см. общую справку по API туннелей.

Без заголовка Authorization и без сессионной куки — если гостевой режим разрешён на сервере.

Ответ: данные туннеля с URL туннеля (в ответе API — поле public_url), время истечения, сведения о лимите трафика — в форме, которую возвращает ваш экземпляр сервера.

Доступ посетителя к URL

GET / POST / другие методы на URL туннеля (поддомен из ответа API) — без входа на платформу; поведение определяется типом туннеля и локальным сервисом.

Ограничения для гостя

Эндпоинты дашборда, инспектора трафика и админки требуют зарегистрированного пользователя; гостевой токен URL не заменяет сессию для этих API.

Ошибки

Отказ в создании гостевого туннеля

Сервер отключил гостевой режим или превышена внутренняя квота — 4xx/5xx с телом JSON или текстом по политике развёртывания.

Туннель истёк или исчерпан трафик

Запросы к URL туннеля возвращают страницу или JSON с сообщением о недоступности; нужно создать новый гостевой туннель.

401 на защищённых API

Попытка вызвать пользовательский API дашборда без регистрации — ожидаемое поведение для гостя.

Ограничения

• Ограниченный срок жизни туннеля (типично до 24 часов).
• Ограниченный объём трафика на туннель; при исчерпании туннель останавливается до срока.
• Нет списка гостевых туннелей в личном кабинете; сохраняйте выданный URL самостоятельно.
• Нельзя приостанавливать, удалять или настраивать гостевой туннель через дашборд тем же способом, что у зарегистрированного пользователя.
• Инспектор трафика и расширенная аналитика недоступны гостю.
• Протоколы и лимиты гостя задаются конфигурацией сервера и могут отличаться между развёртываниями.

Описание

Общее описание функционала

Раздел «Настройки» в дашборде позволяет просматривать и менять параметры интерфейса, транспорта и связанных возможностей, а также при необходимости экспортировать и импортировать конфигурацию в JSON. Часть действий привязана к платным возможностям тарифа: на бесплатном плане соответствующие элементы отображаются неактивными с подсказкой о смене тарифа, а сервер дополнительно проверяет права при сохранении.

Как пользователь может использовать

• Открыть Настройки в дашборде (/dashboard/settings) после входа в аккаунт.
• Изменить параметры интерфейса (заголовок, цвета и др.), если это разрешено тарифом и ролью.
• Настроить параметры UDP и QUIC/DTLS, когда соответствующие возможности доступны в продукте и на тарифе.
• Включить или отключить опции, связанные с аудитом, если функция доступна.
• Экспортировать текущую конфигурацию в JSON для резервного копирования или переноса на другую среду.
• Импортировать ранее сохранённый JSON через форму в разделе настроек.
• Увидеть заблокированные разделы на бесплатном тарифе и перейти к смене плана из подсказки в интерфейсе.
• Администратор сохраняет глобальные параметры, влияющие на отображение и поведение панели, через те же экраны и API настроек.

Как это реализовано в сервисе

Пользователь работает в дашборде: форма отправляет изменения на сервер, который проверяет сессию, роль и права по тарифу, затем применяет допустимые параметры к конфигурации интерфейса и транспорта. Экспорт отдаёт снимок текущих настроек; импорт разбирает JSON и обновляет только разрешённые поля. Изменения вступают в силу без перезапуска клиента туннеля; для части параметров может потребоваться обновление страницы или повторный вход.

Справочник API

Публичные маршруты настроек дашборда. Для изменяющих запросов требуется активная сессия; в текущей версии сохранение глобальных параметров доступно администратору.

Сохранение настроек

POST /ui/settings

• Назначение: обновить параметры интерфейса, транспорта и связанных опций из формы дашборда.
• Авторизация: сессия; без прав администратора — 403 Forbidden.
• Успех: перенаправление обратно на страницу настроек.

Экспорт

GET /ui/settings/export

• Назначение: скачать JSON с текущей конфигурацией.
• Авторизация: сессия администратора.
• Успех: файл ui-config.json (или аналогичное имя, заданное клиентом).

Импорт

POST /ui/settings/import

• Назначение: загрузить JSON конфигурации (форма multipart или тело с полезной нагрузкой по контракту интерфейса).
• Авторизация: сессия администратора.
• Успех: перенаправление на страницу настроек с применёнными полями.