# Хранилище

Хранилище — это объектное хранилище на уровне аккаунта для долговечных файлов и артефактов. Загрузите байты под ключом, а затем получите объект через веб-интерфейс, API-клиент или авторизованную песочницу. Объекты принадлежат аккаунту, а не отдельной песочнице, поэтому остаются доступными после остановки или удаления песочницы.

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

## Возможности[​](#what-you-can-do "Прямая ссылка на Возможности")

* Просматривать объекты по префиксу, их размер и метаданные.
* Загружать и скачивать через веб-интерфейс или REST API.
* Передавать крупные объекты напрямую по короткоживущему presigned URL.
* Выдавать песочнице доступ к хранилищу ее аккаунта на чтение или на чтение и запись.
* Смотреть актуальное потребление в байтах, число объектов, незавершенные загрузки и квоту аккаунта.
* Перезаписывать или удалять отдельные ключи и строить политику хранения на уровне приложения.

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

## Выбор интерфейса[​](#choose-an-interface "Прямая ссылка на Выбор интерфейса")

| Интерфейс                          | Для чего подходит                                                                  | Важная граница                                                                          |
| ---------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Веб-интерфейс                      | Навигация по префиксам и передача отдельных локальных файлов                       | Показывает папки, но это неявные префиксы ключей                                        |
| REST API                           | Полный список, метаданные, потребление, передача через шлюз, перезапись и удаление | Обходите страницы списка и кодируйте процентным кодированием сегменты пути в ключе      |
| Presigned URL                      | Прямая загрузка или скачивание без передачи байтов через шлюз                      | URL дает временный bearer-доступ                                                        |
| `jr-storage` в песочнице           | Публикация или получение артефактов из рабочей нагрузки                            | Требует явного доступа `ro` или `rw`, выданного песочнице на весь аккаунт               |
| MCP `storage_list` и `storage_get` | Поиск ключей и метаданных объектов агентом                                         | Инструменты только для чтения метаданных; для байтов используйте REST или presigned URL |

Веб-интерфейс и обычные аутентифицированные API-клиенты работают в контексте активного аккаунта. Песочница получает отдельные `JR_STORAGE_URL` и `JR_STORAGE_TOKEN`, только если ей выдан доступ к хранилищу.

## Ментальная модель[​](#mental-model "Прямая ссылка на Ментальная модель")

Хранилище — это плоское отображение:

```
account + key → object bytes
```

Ключ `runs/run-42/results/summary.json` выглядит в веб-интерфейсе как вложенные папки, но `/` только группирует строковые префиксы. Ресурсов-каталогов, пустых папок, рекурсивного удаления и правил доступа по префиксам нет.

Аутентифицированный аккаунт становится внутренним префиксом в лежащем в основе хранилище. API и интерфейс возвращают только ключи относительно аккаунта, а один аккаунт не может обратиться к другому, записав его ID в ключ.

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

## Типичный путь артефакта[​](#a-typical-artifact-flow "Прямая ссылка на Типичный путь артефакта")

1. Выберите стабильный версионированный ключ и не помещайте в его имя секреты или персональные данные.
2. Для небольшого объекта используйте загрузку в теле запроса, для прямой передачи — presigned PUT.
3. Проверьте сохраненный размер и контрольную сумму на уровне приложения.
4. Выдайте песочницам-потребителям доступ `ro`, если им нужно только чтение.
5. Перед крупными записями запросите `/v1/storage/usage` и учитывайте незавершенные загрузки при расчете доступного места.
6. Удаляйте временные объекты по одному после проверки всех необходимых копий.

Объекты, скачанные в песочницу, кэш CI или на компьютер разработчика, становятся независимыми копиями. Отзыв доступа к хранилищу или удаление объекта аккаунта не стирает эти копии.

## Хранилище — не диск песочницы[​](#storage-is-not-a-sandbox-disk "Прямая ссылка на Хранилище — не диск песочницы")

| Файловая система песочницы                                       | Хранилище аккаунта                                                        |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------- |
| POSIX-файлы одной песочницы                                      | Объекты «ключ → байты», общие для аккаунта                                |
| Используется командами и процессами напрямую                     | Доступно через интерфейс, REST, presigned URL или вспомогательную утилиту |
| Сохраняется или удаляется по правилам жизненного цикла песочницы | Не зависит от остановки, гибернации и удаления песочницы                  |
| Ограничена размером диска песочницы                              | Ограничено отдельной байтовой квотой хранилища                            |

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

Хранилище также не предназначено для [секретов](/secrets.md). Имена и содержимое объектов не обрабатываются как секреты только потому, что приложение считает их учетными данными.

## Владение данными и жизненный цикл[​](#data-ownership-and-lifecycle "Прямая ссылка на Владение данными и жизненный цикл")

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

Для важных данных используйте манифесты, контрольные суммы, версионированные ключи и проверенный процесс очистки. Перед хранением чувствительного или регулируемого контента прочитайте [Безопасность и жизненный цикл данных](/storage/security-and-data-lifecycle.md).

## Подробнее о хранилище[​](#explore-storage "Прямая ссылка на Подробнее о хранилище")

* [Объекты и ключи](/storage/objects-and-keys.md) — правила именования, префиксы, метаданные и пагинация по курсору.
* [Доступ к хранилищу из песочницы](/storage/access-from-sandboxes.md) — выдача, проверка, ротация и отзыв доступа в режимах `ro` или `rw`.
* [Загрузка и скачивание](/storage/upload-and-download.md) — веб-интерфейс, REST через шлюз, передача по presigned URL, проверка и очистка.
* [Квоты и потребление](/storage/quotas-and-usage.md) — текущее потребление, незавершенные загрузки, сверка и освобождение места.
* [Безопасность и жизненный цикл данных](/storage/security-and-data-lifecycle.md) — учетные данные, хранение, удаление, границы аудита и реагирование на инциденты.
* [Справочник REST API](/api-reference/rest.md) и [справочник MCP](/api-reference/mcp.md) — публичные контракты запросов и ответов и инструменты агента.
