> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Файловое хранилище

Загрузки со scope пространства через контракт объектного хранилища.

## Прохождение для начинающих

Предварительные требования: прочтите два приведенных ниже руководства для начинающих, завершите локальную веб-настройку и откройте этот монорепозиторий в корневой папке вашего редактора. Веб-настройки принадлежат `apps/web/.env.local`; Next.js не читает корень `.env`. `/dashboard` в поддельном режиме по умолчанию представляет собой демонстрацию без базы данных; `/auth` требуется перенесенная база данных.

Вкратце: рабочее пространство — это отдельные пользователи, данные и настройки одной команды. Сервер является доверенным сервером; не допускайте попадания ключей провайдера в код браузера и телефона. Миграция — это изменение версии базы данных, при котором создаются или обновляются таблицы. Модель ИИ — это механизм, который отвечает; Каталог моделей — это список доступных идентификаторов моделей и цен на сервере. Поставщик — это внешняя служба, такая как служба искусственного интеллекта, электронной почты или службы выставления счетов. Право — это грант, который позволяет рабочей области использовать функцию. Вебхук — это сообщение, которое одна служба отправляет на URL другой службы.

1. Для пробной версии без учетных данных сохраните `STORAGE_PROVIDER=memory`. Если эта проверка не имеет видимого контроля загрузки, попросите своего агента по кодированию проверить `apps/web/app/api/storage/avatar/route.ts`, `apps/web/app/api/storage/logo/route.ts`, `apps/web/app/api/storage/organization-logo/route.ts` и соответствующую страницу настроек, прежде чем подключать небольшой образец изображения.

2. Чтобы проверить постоянство, установите `STORAGE_PROVIDER=s3`, `STORAGE_REGION` и `STORAGE_BUCKET` в `apps/web/.env.local`, локально добавьте тестовые учетные данные только для сервера и перезапустите.

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

Для пользовательского кода начните с предоставленного `prompts/README.md` и скопируйте ближайшее приглашение: `prompts/new-app-screen.md` для экрана приложения или `prompts/new-landing-page.md` для общедоступной страницы. Для работы с сервером, базой данных или провайдером дайте своему агенту кодирования задание из этого руководства и попросите его прочитать `AGENTS.md`, `.ai/PROJECT_CONTEXT.md` и соответствующие зеркала `.ai/`; проверьте точные исходные файлы, указанные здесь; список файлов и проверки перед редактированием; сохранять права собственности на рабочую область и секреты, доступные только серверу; и покажу вам разницу. Сообщите ему желаемое поведение, поля ввода и вывода, разрешенные роли, ожидаемые успехи и ошибки, а также тестовую учетную запись, поставщика или устройство. Используйте выборочные значения; никогда не вставляйте настоящий секрет.

[Прежде чем начать](https://supastack.dev/ru/docs/web/before-you-start.md)

[Основные сведения о терминале](https://supastack.dev/ru/docs/web/terminal-basics.md)

[Локальная веб-настройка](https://supastack.dev/ru/docs/web/ship-in-5-minutes.md)

[Подсказки агента и память проекта](https://supastack.dev/ru/docs/web/agents.md)


## Выберите серверное хранилище

`STORAGE_PROVIDER=memory` — значение по умолчанию без учетных данных. `local` записывает объекты на диск в каталог `STORAGE_LOCAL_DIR` (по умолчанию `./.data/storage`, в продакшене указывается явно) и передает их по истекающим URL с HMAC-подписью через `/api/storage/local/[...key]` (`STORAGE_LOCAL_SIGNING_SECRET`, по умолчанию используется `AUTH_SECRET`) для односерверных развертываний. `s3` использует `apps/web/src/storage-runtime.ts` для сборки клиента AWS SDK поверх компактного контракта `@supastack/storage`, поддерживая Supabase Storage и MinIO с включенными по умолчанию URL в стиле путей.

```
STORAGE_PROVIDER=s3
STORAGE_REGION=us-east-1
STORAGE_BUCKET=your-product-bucket
# Set STORAGE_ACCESS_KEY_ID and STORAGE_SECRET_ACCESS_KEY on the server.
# Optional: STORAGE_ENDPOINT, STORAGE_FORCE_PATH_STYLE, STORAGE_PUBLIC_BASE_URL
# Self-hosted single-server disk storage:
# STORAGE_PROVIDER=local
# STORAGE_LOCAL_DIR=./.data/storage
# STORAGE_LOCAL_SIGNING_SECRET=
# Local MinIO Compose overrides: MINIO_ROOT_USER / MINIO_ROOT_PASSWORD
```


## Повторное использование границ загрузки

Отгруженные маршруты включают объекты, аватары, логотипы профилей и логотипы организаций под `/api/storage/`. Они разрешают разрешения на идентификацию/рабочую область и проверяют форму загрузки перед сохранением. Проверьте политику размера/типа выбранного маршрута, а не принимайте произвольные ключи клиентских объектов.

Публичные URL-адреса представляют собой представление, а не авторизацию. Храните защищенный контент за проверенной границей чтения приложения и настройте политику сегмента/CDN для данных вашего продукта.


## Тестирование реального поведения хранилища

Тестируйте разрешенные/запрещенные загрузки, MIME и отклонение размера, пути к внешней рабочей области, отсутствующие объекты и сбой поставщика. Режим памяти не сохраняется между процессами; перед выпуском проверьте хранение и извлечение на выбранном сервере.

[Настройка хранилища Supabase](https://supastack.dev/ru/docs/web/project-structure.md)

[Загрузить список маршрутов](https://supastack.dev/ru/docs/web/project-structure.md)


## Настройка и конфигурация

STORAGE_PROVIDER выбирает адаптер: memory для тестов и локальной разработки, s3 для любого S3-совместимого бакета (STORAGE_BUCKET, STORAGE_ENDPOINT, STORAGE_ACCESS_KEY_ID, STORAGE_SECRET_ACCESS_KEY, STORAGE_PUBLIC_BASE_URL). Учётные данные остаются только на сервере.

packages/storage владеет контрактом ObjectStorage — putObject/getObject/deleteObject по локаторам объектов — плюс assertWorkspaceObjectKey и buildWorkspaceObjectKey, так что каждый сохранённый объект namespaced по пространству и назначению (avatar, file, logo).

```
Uploads and reads go through authenticated routes:
  /api/storage/objects
  /api/storage/avatar
  /api/storage/logo
  /api/storage/organization-logo
```


## Рабочий процесс внедрения

Держите загрузки за слоем аутентифицированных маршрутов: разрешите пространство, проверьте тип и размер контента, постройте ключ со scope пространства и затем сохраните через адаптер. Отдавайте чтения так же, если только объект не намеренно публичен.

Аватары и логотипы организаций имеют выделенные маршруты с собственной валидацией; произвольные продуктовые файлы проходят через /objects с объявленным назначением.


## Проверка и устранение неполадок

Проверьте, что анонимные загрузки отклоняются, что одно пространство не может читать ключи объектов другого, что слишком большие или неразрешённые типы контента завершаются ошибкой и что удалённый объект перестаёт разрешаться. Используйте memory-адаптер в тестах; реальный бакет проверяйте через необязательный smoke-путь.


## Вперёд

[AI-функции](https://supastack.dev/ru/docs/web/ai.md)