> ## 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 воркспейса в память или любой S3-совместимый бакет.

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

Предварительные требования: прочтите два приведенных ниже руководства для начинающих, завершите локальную веб-настройку и откройте этот монорепозиторий в корневой папке вашего редактора. Веб-настройки принадлежат `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)


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

1. STORAGE_PROVIDER=memory (по умолчанию) держит загрузки в процессе — правильно для разработки и тестов.

2. Для реальных файлов установите STORAGE_PROVIDER=s3 с бакетом и парой ключей доступа. STORAGE_ENDPOINT выбирает любой S3-совместимый сервис — Supabase Storage на https://<ref>.supabase.co/storage/v1/s3, MinIO или сам AWS.

3. STORAGE_FORCE_PATH_STYLE по умолчанию true, как только задан endpoint, — Supabase и MinIO этого требуют. Устанавливайте false только для virtual-hosted кастомного endpoint.

4. По желанию направьте STORAGE_PUBLIC_BASE_URL на CDN, чтобы публичные URL объектов разрешались там.

```
STORAGE_PROVIDER=s3
STORAGE_ENDPOINT=https://<ref>.supabase.co/storage/v1/s3
STORAGE_REGION=us-east-1            # Supabase: project region
STORAGE_BUCKET=<bucket>
STORAGE_ACCESS_KEY_ID=…
STORAGE_SECRET_ACCESS_KEY=…
STORAGE_PUBLIC_BASE_URL=https://cdn.example.com   # optional

# No bucket yet? Local S3-compatible storage ships in compose:
docker compose --profile storage up -d minio    # console on :9001
```


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

Загрузки и чтения проходят через аутентифицированные маршруты, сначала разрешающие воркспейс, — /api/storage/objects плюс выделенные маршруты аватара и логотипа. Каждый сохранённый ключ namespaced как {workspaceId}/{purpose}/{safeName} через buildWorkspaceObjectKey.

Креденшелы остаются только на сервере; браузер никогда не видит бакет или ключи.

Загрузки работают? Переходите к «Настройка наблюдаемости».


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

Проверьте, что загрузка проходит туда-обратно, что второй воркспейс не может прочитать объект и что слишком большие или неразрешённые типы контента падают. Ошибки подписи или 403 на Supabase или MinIO обычно означают, что STORAGE_FORCE_PATH_STYLE неверен для этого endpoint.


Чтобы продолжить настройку, прочитайте [Настройка наблюдаемости](https://supastack.dev/ru/docs/web/setup-observability.md).


## Вперёд

[Модуль хранилища](https://supastack.dev/ru/docs/modules/storage.md)