Configurar o armazenamento de ficheiros

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
• Noções básicas sobre terminais
• Configuração local da Web
• Avisos do agente e memória do projeto

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
• Fazer upload do inventário de rotas

Instalação e configuração

1. STORAGE_PROVIDER=memory (a predefinição) mantém os uploads em processo — certo para desenvolvimento e testes.

2. Para ficheiros reais, define STORAGE_PROVIDER=s3 com um bucket e um par de access keys. STORAGE_ENDPOINT seleciona qualquer serviço compatível com S3 — Supabase Storage em https://<ref>.supabase.co/storage/v1/s3, MinIO ou a própria AWS.

3. STORAGE_FORCE_PATH_STYLE passa a true por defeito quando um endpoint está definido — Supabase e MinIO exigem-no. Define-o como false apenas para um endpoint custom virtual-hosted.

4. Opcionalmente aponta STORAGE_PUBLIC_BASE_URL para uma CDN para que os URLs públicos de objetos resolvam aí.

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

Fluxo de implementação

Uploads e leituras passam por rotas autenticadas que resolvem primeiro o workspace — /api/storage/objects mais as rotas dedicadas de avatar e logo. Cada chave armazenada é namespaced como {workspaceId}/{purpose}/{safeName} via buildWorkspaceObjectKey.

As credenciais ficam só no servidor; o browser nunca vê o bucket nem as chaves.

Uploads a funcionar? Continua para Configurar a observabilidade.

Verificação e resolução de problemas

Verifica que um upload faz ida e volta, que um segundo workspace não consegue ler o objeto e que content types demasiado grandes ou não permitidos falham. Erros de assinatura ou 403 contra Supabase ou MinIO costumam significar que STORAGE_FORCE_PATH_STYLE está errado para o endpoint.