Перейти к основному содержимому
Открыть Markdown

Загрузка и скачивание

Используйте веб-интерфейс для быстрой передачи одного файла, REST через шлюз — для небольших программных передач, а presigned URL — для крупных объектов или передачи байтов в обход шлюза.

Перед началом​

Хранилище аккаунта должно быть включено. Также нужен один из вариантов:

  • аутентифицированная сессия веб-интерфейса;
  • bearer-токен с доступом к активному аккаунту;
  • JR_STORAGE_URL и JR_STORAGE_TOKEN внутри песочницы с доступом ro или rw.

Для загрузки нужен доступ на запись. Для скачивания достаточно доступа только на чтение.

Перед передачей выберите ключ:

FILE="./result.bin"
KEY="artifacts/2026-07-27/result.bin"
DOWNLOADED_FILE="./downloaded-result.bin"

Ключи задаются относительно пространства аккаунта. / создает видимую иерархию папок, но объект остается значением «ключ → байты». При самостоятельной сборке пути REST URL-кодируйте необычные символы ключа.

Выбор способа передачи​

СпособДля чего подходитПуть данных
Загрузка в веб-интерфейсеОдин локальный файл в пределах ограничения браузераБраузер → шлюз → объектное хранилище
PUT или GET через шлюзНебольшие файлы и простые API-клиентыКлиент → шлюз → объектное хранилище
Presigned PUT или GETКрупные файлы и прямая передачаКлиент → объектное хранилище
jr-storage put/getПередача из песочницы с выданным доступомПесочница → объектное хранилище через presigned URL

Размер передачи через шлюз, срок presigned URL и максимальный размер одного объекта настраиваются в инсталляции. Не фиксируйте в коде значение по умолчанию, увиденное в одной инсталляции.

Передача файла через веб-интерфейс​

  1. Откройте Хранилище в активном аккаунте.
  2. Перейдите в нужный префикс по цепочке папок, которая начинается с Все файлы.
  3. Нажмите Загрузить и выберите один файл.
  4. Дождитесь уведомления об успехе и проверьте имя и размер объекта.
  5. Используйте действие Скачать у объекта, чтобы сохранить его локально.

Текущая загрузка из браузера принимает по одному файлу и до отправки отказывается от файлов больше 128 МиБ. Инсталляция может настроить меньший предел на сервере, тогда запрос вернет 413. Скачивание в интерфейсе использует presigned GET URL и не ограничено пределом передачи через шлюз.

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

Загрузка объекта через REST API в теле запроса​

Отправьте файл как сырое тело запроса, а не JSON или multipart-форму:

UPLOAD_RESPONSE="$(
curl --fail-with-body --silent --show-error \
--request PUT \
"$JUSTRUN_API/v1/storage/objects/$KEY" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/octet-stream" \
--data-binary @"$FILE"
)"

jq '{key, size, etag}' <<<"$UPLOAD_RESPONSE"

Успешная загрузка возвращает HTTP 201 с ключом относительно аккаунта, сохраненным размером и необязательным ETag. Загрузка по тому же ключу перезаписывает существующий объект. Контроль квоты при загрузке в теле запроса учитывает разницу размеров, поэтому замена объекта меньшим освобождает место.

Проверьте объект без скачивания:

curl --fail --silent --show-error \
--head "$JUSTRUN_API/v1/storage/objects/$KEY" \
--header "Authorization: Bearer $JUSTRUN_PAT"

Ответ содержит Content-Length и, когда доступны, ETag и Last-Modified.

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

Скачивание объекта через REST API в теле ответа​

curl --fail-with-body --silent --show-error \
"$JUSTRUN_API/v1/storage/objects/$KEY" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--output "$DOWNLOADED_FILE"

cmp "$FILE" "$DOWNLOADED_FILE"

Скачивание в теле ответа передает байты через шлюз. Если сохраненный объект превышает предел передачи через шлюз в инсталляции, шлюз возвращает 413 и направляет клиент к пути через presigned URL.

Загрузка объекта через presigned URL​

Сначала укажите точное количество байтов и запросите у шлюза прямой PUT URL:

SIZE="$(wc -c <"$FILE" | tr -d ' ')"

PRESIGN_RESPONSE="$(
jq -n \
--arg key "$KEY" \
--argjson content_length "$SIZE" \
'{key:$key, method:"PUT", upload_protocol:"multipart_v1", content_length:$content_length}' |
curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/storage/presign" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--data @-
)"

PUT_URL="$(jq -er '.url' <<<"$PRESIGN_RESPONSE")"
UPLOAD_ID="$(jq -er '.upload_id' <<<"$PRESIGN_RESPONSE")"
jq '{expires_at, complete_before}' <<<"$PRESIGN_RESPONSE"

Затем загрузите неопубликованную часть напрямую. Не передавайте bearer-токен Just Run на адрес presigned URL:

curl --fail-with-body --silent --show-error \
--request PUT \
--upload-file "$FILE" \
"$PUT_URL"

Начните передачу части до expires_at. Запросите завершение на сервере до complete_before — на 300 секунд позже. Этот запас сохраняет сессию и резерв квоты, не продлевая срок жизни ссылки. Передача может продолжаться после истечения срока URL, но должна закончиться вовремя для запроса завершения.

После успешного PUT опубликуйте объект через шлюз. Для этого требуется действующее право записи; одна загрузка части еще не означает успех:

curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/storage/uploads/$UPLOAD_ID/complete" \
--header "Authorization: Bearer $JUSTRUN_PAT"

content_length входит в подпись. Если передано другое количество байтов, объектное хранилище отклоняет запрос, обычно с 403. Не сжимайте и не преобразуйте тело между запросом presigned URL и загрузкой.

Запрос presigned URL резервирует только положительный рост байтов и слот нового объекта. Ключом владеет одна незавершенная сессия или запись; конкуренты получают 409 storage.operation_in_progress. Для повтора используйте исходную сессию. Завершение атомарно заменяет резерв учтенным потреблением. Повтор завершенной сессии возвращает исходный результат без повторной публикации. Истекшая сессия, не начавшая завершение, больше не может публиковать и освобождает резерв. Если завершение вернуло 503 из-за неопределенного результата, сохраните идентификатор загрузки и локальный файл и обратитесь к оператору для сверки; одного истечения срока недостаточно.

Определенный отказ S3 при попытке публикации возвращает 422, а отсутствие загрузки — 409. Сервер выполняет прерывание загрузки и проверяет видимые на этот момент части перед освобождением резерва. При неудачной очистке ответ 503 сохраняет резерв для повтора. После успешной очистки можно создать новую сессию. Ошибки проверки до публикации оставляют сессию незавершенной до ее крайнего срока. Неопределенное завершение возвращает 503 и сохраняет резерв до сверки.

Чтобы отменить неиспользуемую незавершенную загрузку, вызовите DELETE /v1/storage/uploads/$UPLOAD_ID с правом записи. Ответ 204 подтверждает прерывание загрузки в S3 и пустой ListParts либо NoSuchUpload, после чего освобождаются резерв и ключ. Публикация и новые передачи частей запрещены, но это не доказывает физическое удаление части, уже находившейся в передаче. Фоновая очистка повторяет прерывание после исходного окна загрузки; правило жизненного цикла бакета остается последним механизмом очистки оставшихся частей. При неудачном прерывании ответ 503 сохраняет резерв даже после истечения срока. Повторите DELETE; фоновая очистка тоже повторяет прерывание. Опубликованная сессия отвечает 409, а неопределенная публикация — 503 и сохраняет резерв.

Скачивание объекта через presigned URL​

Запросите прямой GET URL:

PRESIGN_RESPONSE="$(
jq -n \
--arg key "$KEY" \
'{key:$key, method:"GET"}' |
curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/storage/presign" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--data @-
)"

GET_URL="$(jq -er '.url' <<<"$PRESIGN_RESPONSE")"
jq '{expires_at}' <<<"$PRESIGN_RESPONSE"

curl --fail-with-body --silent --show-error \
"$GET_URL" \
--output "$DOWNLOADED_FILE"

cmp "$FILE" "$DOWNLOADED_FILE"

Шлюз также может подписать необязательное значение content_disposition, переданное клиентом, если браузер должен скачать файл с выбранным именем. Сформируйте значение, безопасное для заголовка, без управляющих символов. Сам URL дает временный bearer-доступ: любой получивший его сможет использовать URL до expires_at.

Проверка результата и очистка​

Сравните криптографическую контрольную сумму, если источник и место назначения находятся на разных машинах:

sha256sum "$FILE" "$DOWNLOADED_FILE"

После проверки удалите временный объект и локально скачанный файл:

STATUS="$(
curl --silent --show-error \
--output /dev/null \
--write-out '%{http_code}' \
--request DELETE "$JUSTRUN_API/v1/storage/objects/$KEY" \
--header "Authorization: Bearer $JUSTRUN_PAT"
)"

test "$STATUS" = "204"
rm -f "$DOWNLOADED_FILE"

Запрос DELETE к хранилищу идемпотентен: удаление отсутствующего ключа тоже возвращает 204.

Диагностика​

Статус или симптомПричина и действие
400 от /presignПроверьте key, GET или PUT заглавными буквами и обязательный числовой content_length для PUT; добавьте upload_protocol: "multipart_v1" (без протокола — 422)
401 от шлюзаОбновите токен пользователя или замените ротированный или отозванный токен песочницы
403 от шлюзаПесочница в режиме ro попыталась выполнить запись
403 от адреса presigned URLURL истек, подписанный размер изменился или URL был модифицирован; запросите новый и повторите точные байты
404 от GET объектаКлюч отсутствует в активном аккаунте; 404 для любого /v1/storage также может означать отключенное хранилище
413 при передаче через шлюзПерейдите на передачу по presigned URL
413 от /presignЗаявленный объект превышает максимум инсталляции; протокол принимает ровно одну часть
429Запись превысит квоту хранилища с учетом pending_bytes; проверьте /v1/storage/usage
503Сохраните локальный источник и идентификатор загрузки; неопределенное завершение требует сверки оператором
Presigned PUT из браузера не работает, а из командной строки работаетПолитика CORS объектного хранилища не разрешает адрес браузера; используйте клиент вне браузера или обратитесь к оператору

Для рабочей среды​

  • Никогда не логируйте и не передавайте bearer-токен или presigned URL.
  • Добавляйте заголовок Authorization только к запросам к шлюзу. Presigned URL уже содержит собственную авторизацию.
  • Используйте стабильные версионированные ключи и проверяйте контрольную сумму до удаления источника.
  • Повтор PUT по тому же ключу перезаписывает этот ключ. Убедитесь, что каждый повтор использует нужные байты.
  • Публичный API использует PUT одного объекта, а не возобновляемую многочастную загрузку. Разбивайте или сохраняйте во внешней промежуточной области объекты больше максимума инсталляции.
  • Изоляция аккаунтов определяется аутентифицированным аккаунтом. Перед передачей чувствительных данных проверьте активный аккаунт.