> ## 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 # Armazenamento de ficheiros Uploads com scope de workspace através do contrato de object storage. ## Passo a passo para iniciantes Pré-requisitos: Leia os dois guias para iniciantes abaixo, conclua a configuração local da Web e abra este monorepo na raiz do seu editor. As configurações da Web pertencem a `apps/web/.env.local`; Next.js não lê a raiz `.env`. `/dashboard` no modo falso padrão é uma demonstração sem banco de dados; `/auth` precisa de um banco de dados migrado. Termos rápidos: um espaço de trabalho consiste em usuários, dados e configurações separados de uma equipe. O servidor é o back-end confiável; mantenha as chaves do provedor fora do navegador e do código do telefone. Uma migração é uma alteração de versão do banco de dados que cria ou atualiza tabelas. Um modelo de IA é o mecanismo que responde; o catálogo de modelos é a lista do servidor de IDs e preços de modelos disponíveis. Um provedor é um serviço externo, como IA, e-mail ou serviço de cobrança. Um direito é uma concessão que permite que um espaço de trabalho use um recurso. Um webhook é uma mensagem que um serviço envia para o URL de outro serviço. 1. Para uma avaliação sem credencial, mantenha `STORAGE_PROVIDER=memory`. Se esta verificação não tiver controle de upload visível, peça ao seu agente de codificação para inspecionar `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` e a página de configurações correspondentes antes de conectar uma pequena imagem de amostra. 2. Para verificar a persistência, defina `STORAGE_PROVIDER=s3`, `STORAGE_REGION` e `STORAGE_BUCKET` em `apps/web/.env.local`, adicione credenciais de teste somente de servidor localmente e reinicie. 3. A imagem deve ser recarregada do armazenamento. Os arquivos de memória desaparecem quando o processo é reiniciado; para erros S3, verifique o bucket, o endpoint e a política de acesso. Para código personalizado, comece com o `prompts/README.md` fornecido e copie o prompt mais próximo: `prompts/new-app-screen.md` para uma tela de aplicativo ou `prompts/new-landing-page.md` para uma página pública. Para trabalho de servidor, banco de dados ou provedor, dê ao seu agente de codificação a tarefa deste guia e peça-lhe para ler `AGENTS.md`, `.ai/PROJECT_CONTEXT.md` e espelhos `.ai/` correspondentes; inspecione os arquivos de origem exatos nomeados aqui; listar arquivos e verificações antes de editar; preservar a propriedade do espaço de trabalho e os segredos apenas do servidor; e mostrar a diferença. Informe o comportamento desejado, campos de entrada e saída, funções permitidas, sucessos e erros esperados e a conta de teste, provedor ou dispositivo. Use valores de amostra; nunca cole um segredo real. [Antes de começar](https://supastack.dev/pt/docs/web/before-you-start.md) [Noções básicas sobre terminais](https://supastack.dev/pt/docs/web/terminal-basics.md) [Configuração local da Web](https://supastack.dev/pt/docs/web/ship-in-5-minutes.md) [Avisos do agente e memória do projeto](https://supastack.dev/pt/docs/web/agents.md) ## Selecione o back-end de armazenamento `STORAGE_PROVIDER=memory` é o padrão sem credenciais. `local` grava objetos em disco sob `STORAGE_LOCAL_DIR` (padrão `./.data/storage`, exigido explicitamente em produção) e os transmite por URLs com expiração assinadas via HMAC em `/api/storage/local/[...key]` (`STORAGE_LOCAL_SIGNING_SECRET`, recorrendo a `AUTH_SECRET`) para implantações de servidor único. `s3` usa `apps/web/src/storage-runtime.ts` para compor o cliente AWS SDK sobre o contrato enxuto `@supastack/storage`, oferecendo suporte ao Supabase Storage e ao MinIO com URLs no estilo de caminho ativadas por padrão. ``` 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 ``` ## Reutilize os limites de upload As rotas enviadas abrangem objetos, avatares, logotipos de perfil e logotipos de organizações sob `/api/storage/`. Eles resolvem permissões de identidade/espaço de trabalho e validam o formato de upload antes do armazenamento. Inspecione a política de tamanho/tipo da rota escolhida em vez de aceitar chaves de objeto cliente arbitrárias. URLs públicos são apresentação, não autorização. Mantenha o conteúdo protegido atrás do limite de leitura verificado do aplicativo e configure a política bucket/CDN para os dados do seu produto. ## Teste o comportamento real do armazenamento Teste uploads permitidos/negados, MIME e rejeição de tamanho, caminhos de espaço de trabalho externo, objetos ausentes e falha do provedor. O modo de memória não persiste entre processos; verifique o armazenamento e a recuperação no back-end selecionado antes do lançamento. [Configuração de armazenamento Supabase](https://supastack.dev/pt/docs/web/project-structure.md) [Fazer upload do inventário de rotas](https://supastack.dev/pt/docs/web/project-structure.md) ## Instalação e configuração STORAGE_PROVIDER seleciona o adaptador: memory para testes e desenvolvimento local, s3 para qualquer bucket compatível com S3 (STORAGE_BUCKET, STORAGE_ENDPOINT, STORAGE_ACCESS_KEY_ID, STORAGE_SECRET_ACCESS_KEY, STORAGE_PUBLIC_BASE_URL). As credenciais ficam apenas no servidor. O packages/storage possui o contrato ObjectStorage — putObject/getObject/deleteObject sobre locators de objetos — mais assertWorkspaceObjectKey e buildWorkspaceObjectKey para que cada objeto armazenado seja namespaced por workspace e propósito (avatar, ficheiro, logo). ``` Uploads and reads go through authenticated routes: /api/storage/objects /api/storage/avatar /api/storage/logo /api/storage/organization-logo ``` ## Fluxo de implementação Mantém os uploads atrás da camada de rotas autenticadas: resolve o workspace, valida content type e tamanho, constrói a chave com scope de workspace e depois armazena através do adaptador. Serve as leituras da mesma forma, salvo quando um objeto é deliberadamente público. Avatares e logotipos de organização têm rotas dedicadas com a sua própria validação; ficheiros de produto arbitrários passam por /objects com um propósito declarado. ## Verificação e resolução de problemas Verifica que uploads anónimos são rejeitados, que um workspace não consegue ler as chaves de objetos de outro, que content types demasiado grandes ou não permitidos falham, e que um objeto eliminado deixa de resolver. Usa o adaptador memory nos testes; verifica o bucket real através do percurso smoke opcional. ## Seguinte [Funcionalidades de IA](https://supastack.dev/pt/docs/web/ai.md)