Перейти к основному содержимому
Открыть Markdown

Сеть и превью

URL превью публикует один HTTP-порт песочницы через граничный сервис платформы. URL использует HTTPS, может быть защищен независимо от API песочницы и доступен из веб-интерфейса или другого HTTP-клиента.

Как трафик попадает в сервис​

client
→ HTTPS preview URL
→ preview access control
→ network address sandbox и exposed port
→ ваш HTTP-сервис

Сервис можно запустить до или после публикации порта. Он должен слушать указанный порт на сетевом интерфейсе песочницы, доступном снаружи гостевой системы; обычно используют 0.0.0.0. Процесс, слушающий только 127.0.0.1, недоступен через маршрут превью.

URL превью публикуют HTTP-приложения, а не произвольное перенаправление входящего TCP- или UDP-трафика. WebSocket-соединения используют тот же HTTP-маршрут и контекст аутентификации.

Публикация порта через веб-интерфейс​

  1. Запустите приложение внутри песочницы.
  2. Откройте вкладку Внешний доступ песочницы.
  3. Нажмите Опубликовать порт.
  4. В форме укажите Номер порта и выберите режим в блоке Контроль доступа: Публичный, Basic, Токен или Сессия.
  5. При необходимости заполните Свой поддомен (необязательно).
  6. Нажмите Опубликовать, затем откройте сервис кнопкой Открыть. В режиме IDE у порта также есть кнопки Предпросмотр здесь и Новая вкладка.

Панель предпросмотра проверяет доступность и встраивает приложение, если заголовки ответа разрешают встраивание во фрейм. Приложение может работать в новой вкладке, но запрещать встраивание через X-Frame-Options или Content Security Policy.

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

Выбор контроля доступа​

auth.typeКто может открыть URLКогда использовать
noneЛюбой, кто знает URLКонтент намеренно публичный
internalВладелец песочницы или участник ее организации: браузер — по одноразовой ссылке из веб-интерфейса, API-клиент — с Authorization: BearerПревью предназначено для вошедших пользователей рабочего пространства
basicКлиент с заданными именем пользователя и паролемНужен простой внешний вход через браузер
bearerКлиент, отправляющий настроенный bearer-токенПревью вызывает сервис или интеграция

none означает публичный доступ из интернета. Трудно угадываемый поддомен не является границей авторизации.

Для bearer-доступа передавайте Authorization: Bearer <token>. Не сохраняйте токен в системе контроля версий или логах. Пароли Basic хранятся в виде хешей для проверки на граничном сервисе, но все равно требуют безопасной передачи и ротации.

internal лучше всего подходит для браузерных превью внутри продукта. На хосте превью работает код из песочницы, поэтому сессия веб-интерфейса туда не попадает: ее cookie привязан только к хосту веб-интерфейса, а хосты превью не принимают ни его, ни ?access_token=. Веб-интерфейс открывает internal-превью в новой вкладке по одноразовой ссылке (POST /v1/preview-tickets, действует 30 секунд). Шлюз проверяет ссылку раньше, чем запрос попадет в код из песочницы, и ставит cookie justrun-preview только на этот хост, поэтому вложенные ресурсы страницы и WebSocket-соединения тоже проходят аутентификацию. Пока вкладкой пользуются, cookie продлевается, но действует не дольше 8 часов с момента открытия ссылки (значение по умолчанию). Во встроенном превью веб-интерфейса internal-превью не открываются. Путь /_justrun/ на хостах превью зарезервирован платформой.

Свои cookie приложение ставит как обычно. Атрибут Domain, указывающий не на сам хост превью, снимается, чтобы одно превью не могло подменять cookie соседних. Cookie с именами justrun-session и justrun-preview приложение поставить не может.

Публикация порта через REST​

POST /v1/sandboxes/{id}/ports создает маршрут и возвращает HTTP 201:

curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/ports" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--data '{
"port": 8080,
"subdomain": "acme-preview",
"auth": {"type": "internal"},
"path": "/health"
}' |
jq

Ответ содержит port, url, auth_type, необязательные метаданные для отображения, last_active_at и requests_total. Необязательный path добавляется к возвращаемому URL; маршрутизация все равно направляет весь трафик на опубликованный порт и не ограничивает запросы этим путем.

Получить список маршрутов или удалить один из них:

curl --fail-with-body --silent --show-error \
"$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/ports" \
--header "Authorization: Bearer $JUSTRUN_PAT" |
jq

curl --fail-with-body --silent --show-error \
--request DELETE "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/ports/8080" \
--header "Authorization: Bearer $JUSTRUN_PAT"

Один порт можно опубликовать в песочнице только один раз. Повтор возвращает HTTP 409. Порт 0 недопустим. Маршрутизация превью должна быть включена в инсталляции; если она не настроена, публикация возвращает HTTP 400.

Управление именем хоста​

Без subdomain платформа генерирует случайную неугадываемую метку из 16 символов (base32 строчными буквами) и добавляет порт — например, k7m2q4x9p3w6r8t5-8080. Метка никогда не строится из имени песочницы, поэтому всегда используйте url из ответа, а не собирайте хост вручную. Чтобы перевести порт на новый адрес, удалите публикацию и создайте заново — будет сгенерирована новая метка.

Явно заданный subdomain по умолчанию создает метку без суффикса порта:

{
"port": 8080,
"subdomain": "acme-preview"
}

Получится хост вида acme-preview.<preview-domain>. Укажите "omit_port_suffix": false, чтобы сохранить acme-preview-8080.<preview-domain>.

Собственный поддомен может содержать только строчные буквы ASCII, цифры и дефисы, не может начинаться или заканчиваться дефисом и ограничен 48 символами. Итоговая метка хоста глобально уникальна, поэтому конфликт имен возвращает HTTP 400. Базовый домен превью зависит от инсталляции: используйте url из ответа API, а не собирайте его самостоятельно.

Публикация порта при создании​

Используйте expose_ports, когда сервис и маршрут превью являются частью определения песочницы:

{
"template": "base",
"expose_ports": [
{
"port": 8080,
"name": "Web app",
"auth": {"type": "internal"},
"path": "/"
}
]
}

Запись при создании также принимает name, note и required. Обычная публикация превью по умолчанию выполняется без гарантий: ошибка маршрута возвращается как предупреждение при создании. Если без маршрута песочница бесполезна, задайте required: true; тогда ошибка публикации завершит создание ошибкой и удалит создаваемую песочницу.

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

Поведение в жизненном цикле​

Запись опубликованного порта сохраняется при остановке, возобновлении, гибернации и пробуждении. Активные маршруты восстанавливаются после возврата песочницы в running.

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

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

Устранение проблем​

  • URL возвращает 502, 503 или 504: убедитесь, что песочница находится в running, а сервис слушает опубликованный порт. Повторите запрос после загрузки.
  • Сервис работает на localhost, но не через URL: слушайте 0.0.0.0 или другой доступный сетевой интерфейс песочницы.
  • Встроенное превью пусто или заблокировано: откройте его в новой вкладке и проверьте X-Frame-Options и Content-Security-Policy приложения.
  • URL возвращает 401 или 403: используйте учетные данные, соответствующие auth_type; для internal откройте превью из веб-интерфейса заново (одноразовая ссылка и сессия превью истекают) или передайте из API-клиента Authorization: Bearer с токеном платформы.
  • Публикация возвращает 400: проверьте поддомен и доступность маршрутизации превью в этой инсталляции.
  • Первый запрос после паузы медленный или недоступен: учитывайте холодный старт, выполните безопасный повтор или явно возобновите или разбудите песочницу перед отправкой трафика.