Хранилище
Хранилище — это объектное хранилище на уровне аккаунта для долговечных файлов и артефактов. Загрузите байты под ключом, а затем получите объект через веб-интерфейс, API-клиент или авторизованную песочницу. Объекты принадлежат аккаунту, а не отдельной песочнице, поэтому остаются доступными после остановки или удаления песочницы.
Используйте хранилище для результатов сборки, датасетов, артефактов моделей, отчетов и других файлов, которые должны передаваться между рабочими нагрузками или жить дольше песочницы.
Возможности
- Просматривать объекты по префиксу, их размер и метаданные.
- Загружать и скачивать через веб-интерфейс или REST API.
- Передавать крупные объекты напрямую по короткоживущему presigned URL.
- Выдавать песочнице доступ к хранилищу ее аккаунта на чтение или на чтение и запись.
- Смотреть актуальное потребление в байтах, число объектов, незавершенные загрузки и квоту аккаунта.
- Перезаписывать или удалять отдельные ключи и строить политику хранения на уровне приложения.
Хранилище может быть отключено в инсталляции. Когда оно недоступно,
/v1/storage/* не смонтирован, а песочнице нельзя выдать доступ к хранилищу.
Выбор интерфейса
| Интерфейс | Для чего подходит | Важная граница |
|---|---|---|
| Веб-интерфейс | Навигация по префиксам и передача отдельных локальных файлов | Показывает папки, но это неявные префиксы ключей |
| 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, только если ей выдан доступ к хранилищу.
Ментальная модель
Хранилище — это плоское отображение:
account + key → object bytes
Ключ runs/run-42/results/summary.json выглядит в веб-интерфейсе как вложенные
папки, но / только группирует строковые префиксы. Ресурсов-каталогов, пустых
папок, рекурсивного удаления и правил доступа по префиксам нет.
Аутентифицированный аккаунт становится внутренним префиксом в лежащем в основе хранилище. API и интерфейс возвращают только ключи относительно аккаунта, а один аккаунт не может обратиться к другому, записав его ID в ключ.
Загрузка в существующий ключ заменяет его байты. Предпочитайте версионированные или сгенерированные ключи, если результаты должны быть воспроизводимыми или несколько пишущих клиентов могут публиковать одновременно.
Типичный путь артефакта
- Выберите стабильный версионированный ключ и не помещайте в его имя секреты или персональные данные.
- Для небольшого объекта используйте загрузку в теле запроса, для прямой передачи — presigned PUT.
- Проверьте сохраненный размер и контрольную сумму на уровне приложения.
- Выдайте песочницам-потребителям доступ
ro, если им нужно только чтение. - Перед крупными записями запросите
/v1/storage/usageи учитывайте незавершенные загрузки при расчете доступного места. - Удаляйте временные объекты по одному после проверки всех необходимых копий.
Объекты, скачанные в песочницу, кэш CI или на компьютер разработчика, становятся независимыми копиями. Отзыв доступа к хранилищу или удаление объекта аккаунта не стирает эти копии.
Хранилище — не диск песочницы
| Файловая система песочницы | Хранилище аккаунта |
|---|---|
| POSIX-файлы одной песочницы | Объекты «ключ → байты», общие для аккаунта |
| Используется командами и процессами напрямую | Доступно через интерфейс, REST, presigned URL или вспомогательную утилиту |
| Сохраняется или удаляется по правилам жизненного цикла песочницы | Не зависит от остановки, гибернации и удаления песочницы |
| Ограничена размером диска песочницы | Ограничено отдельной байтовой квотой хранилища |
Используйте файловую систему песочницы для рабочих деревьев, установленных пакетов, сокетов и файловых операций на месте. Хранилище подходит для обмена и долговечных артефактов аккаунта. Копирование файла между ними расходует место с обеих сторон, пока одна копия не удалена.
Хранилище также не предназначено для секретов. Имена и содержимое объектов не обрабатываются как секреты только потому, что приложение считает их учетными данными.
Владение данными и жизненный цикл
Публичный API предоставляет явные перезапись и удаление, но не автоматический срок жизни объектов, версии, восстановление, юридическое удержание или рекурсивную очистку. Шифрование при хранении, резервные копии, срок физического удаления и место размещения данных зависят от инсталляции, а не являются универсальными гарантиями API.
Для важных данных используйте манифесты, контрольные суммы, версионированные ключи и проверенный процесс очистки. Перед хранением чувствительного или регулируемого контента прочитайте Безопасность и жизненный цикл данных.
Подробнее о хранилище
- Объекты и ключи — правила именования, префиксы, метаданные и пагинация по курсору.
- Доступ к хранилищу из песочницы —
выдача, проверка, ротация и отзыв доступа в режимах
roилиrw. - Загрузка и скачивание — веб-интерфейс, REST через шлюз, передача по presigned URL, проверка и очистка.
- Квоты и потребление — текущее потребление, незавершенные загрузки, сверка и освобождение места.
- Безопасность и жизненный цикл данных — учетные данные, хранение, удаление, границы аудита и реагирование на инциденты.
- Справочник REST API и справочник MCP — публичные контракты запросов и ответов и инструменты агента.