Сеть и превью
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-маршрут и контекст аутентификации.
Публикация порта через веб-интерфейс
- Запустите приложение внутри песочницы.
- Откройте вкладку Внешний доступ песочницы.
- Нажмите Опубликовать порт.
- В форме укажите Номер порта и выберите режим в блоке Контроль доступа: Публичный, Basic, Токен или Сессия.
- При необходимости заполните Свой поддомен (необязательно).
- Нажмите Опубликовать, затем откройте сервис кнопкой Открыть. В режиме 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: проверьте поддомен и доступность маршрутизации превью в этой инсталляции.
- Первый запрос после паузы медленный или недоступен: учитывайте холодный старт, выполните безопасный повтор или явно возобновите или разбудите песочницу перед отправкой трафика.