# Сеть и превью

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

## Как трафик попадает в сервис[​](#how-traffic-reaches-your-service "Прямая ссылка на Как трафик попадает в сервис")

```
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-маршрут и контекст аутентификации.

## Публикация порта через веб-интерфейс[​](#expose-a-port-in-the-web-ui "Прямая ссылка на Публикация порта через веб-интерфейс")

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

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

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

## Выбор контроля доступа[​](#choose-access-control "Прямая ссылка на Выбор контроля доступа")

| `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[​](#expose-a-port-through-rest "Прямая ссылка на Публикация порта через 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`.

## Управление именем хоста[​](#control-the-hostname "Прямая ссылка на Управление именем хоста")

Без `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-a-port-during-creation "Прямая ссылка на Публикация порта при создании")

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

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

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

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

## Поведение в жизненном цикле[​](#lifecycle-behavior "Прямая ссылка на Поведение в жизненном цикле")

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

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

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

## Устранение проблем[​](#troubleshooting "Прямая ссылка на Устранение проблем")

* **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:** проверьте поддомен и доступность маршрутизации превью в этой инсталляции.
* **Первый запрос после паузы медленный или недоступен:** учитывайте холодный старт, выполните безопасный повтор или явно возобновите или разбудите песочницу перед отправкой трафика.

## См. также[​](#related "Прямая ссылка на См. также")

* [Команды, процессы и терминалы](/sandboxes/commands-processes-and-terminals.md)
* [Настройка песочницы](/sandboxes/configure-a-sandbox.md)
* [Жизненный цикл песочницы](/sandboxes/lifecycle.md)
* [Безопасность](/sandboxes/security)
* [Справочник REST API](/api-reference/rest.md)
* [Наблюдаемость и диагностика](/sandboxes/observability-and-troubleshooting.md)
