Постоянные данные и хранилище
В Just Run есть два независимых способа хранить постоянные данные. Корневая файловая система принадлежит одной песочнице и подходит для рабочего дерева и установленных инструментов. Хранилище аккаунта — это опциональное объектное хранилище с явной выдачей доступа; оно подходит для артефактов, которые должны пережить песочницу или переходить между песочницами.
Выбор места для данных
| Требование | Корневая файловая система | Хранилище аккаунта |
|---|---|---|
| Обычные POSIX-пути, установка пакетов, рабочее дерево Git | Да | Нет; это объектное хранилище «ключ → байты» |
| Переживает остановку и возобновление | Да | Да |
| Сохраняет запущенные процессы | Только гибернация сохраняет память VM | Хранилище не хранит процессы |
| Доступно нескольким песочницам | Нет | Да, внутри активного аккаунта |
| Переживает удаление песочницы | Нет | Да, пока не удален объект |
| Доступно в каждой инсталляции | Корневая файловая система обязательна | Нет; хранилище может быть отключено |
| Доступ с ноутбука или CI | Через API файлов песочницы | Напрямую через /v1/storage |
Храните исходный код и временное состояние сборки на корневом диске. Датасеты, веса моделей, экспорты, отчеты и промежуточные результаты конвейера кладите в хранилище, если они не должны зависеть от жизненного цикла одной песочницы.
Жизненный цикл корневой файловой системы
Каждая песочница начинает работу с клона файловой системы шаблона. Изменения
через терминал, /exec, API файлов или компонент подготовки попадают на корневой диск
этой песочницы.
| Действие | Корневая файловая система | Процессы и память |
|---|---|---|
| Остановка | Сохраняется | Теряются |
| Возобновление после остановки | Восстанавливается при холодной загрузке | Запускаются новые процессы |
| Гибернация | Сохраняется | Память и состояние выполнения VM попадают в снимок |
| Пробуждение после гибернации | Сохраняется | Состояние снимка восстанавливается |
| Удаление | Уничтожается | Уничтожаются |
У удаления нет публичной операции отмены или восстановления. Экспортируйте ценные результаты до удаления песочницы. Сохранение песочницы как шаблона полезно, когда вся настроенная файловая система должна стать переиспользуемой отправной точкой; для независимых объектов данных лучше подходит хранилище.
Переходы состояний описаны в жизненном цикле песочницы, а файловые операции — в разделе Файлы и Git.
Размер корневого диска
Передайте 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 внутри песочницы.
Хранилище аккаунта
Хранилище — плоское пространство ключей и байтов в пределах аккаунта. Ключи наподобие
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 разрешает чтение и
запись.
Обращайтесь к хранилищу вне песочницы
Используйте персональный токен и 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. Ключи объектов
задаются относительно аккаунта, не могут начинаться или заканчиваться / и не
могут содержать пустые сегменты, сегменты . или .., обратную косую черту и
управляющие символы.
Квоты и доступность
Квота корневых дисков и хранилища аккаунта — разные бюджеты:
GET /v1/account/overviewпоказывает количество песочниц, vCPU, RAM и использование корневых дисков песочниц относительно лимитов аккаунта;GET /v1/storage/usageпоказывает байты объектов, их количество, ожидающие presigned-загрузки и квоту объектного хранилища.
Не выводите один бюджет из другого. Запись в хранилище, которая превысит
bytes_used + pending_bytes + incoming, возвращает HTTP 429.
Хранилище настраивается для каждой инсталляции. Когда оно отключено, маршруты
/v1/storage/* не смонтированы и возвращают 404, а создание песочницы отвергает
storage_access. Веб-интерфейс показывает область хранилища, только когда возможность
доступна.
Границы безопасности и отказов
- Считайте
JR_STORAGE_TOKENи presigned URL bearer-учетными данными. Не выводите их в логи, не печатайте, не коммитьте и не передавайте другим. - Доступ к хранилищу, выданный песочнице, открывает общее пространство активного
аккаунта. Используйте
ro, если рабочая нагрузка не должна писать, и отзывайте ненужный доступ. - Удаление файла корневого диска или объекта хранилища нельзя отменить через публичный API.
- Presigned-загрузка резервирует
pending_bytesдо сверки или истечения; незавершенная загрузка может временно уменьшить свободную квоту. - Ошибка бэкенда хранилища может вернуть
503. Сохраняйте локальный результат до успешной загрузки в хранилище и проверяйте важный объект через метаданные или скачивание. - Корневая файловая система — не механизм синхронизации. Для обмена между песочницами используйте неизменяемые или версионированные ключи хранилища, а не рассчитывайте на общую POSIX-семантику.