For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ru/docs/web/storage.md (or send Accept: text/markdown).
Файловое хранилище
Загрузки со 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/; проверьте точные исходные файлы, указанные здесь; список файлов и проверки перед редактированием; сохранять права собственности на рабочую область и секреты, доступные только серверу; и покажу вам разницу. Сообщите ему желаемое поведение, поля ввода и вывода, разрешенные роли, ожидаемые успехи и ошибки, а также тестовую учетную запись, поставщика или устройство. Используйте выборочные значения; никогда не вставляйте настоящий секрет.
Выберите серверное хранилище
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 и отклонение размера, пути к внешней рабочей области, отсутствующие объекты и сбой поставщика. Режим памяти не сохраняется между процессами; перед выпуском проверьте хранение и извлечение на выбранном сервере.
Настройка и конфигурация
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-путь.