# Постоянные данные и хранилище

В Just Run есть два независимых способа хранить постоянные данные. Корневая файловая система принадлежит одной песочнице и подходит для рабочего дерева и установленных инструментов. Хранилище аккаунта — это опциональное объектное хранилище с явной выдачей доступа; оно подходит для артефактов, которые должны пережить песочницу или переходить между песочницами.

## Выбор места для данных[​](#choose-where-data-belongs "Прямая ссылка на Выбор места для данных")

| Требование                                                | Корневая файловая система             | Хранилище аккаунта                          |
| --------------------------------------------------------- | ------------------------------------- | ------------------------------------------- |
| Обычные POSIX-пути, установка пакетов, рабочее дерево Git | Да                                    | Нет; это объектное хранилище «ключ → байты» |
| Переживает остановку и возобновление                      | Да                                    | Да                                          |
| Сохраняет запущенные процессы                             | Только гибернация сохраняет память VM | Хранилище не хранит процессы                |
| Доступно нескольким песочницам                            | Нет                                   | Да, внутри активного аккаунта               |
| Переживает удаление песочницы                             | Нет                                   | Да, пока не удален объект                   |
| Доступно в каждой инсталляции                             | Корневая файловая система обязательна | Нет; хранилище может быть отключено         |
| Доступ с ноутбука или CI                                  | Через API файлов песочницы            | Напрямую через `/v1/storage`                |

Храните исходный код и временное состояние сборки на корневом диске. Датасеты, веса моделей, экспорты, отчеты и промежуточные результаты конвейера кладите в хранилище, если они не должны зависеть от жизненного цикла одной песочницы.

## Жизненный цикл корневой файловой системы[​](#root-filesystem-lifecycle "Прямая ссылка на Жизненный цикл корневой файловой системы")

Каждая песочница начинает работу с клона файловой системы шаблона. Изменения через терминал, `/exec`, API файлов или компонент подготовки попадают на корневой диск этой песочницы.

| Действие                      | Корневая файловая система               | Процессы и память                                  |
| ----------------------------- | --------------------------------------- | -------------------------------------------------- |
| Остановка                     | Сохраняется                             | Теряются                                           |
| Возобновление после остановки | Восстанавливается при холодной загрузке | Запускаются новые процессы                         |
| Гибернация                    | Сохраняется                             | Память и состояние выполнения VM попадают в снимок |
| Пробуждение после гибернации  | Сохраняется                             | Состояние снимка восстанавливается                 |
| Удаление                      | Уничтожается                            | Уничтожаются                                       |

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

Переходы состояний описаны в [жизненном цикле песочницы](/sandboxes/lifecycle.md), а файловые операции — в разделе [Файлы и Git](/sandboxes/files-and-git.md).

## Размер корневого диска[​](#size-the-root-disk "Прямая ссылка на Размер корневого диска")

Передайте `disk_mb` при создании песочницы. Значение задается в МиБ:

```
curl --fail-with-body --silent --show-error \
  --request POST "$JUSTRUN_API/v1/sandboxes" \
  --header "Authorization: Bearer $JUSTRUN_PAT" \
  --header "Content-Type: application/json" \
  --data '{
    "template": "base",
    "disk_mb": 16384,
    "wait_until_ready": true
  }' |
  jq '{id, status, disk_mb}'
```

Итоговый размер определяется так:

* при отсутствии значения используется значение шаблона по умолчанию, затем значение инсталляции по умолчанию;
* диск не может быть меньше файловой системы, запеченной в шаблон;
* шлюз поднимает запрос как минимум до 2048 МиБ и до минимума шаблона;
* жесткий предел платформы — 65536 МиБ, но инсталляция может задать меньший;
* запрос вне диапазона приводится к эффективному минимуму или максимуму;
* диск можно увеличить только при создании, а изменить размер или уменьшить его позднее нельзя.

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

Размер диска и свободное место — не одно и то же

`disk_mb` — размер подготовленной корневой файловой системы. Часть места занимают файлы шаблона, установленные пакеты, логи и ваши данные. Проверяйте свободное место командой `df -h` внутри песочницы.

## Хранилище аккаунта[​](#use-account-storage "Прямая ссылка на Хранилище аккаунта")

Хранилище — плоское пространство ключей и байтов в пределах аккаунта. Ключи наподобие `runs/42/result.json` выглядят иерархически, но каталоги в нем являются неявными префиксами. Пользователь аутентифицируется обычным bearer-токеном. Песочница получает отдельный токен с ограниченными правами, только если вы выдаете доступ `ro` или `rw`.

Создайте песочницу с доступом на чтение и запись:

```
{
  "template": "base",
  "storage_access": "rw"
}
```

Либо выдайте, измените или отзовите доступ существующей песочницы:

```
curl --fail-with-body --silent --show-error \
  --request PATCH "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID" \
  --header "Authorization: Bearer $JUSTRUN_PAT" \
  --header "Content-Type: application/json" \
  --data '{"storage_access":"ro"}' |
  jq '{id, storage_access}'
```

Для отзыва используйте `"none"`. При выдаче доступа в окружение песочницы добавляются `JR_STORAGE_URL` и `JR_STORAGE_TOKEN`. При смене режима токен ротируется; отзыв инвалидирует старый токен и удаляет сохраненные переменные. Новые процессы видят обновленное окружение, а уже запущенный процесс сохраняет исходное.

Поддерживаемые шаблоны содержат вспомогательную утилиту `jr-storage`:

```
jr-storage usage
jr-storage put ./result.json runs/42/result.json
jr-storage get runs/42/result.json ./downloaded-result.json
jr-storage ls runs/42/
jr-storage rm runs/42/result.json
```

Режим `ro` разрешает список, метаданные, скачивание, потребление и presigned GET URL. Он запрещает загрузку, удаление и presigned PUT URL. Режим `rw` разрешает чтение и запись.

## Обращайтесь к хранилищу вне песочницы[​](#access-storage-outside-a-sandbox "Прямая ссылка на Обращайтесь к хранилищу вне песочницы")

Используйте персональный токен и REST API:

| Операция                 | Запрос                                                                |
| ------------------------ | --------------------------------------------------------------------- |
| Список ключей            | `GET /v1/storage/objects?prefix=...&delimiter=/&cursor=...&limit=...` |
| Загрузка сырых байтов    | `PUT /v1/storage/objects/{key}`                                       |
| Скачивание сырых байтов  | `GET /v1/storage/objects/{key}`                                       |
| Чтение метаданных        | `HEAD /v1/storage/objects/{key}`                                      |
| Удаление                 | `DELETE /v1/storage/objects/{key}`                                    |
| URL для прямой передачи  | `POST /v1/storage/presign`                                            |
| Проверка объектной квоты | `GET /v1/storage/usage`                                               |

Например, проверьте квоту и загрузите объект в теле запроса:

```
curl --fail-with-body --silent --show-error \
  "$JUSTRUN_API/v1/storage/usage" \
  --header "Authorization: Bearer $JUSTRUN_PAT" |
  jq '{bytes_used, pending_bytes, quota_bytes, object_count}'

curl --fail-with-body --silent --show-error \
  --request PUT "$JUSTRUN_API/v1/storage/objects/runs/42/result.json" \
  --header "Authorization: Bearer $JUSTRUN_PAT" \
  --header "Content-Type: application/json" \
  --data-binary @result.json |
  jq '{key, size, etag}'
```

Ограничения передачи в теле запроса задаются в инсталляции. Для крупных объектов запросите presigned `GET` или `PUT` URL и передавайте данные прямо в лежащее в основе объектное хранилище. Для presigned `PUT` нужен точный `content_length`; URL и срок его действия приходят в ответе.

Страница списка по умолчанию содержит 100 записей и принимает `limit` от 1 до 1000. Следуйте по непрозрачному `next_cursor`, пока он не станет `null`. Ключи объектов задаются относительно аккаунта, не могут начинаться или заканчиваться `/` и не могут содержать пустые сегменты, сегменты `.` или `..`, обратную косую черту и управляющие символы.

## Квоты и доступность[​](#quotas-and-availability "Прямая ссылка на Квоты и доступность")

Квота корневых дисков и хранилища аккаунта — разные бюджеты:

* `GET /v1/account/overview` показывает количество песочниц, vCPU, RAM и использование корневых дисков песочниц относительно лимитов аккаунта;
* `GET /v1/storage/usage` показывает байты объектов, их количество, ожидающие presigned-загрузки и квоту объектного хранилища.

Не выводите один бюджет из другого. Запись в хранилище, которая превысит `bytes_used + pending_bytes + incoming`, возвращает HTTP `429`.

Хранилище настраивается для каждой инсталляции. Когда оно отключено, маршруты `/v1/storage/*` не смонтированы и возвращают `404`, а создание песочницы отвергает `storage_access`. Веб-интерфейс показывает область хранилища, только когда возможность доступна.

## Границы безопасности и отказов[​](#security-and-failure-boundaries "Прямая ссылка на Границы безопасности и отказов")

* Считайте `JR_STORAGE_TOKEN` и presigned URL bearer-учетными данными. Не выводите их в логи, не печатайте, не коммитьте и не передавайте другим.
* Доступ к хранилищу, выданный песочнице, открывает общее пространство активного аккаунта. Используйте `ro`, если рабочая нагрузка не должна писать, и отзывайте ненужный доступ.
* Удаление файла корневого диска или объекта хранилища нельзя отменить через публичный API.
* Presigned-загрузка резервирует `pending_bytes` до сверки или истечения; незавершенная загрузка может временно уменьшить свободную квоту.
* Ошибка бэкенда хранилища может вернуть `503`. Сохраняйте локальный результат до успешной загрузки в хранилище и проверяйте важный объект через метаданные или скачивание.
* Корневая файловая система — не механизм синхронизации. Для обмена между песочницами используйте неизменяемые или версионированные ключи хранилища, а не рассчитывайте на общую POSIX-семантику.

## Связанные разделы[​](#related "Прямая ссылка на Связанные разделы")

* [Создание песочницы](/sandboxes/create-a-sandbox.md)
* [Настройка песочницы](/sandboxes/configure-a-sandbox.md)
* [Файлы и Git](/sandboxes/files-and-git.md)
* [Жизненный цикл песочницы](/sandboxes/lifecycle.md)
* [Лимиты](/sandboxes/limits.md)
* [Хранилище](/storage.md)
* [Справочник REST API](/api-reference/rest.md)
