Перейти к содержимому
Логотип Аурабаза
аурабаза

Храните и обслуживайте файлы с помощью JavaScript SDK.

Ежедневные потоки хранения данных с помощью client.storage: управление сегментами, одиночная и многочастная загрузка, потоковая загрузка, URL-адреса с подписью HMAC и восстановление корзины.

Практическое руководство8 мин читатьУровень среднийПересмотрено 28 окт. 2026 г.

Эта страница была переведена автоматически. Английская версия является авторитетной.

Управление сегментами#

Корзина группирует файлы и решает, являются ли они общедоступными. Для создания и удаления сегментов требуется ключ service_role. Для просмотра сегментов требуется вошедший в систему пользователь или ключ service_role (анонимный ключ получает 403 FORBIDDEN).

server/buckets.tstypescript
// Создайте общедоступную корзину (любой может читать объекты без ключей API)
await admin.storage.createBucket('avatars', { public: true })

// Создайте частный сегмент (только владельцы объектов или service_role могут читать)
await admin.storage.createBucket('invoices', {
  public: false,
  fileSizeLimit: 10 * 1024 * 1024, // Ограничение 10 МБ на файл
  allowedMimeTypes: ['application/pdf'],
})

// Получение списка доступных сегментов
const { data: buckets, error } = await admin.storage.listBuckets()

Корзина также принимает fileSizeLimit (в байтах) и allowedMimeTypes. Слишком большая загрузка возвращает 413 PAYLOAD_TOO_LARGE, а недопустимый тип возвращает 400 BAD_REQUEST.

Загрузить, скачать, перечислить, удалить#

files.tstypescript
const bucket = aura.storage.from('invoices')

// Загрузка: файл, большой двоичный объект, буфер или Uint8Array.
// Файлы размером > 5 МБ автоматически разбиваются на составные части.
const { data, error } = await bucket.upload(`${user.id}/2026-10.pdf`, file, {
  contentType: 'application/pdf',
  onUploadProgress: (progress) => {
    console.log(`Upload progress: ${progress.percentage}%`)
  },
})
// → {ключ, сегмент, URL, размер, тип_контента, etag }

// Заменить существующий файл, принадлежащий текущему пользователю
await bucket.upload(`${user.id}/2026-10.pdf`, newFile, { upsert: true })

// Список файлов в префиксе/папке
const { data: files } = await bucket.list({ prefix: `${user.id}/` })

// Скачать файл как Blob
const { data: blob, error: downloadError } = await bucket.download(`${user.id}/2026-10.pdf`)

// Потоковая загрузка без загрузки всего файла в память
const { data: stream } = await bucket.download(`${user.id}/2026-10.pdf`).asStream()

// Удалить файл (по умолчанию он перемещается в корзину с 30-дневным сроком хранения).
await bucket.remove([`${user.id}/2026-10.pdf`])

// Безвозвратное удаление (обходит мусор и немедленно освобождает дисковую квоту)
await bucket.remove([`${user.id}/2026-10.pdf`], { permanent: true })

Ключевые варианты поведения во время выполнения:

  • При загрузке существующего пути возвращается 409 CONFLICT, если не указан upsert: true.
  • Анонимные загрузки отклоняются с помощью 403 FORBIDDEN как в частных, так и в общедоступных сегментах (для записи требуется проверенный JWT или служебный ключ).
  • Защита от обхода пути: пути, содержащие .. или недопустимые символы, возвращают 400 INVALID_PATH без возникновения необработанных исключений.
  • Изоляция пользователя: один пользователь не может перезаписывать или удалять файлы, принадлежащие другому пользователю (owner_id = auth.uid()). Структурируйте пути, используя папки с пользовательской областью, такие как ${user.id}/....

Поделиться файлом (публичные и подписанные URL-адреса)#

share.tstypescript
// 1. Публичный сегмент: прямой постоянный URL-адрес (обслуживается без ключей API).
const { data: { publicUrl } } = aura.storage.from('avatars').getPublicUrl('ada.png')
// → https://<slug>.localhost:8080/v1/storage/avatars/ada.png

// Принудительная загрузка в виде вложения с собственным именем файла
const downloadUrl = aura.storage.from('avatars').getPublicUrl('ada.png', {
  download: 'avatar-ada.png',
})

// 2. Частный сегмент: подписанный URL-адрес HMAC с настраиваемым сроком жизни.
const { data, error } = await aura.storage.from('invoices').createSignedUrl(
  `${user.id}/2026-10.pdf`,
  300, // Действительно в течение 300 секунд (5 минут)
  { download: true }
)
// data.signedUrl и data.url содержат подписанный URL-адрес HMAC.

// 3. Прямая загрузка в браузер без раскрытия секретных ключей.
// Серверная сторона (service_role):
const { data: uploadInfo } = await admin.storage.from('invoices').createSignedUploadUrl(
  `${user.id}/document.pdf`,
  600
)

// Браузерный клиент (ключ API не требуется):
await aura.storage.uploadToSignedUrl(uploadInfo.signedUrl, file, {
  contentType: 'application/pdf',
})

Подписанные URL-адреса фиксируют метод HTTP (GET или PUT), корзину, ключ и временную метку срока действия. По истечении срока действия или в случае удаления объекта запросы получают 403 FORBIDDEN.

Кто что может делать (матрица доступа)#

ДействиеАнонимный ключ (anon)Вошедший пользователь (authenticated)Роль службы (service_role)
Чтение файла в общедоступной корзинеДаДаДа
Чтение файла в частной корзинеНет (403)Только владелец (owner_id = auth.uid())Да
Загрузите новый файлНет (403)Да (становится владельцем)Да
Замените (upsert) или удалите.Нет (403)Только владелецДа
Список файлов в общедоступной корзинеДаДаДа
Список файлов в частной корзинеНет (403)Только владелец (фильтр RLS)Да
Создание, обновление или удаление сегментовНет (403)Нет (403)Да
URL-адреса загрузки, подписанные MintНет (403)Нет (403)Да

Владелец идентифицируется субъектом JWT (auth.uid()). Как в общедоступных, так и в частных сегментах пользователи не могут перезаписывать или уничтожать объекты других пользователей.

Перемещение, копирование, метаданные и удаление#

server/organise.tstypescript
// Скопируйте файл (сохраняет исходный тип контента и пользовательские метаданные)
await admin.storage.copy('invoices', '2026/draft.pdf', '2026/archive.pdf')

// Переместить или переименовать файл
await admin.storage.move('invoices', '2026/draft.pdf', '2026/final.pdf')

// Проверка метаданных объекта (размер, тип MIME, ETag, пользовательские метаданные)
const { data: meta } = await admin.storage.getMetadata('invoices', '2026/final.pdf')

// Список элементов, которые сейчас находятся в корзине (сохранение 30 дней).
const { data: trashItems } = await admin.storage.from('invoices').listTrash()

// Восстановить объект из корзины
await admin.storage.from('invoices').restore('2026/final.pdf')

Сведения о преобразованиях изображений в реальном времени (изменение размера, преобразование формата, поворот) см. в Storage SDK Reference.