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/modules/storage.md (or send Accept: text/markdown).
Модуль хранилища
Один контракт ObjectStorage, адаптеры memory и 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/; проверьте точные исходные файлы, указанные здесь; список файлов и проверки перед редактированием; сохранять права собственности на рабочую область и секреты, доступные только серверу; и покажу вам разницу. Сообщите ему желаемое поведение, поля ввода и вывода, разрешенные роли, ожидаемые успехи и ошибки, а также тестовую учетную запись, поставщика или устройство. Используйте выборочные значения; никогда не вставляйте настоящий секрет.
Выберите серверное хранилище
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=Повторное использование границ загрузки
Отгруженные маршруты включают объекты, аватары, логотипы профилей и логотипы организаций под /api/storage/. Они разрешают разрешения на идентификацию/рабочую область и проверяют форму загрузки перед сохранением. Проверьте политику размера/типа выбранного маршрута, а не принимайте произвольные ключи клиентских объектов.
Публичные URL-адреса представляют собой представление, а не авторизацию. Храните защищенный контент за проверенной границей чтения приложения и настройте политику сегмента/CDN для данных вашего продукта.
Тестирование реального поведения хранилища
Тестируйте разрешенные/запрещенные загрузки, MIME и отклонение размера, пути к внешней рабочей области, отсутствующие объекты и сбой поставщика. Режим памяти не сохраняется между процессами; перед выпуском проверьте хранение и извлечение на выбранном сервере.
Настройка и конфигурация
packages/storage определяет интерфейс ObjectStorage — putObject, getObject и deleteObject по локаторам объектов — с MemoryObjectStorage для детерминированных тестов и S3CompatibleObjectStorage для продакшен-бакетов.
Ключи объектов строятся через buildWorkspaceObjectKey и проверяются assertWorkspaceObjectKey, так что каждый сохранённый файл namespaced по пространству и назначению (avatar, file, logo). WorkspaceScopedStorageError срабатывает, когда ключ выходит за пределы своего пространства.
interface ObjectStorage {
putObject(input: PutObjectInput): Promise<StoredObject>
getObject(locator: ObjectLocator): Promise<StoredObject | undefined>
deleteObject(locator: ObjectLocator): Promise<boolean>
getPublicUrl(locator: ObjectLocator): string
}
key = {workspaceId}/{purpose}/{safeName}Рабочий процесс внедрения
Маршруты приложения разрешают пространство, валидируют загрузку, строят ключ со scope и вызывают адаптер — хранилище никогда не видит сырого клиентского пути. Выбирайте адаптер в серверном окружении через STORAGE_PROVIDER и его учётные данные.
Открывайте чтения через ту же границу авторизации; отдавайте публичные URL только для объектов, которые продукт намеренно публикует.
Проверка и устранение неполадок
MemoryObjectStorage сохраняет юнит-тесты детерминированными — проверяйте ключи, типы контента и межпространственные отказы там. Проверяйте S3-адаптер через необязательный smoke-путь на реальном бакете до поставки загрузок.