Интеграция с ngrok

ngrok -- популярный сервис туннелирования, создающий защищённый входящий доступ к вашему локальному экземпляру PRX. Это самый быстрый способ начать работу с вебхуками и внешними интеграциями -- одна команда даёт публичный HTTPS URL, указывающий на вашего локального агента.

Обзор

ngrok лучше всего подходит для:

• Разработки и тестирования -- получите публичный URL за секунды без настройки аккаунта
• Прототипирования вебхуков -- быстрое тестирование интеграций Telegram, Discord, GitHub или Slack
• Демонстраций и презентаций -- поделитесь временным публичным URL для показа вашего агента
• Сред, где Cloudflare или Tailscale недоступны

Для продакшн-развёртываний рассмотрите Cloudflare Tunnel или Tailscale Funnel, которые предлагают лучшую надёжность, собственные домены и средства контроля доступа с нулевым доверием.

Предварительные требования

1. CLI ngrok, установленный на машине с PRX
2. Аккаунт ngrok с токеном авторизации (достаточно бесплатного плана)

Установка ngrok

# Debian / Ubuntu (via snap)
sudo snap install ngrok

# macOS
brew install ngrok

# Binary download (all platforms)
# https://ngrok.com/download

# Authenticate (one-time setup)
ngrok config add-authtoken <YOUR_AUTH_TOKEN>

Получите токен авторизации в панели управления ngrok.

Конфигурация

Базовая настройка

[tunnel]
backend = "ngrok"
local_addr = "127.0.0.1:8080"

[tunnel.ngrok]
# Auth token. Can also be set via NGROK_AUTHTOKEN environment variable.
# If omitted, ngrok uses the token from its local config file.
authtoken = ""

# Region for the tunnel endpoint.
# Options: "us", "eu", "ap", "au", "sa", "jp", "in"
region = "us"

Собственный домен (платные планы)

Платные планы ngrok поддерживают постоянные собственные домены:

[tunnel]
backend = "ngrok"
local_addr = "127.0.0.1:8080"

[tunnel.ngrok]
authtoken = "${NGROK_AUTHTOKEN}"

# Custom domain (requires ngrok paid plan)
domain = "agent.example.com"

# Alternatively, use a static ngrok subdomain (free on some plans)
# subdomain = "my-prx-agent"

Зарезервированный домен

Для стабильных URL на бесплатном плане ngrok предлагает зарезервированные домены:

[tunnel.ngrok]
authtoken = "${NGROK_AUTHTOKEN}"

# Reserved domain assigned by ngrok (e.g., "example-agent.ngrok-free.app")
domain = "example-agent.ngrok-free.app"

Справочник конфигурации

Параметр	Тип	По умолчанию	Описание
authtoken	string	--	Токен аутентификации ngrok
region	string	"us"	Регион туннеля: "us", "eu", "ap", "au", "sa", "jp", "in"
domain	string	--	Собственный домен или зарезервированный домен (платная функция)
subdomain	string	--	Фиксированный поддомен на ngrok-free.app
ngrok_path	string	"ngrok"	Путь к бинарнику ngrok
inspect	boolean	true	Включить панель инспекции ngrok (localhost:4040)
log_level	string	"info"	Уровень журнала ngrok: "debug", "info", "warn", "error"
metadata	string	--	Произвольная строка метаданных, прикрепляемая к сессии туннеля
basic_auth	string	--	HTTP Basic Auth в формате user:password
ip_restrictions	list	[]	Список разрешённых CIDR-диапазонов (напр., ["203.0.113.0/24"])
circuit_breaker	float	--	Порог частоты ошибок (0.0-1.0) для срабатывания автоматического выключателя
compression	boolean	false	Включить сжатие ответов

Как PRX управляет ngrok

При запуске туннеля PRX запускает ngrok как дочерний процесс:

ngrok http 127.0.0.1:8080 \
  --authtoken=<token> \
  --region=us \
  --log=stdout \
  --log-format=json

Затем PRX запрашивает локальный API ngrok (http://127.0.0.1:4040/api/tunnels) для получения назначенного публичного URL. Этот URL сохраняется и используется для регистрации вебхуков и конфигурации каналов.

Извлечение URL

ngrok предоставляет локальный API на порту 4040. PRX опрашивает этот эндпоинт с таймаутом:

GET http://localhost:4040/api/tunnels

Ответ содержит публичный URL:

{
  "tunnels": [
    {
      "public_url": "https://abc123.ngrok-free.app",
      "config": {
        "addr": "http://localhost:8080"
      }
    }
  ]
}

Если API недоступен в пределах startup_timeout_secs, PRX переключается на парсинг stdout для получения URL.

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

Бесплатный план ngrok имеет ряд ограничений, которые следует учитывать:

Ограничение	Бесплатный план	Влияние на PRX
Параллельные туннели	1	Только один экземпляр PRX на аккаунт ngrok
Соединений в минуту	40	Может ограничивать высоконагруженные вебхуки
Собственные домены	Недоступны	URL меняется при каждом перезапуске
Ограничения по IP	Недоступны	Невозможно ограничить исходные IP
Пропускная способность	Ограничена	Передача больших файлов может замедляться
Промежуточная страница	Показывается при первом посещении	Может мешать некоторым провайдерам вебхуков

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

Панель инспекции ngrok

При inspect = true (по умолчанию) ngrok запускает локальную веб-панель по адресу http://localhost:4040. Эта панель предоставляет:

• Инспектор запросов -- просмотр всех входящих запросов с заголовками, телом и ответом
• Воспроизведение -- повторная отправка любого запроса для отладки
• Статус туннеля -- состояние соединения, регион и публичный URL

Это незаменимо для отладки интеграций вебхуков при разработке.

Замечания по безопасности

• Защита токена авторизации -- токен авторизации ngrok предоставляет доступ к созданию туннелей в вашем аккаунте. Храните его в менеджере секретов PRX или передавайте через переменную окружения NGROK_AUTHTOKEN.
• URL бесплатного плана публичны -- любой, у кого есть URL, может связаться с вашим агентом. Используйте basic_auth или ip_restrictions (платно) для ограничения доступа.
• Ротация URL -- URL бесплатного плана меняются при перезапуске. Если провайдеры вебхуков кэшируют старый URL, доставка событий прекратится. Используйте зарезервированные домены или другой бэкенд для стабильных URL.
• Терминация TLS -- ngrok терминирует TLS на своём граничном узле. Трафик между ngrok и вашим локальным PRX проходит через инфраструктуру ngrok.
• Инспекция данных -- панель инспекции ngrok показывает тела запросов/ответов. Отключите её в продакшне с помощью inspect = false, если передаются конфиденциальные данные.

Паттерн интеграции вебхуков

Типичный паттерн для разработки: запустить PRX с ngrok, зарегистрировать URL вебхука и тестировать:

# 1. Start PRX (tunnel starts automatically)
prx start

# 2. PRX logs the public URL
# [INFO] Tunnel started: https://abc123.ngrok-free.app

# 3. Register the webhook URL with your service
# Telegram: https://abc123.ngrok-free.app/webhook/telegram
# GitHub:   https://abc123.ngrok-free.app/webhook/github

# 4. Inspect requests at http://localhost:4040

Сравнение с другими бэкендами

Функция	ngrok	Cloudflare Tunnel	Tailscale Funnel
Время настройки	Секунды	Минуты	Минуты
Собственный домен	Платно	Бесплатно (с зоной)	Только MagicDNS
Zero-trust	Нет	Да (Access)	Да (ACL)
Бесплатный план	Да (ограниченно)	Да	Да (личный)
Панель инспекции	Да	Нет	Нет
Готовность к продакшну	Платные планы	Да	Да

Устранение неполадок

Симптом	Причина	Решение
"authentication failed"	Неверный или отсутствующий токен авторизации	Выполните ngrok config add-authtoken <token>
URL не обнаружен	API ngrok не отвечает на :4040	Проверьте, что порт 4040 не занят другим процессом
"tunnel session limit"	Бесплатный план допускает 1 туннель	Остановите другие сессии ngrok или обновите план
Вебхуки возвращают 502	Шлюз PRX не прослушивает	Убедитесь, что local_addr совпадает с адресом вашего шлюза
Показывается промежуточная страница	Предупреждение браузера бесплатного плана	Используйте --domain или обновите до платного плана
Случайные отключения	Ограничения соединений бесплатного плана	Обновите план или переключитесь на Cloudflare/Tailscale

Связанные страницы

• Обзор туннелей
• Cloudflare Tunnel
• Tailscale Funnel
• Обзор безопасности