Вернуться к документации

HTTP-тоннели через Adal CLI

Настройте тоннель, подключите Adal CLI и разберитесь с ошибками подключения и HTTP-передачи.

Открыть как Markdown
На этой странице

Как работает подключение

Отправитель обращается по публичному HTTPS-адресу тоннеля. Adal CLI вызывает указанный сервис с компьютера, на котором запущен, и передаёт HTTP-ответ обратно отправителю. Запрос и ответ могут передаваться одновременно. Локальное приложение может начать отвечать до того, как отправитель закончит загрузку запроса.

Для примера с тестовым сервисом откройте быстрый старт.

Настройки тоннеля

Настройка Поведение
Name, Notes Название и необязательная заметка в кабинете. Заметка вмещает до 4 096 символов.
Region Определяет публичный адрес и место хранения HTTP-данных. Регион выбирается при создании. Затем регион и адрес закреплены за тоннелем.
Endpoint URL Базовый HTTP- или HTTPS-адрес, доступный с компьютера с CLI. Допускаются loopback и частные адреса. Можно указать порт и путь. Укажите URL без учётных данных, query и fragment. Для HTTPS проверяется сертификат.
Enabled Разрешает запросы после подключения CLI и готовности конфигурации. Выключение или удаление тоннеля закрывает сессию и отменяет активные запросы.
Timeout (seconds) От 1 до 120 секунд на обмен. По умолчанию 30 секунд.
Concurrent requests От 1 до 64 одновременных обменов на тоннель. По умолчанию 16. При исчерпании доступных слотов запрос отклоняется сразу.
Save request, Save response Независимые настройки хранения, обе включены по умолчанию. См. HTTP-данные и скачивание.

Если Endpoint URL равен http://127.0.0.1:3000/api, то запрос по публичному пути /orders?view=summary попадёт на http://127.0.0.1:3000/api/orders?view=summary. Хост назначения и имя сервера для HTTPS берутся из Endpoint URL.

Если локальный сервис принимает POST /api/orders, проверьте тот же вызов через тоннель. Подставьте публичный адрес из карточки.

curl -i 'https://TUNNEL_ADDRESS.se.adal.cloud/orders?view=summary' \ -H 'Content-Type: application/json' --data '{"event":"demo"}'
$body = @{ event = 'demo' } | ConvertTo-Json -Compress Invoke-WebRequest -Uri 'https://TUNNEL_ADDRESS.se.adal.cloud/orders?view=summary' -Method Post -ContentType 'application/json' -Body $body

Отправитель получает HTTP-код, заголовки и тело ответа в том же запросе.

Команды CLI и токен

В разделе Tunnels откройте карточку тоннеля, выберите CLI token и выпустите токен. Доступны 30, 60 и 90 суток или календарная дата окончания в UTC. Сохраните секрет при выпуске. Замена или отзыв прекращают его действие. После замены запустите CLI с новым токеном.

./adal-cli --token '<TUNNEL_TOKEN>' ./adal-cli --host wss://cli.adal.cloud --token '<TUNNEL_TOKEN>' ./adal-cli --help
.\adal-cli.exe --token '<TUNNEL_TOKEN>' .\adal-cli.exe --host wss://cli.adal.cloud --token '<TUNNEL_TOKEN>' .\adal-cli.exe --help

Адрес подключения по умолчанию — wss://cli.adal.cloud. Необязательный --host имеет приоритет над переменной ADAL_API_HOST. Указывайте WSS-адрес без пути, query и учётных данных. Режим определяется токеном. Токен Канала подключает доставку Inbound.

Ограничения HTTP и трафика

  • Тело запроса и тело ответа ограничены 128 МиБ каждое. Региональный обработчик ограничивает заголовки запроса 64 КиБ, а путь вместе с query — 16 КиБ. Превышение лимита тела после начала передачи может оборвать обмен.

  • Запрос и ответ передаются потоком в обе стороны. WebSocket Upgrade и HTTP CONNECT не поддерживаются. CLI передаёт HTTP-код приложения, включая перенаправления и ответы 4xx и 5xx. CLI не следует перенаправлениям.

  • У тоннеля нет очереди доставок, автоматического повтора HTTP и повторного воспроизведения. При разрыве соединения активные обмены отменяются. После временных сбоев клиент переподключается. После выключения и включения тоннеля запустите CLI вручную.

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

Логи и ошибки

Проверяйте ошибки подключения CLI в терминале. HTTP-код и результат передачи смотрите в журнале запросов. Храните токен в тайне. В журнале можно отличить ответ Ендпоинта от ответа платформы.

Симптом Что проверить
CLI не подключается Проверьте версию CLI, токен тоннеля, срок действия, состояние тоннеля и доступ к wss://cli.adal.cloud. После повторного включения запустите клиент заново.
404 tunnel_not_found Скопируйте полный публичный адрес из карточки. Проверьте регион и наличие тоннеля.
403 quota_exhausted или access_disabled Проверьте остаток трафика и доступ аккаунта.
503 tunnel_disabled, tunnel_not_ready или quota_unavailable Проверьте Enabled, обновите карточку и убедитесь, что CLI подключён. Если ошибка относится к квоте, проверьте доступность остатка.
503 concurrency_limit_exceeded или service_overloaded Проверьте Concurrent requests и уменьшите число одновременных вызовов.
502 endpoint_unavailable Вызовите Ендпоинт напрямую с компьютера с CLI. Проверьте приложение, порт и TLS-сертификат.
502 cli_unavailable или tunnel_transport_error Проверьте подключение CLI и результат передачи в журнале.
400 invalid_request Проверьте HTTP-запрос и его адрес.
500 internal_error Для диагностики запишите время и ID запроса, если он доступен.
504 request_timeout Проверьте скорость приложения и Timeout (seconds). Если передача ответа уже началась, она может оборваться.
413, 414, 431, 417 или 501 Проверьте соответственно размер тела, длину пути с query, размер заголовков, заголовок Expect либо использование CONNECT и Upgrade.

См. журнал и статусы и HTTP-данные и скачивание.

Связанная документация