Como Adicionar Upload de Arquivos ao Seu App: Armazenamento, Limites e Segurança

Para adicionar upload de arquivos ao seu app, guarde os arquivos em armazenamento de objetos (um bucket), e não no disco do servidor nem no banco de dados, e salve um pequeno registro no banco com a chave do arquivo, o nome, o tamanho, o tipo e o dono. Verifique o tamanho e o tipo do arquivo no servidor, defina logo no início se os arquivos são públicos (como fotos de produtos) ou privados (como faturas), e sirva arquivos privados somente depois de conferir quem está pedindo. Em um construtor de apps com IA, você pode descrever o recurso de upload em um prompt; o importante é testar se os arquivos sobrevivem a um novo deploy e se não podem ser abertos pela pessoa errada.

Decida que tipo de upload você precisa

Antes de construir, responda três perguntas:

1. Quais arquivos? Fotos de perfil, imagens de produtos, PDFs, planilhas, áudio, vídeo. Isso define os limites de tipo e tamanho.
2. Quem pode vê-los? Todos (uma galeria pública) ou apenas quem enviou e os administradores (contratos, documentos de identidade, arquivos de clientes).
3. O que acontece depois do upload? Apenas guardar, mostrar uma prévia, redimensionar imagens ou ler o conteúdo.

Imagens públicas e documentos privados precisam de configurações diferentes, então resolva isso primeiro.

Onde os arquivos devem ficar

Para a maioria dos apps, armazenamento de objetos mais um registro no banco é a resposta certa. O registro no banco é o que o seu app consulta (“mostrar os documentos deste usuário”); o bucket apenas guarda os bytes.

Arquivos públicos versus privados

• Arquivos públicos (fotos de produtos, imagens de blog, avatares) podem ser servidos a partir de uma URL pública. Qualquer pessoa com o link pode abri-los, o que é aceitável para esse tipo de conteúdo.
• Arquivos privados (faturas, contratos, documentos médicos ou de identidade, entregas de clientes) nunca podem ter uma URL pública adivinhável. O servidor verifica se o usuário logado é dono do arquivo ou tem permissão e, então, ou devolve o arquivo ou devolve uma URL assinada: um link que funciona apenas por um curto período.

Um erro comum e grave é guardar arquivos privados em um bucket público com nomes previsíveis. Quem adivinhar /uploads/invoice-102.pdf recebe a fatura de outra pessoa.

Prompts de exemplo

Upload de imagem pública:

Permita que administradores enviem até 5 fotos de produto por produto. Aceite JPG, PNG e WebP de até 5 MB cada. Guarde os arquivos no armazenamento de arquivos, salve a chave, o tamanho e a ordem de cada arquivo em uma tabela product_images e mostre miniaturas com um botão de remover. Valide tipo e tamanho no servidor, não apenas no navegador.

Upload de documento privado:

Adicione uma página de Documentos para clientes logados. Os clientes podem enviar PDFs de até 20 MB. Os arquivos são privados: guarde-os no armazenamento de arquivos, salve o ID do dono, o nome original, o tamanho e a hora do envio em uma tabela documents, e só permita que o dono e os administradores façam o download. Os downloads passam por uma rota do servidor que verifica a permissão. Nunca exponha uma URL pública para esses arquivos.

Acréscimos úteis:

Mostre uma barra de progresso durante o envio e um erro claro se o arquivo for grande demais ou do tipo errado.

Quando um registro de documento for apagado, apague também o arquivo armazenado.

Passo a passo

1. Defina tipos e limites de tamanho para cada campo de upload. Seja específico: “PDF de até 20 MB”, e não “documentos”.
2. Ative o armazenamento. Em um construtor com IA, peça o upload e ele configura o armazenamento; em outros lugares, crie um bucket e adicione as credenciais como segredos do servidor.
3. Crie uma tabela no banco para os registros de arquivos: ID, dono, chave de armazenamento, nome original, tipo, tamanho, data de criação.
4. Crie a rota de upload no servidor: verifique se o usuário está logado, confira tipo e tamanho, gere uma chave de armazenamento segura (não o nome do arquivo enviado pelo usuário), salve o arquivo e insira o registro.
5. Crie o caminho de download ou exibição: URL pública para arquivos públicos; uma rota com verificação de permissão ou uma URL assinada para os privados.
6. Construa a interface: seletor de arquivo, arrastar e soltar se for útil, progresso, prévias, erros.
7. Trate as exclusões para que remover um registro também remova o arquivo armazenado.
8. Teste: envie, recarregue, faça um novo deploy ou publique e confira se o arquivo ainda abre. Depois, entre com outro usuário e tente abrir o arquivo privado do primeiro.

Erros comuns

• Gravar uploads no disco do servidor. Funciona em desenvolvimento, e depois os arquivos somem após um reinício ou novo deploy.
• Confiar nas verificações do navegador. A configuração “accept” de um campo de arquivo é uma dica, não segurança. Verifique tipo e tamanho no servidor.
• Usar o nome do arquivo do usuário como chave de armazenamento. Nomes colidem e podem ter caracteres estranhos. Gere uma chave única e guarde o nome original separadamente.
• Buckets públicos para arquivos privados. Veja acima; este é o erro que vira notícia.
• Permitir qualquer tipo de arquivo. Arquivos HTML ou SVG servidos a partir do seu domínio podem executar scripts em algumas configurações. Aceite apenas os tipos de que você precisa.
• Nenhum limite de tamanho. Um único upload enorme pode consumir sua cota de armazenamento ou estourar o tempo limite da requisição.
• Arquivos órfãos. Apagar o registro no banco sem apagar o arquivo enche aos poucos um armazenamento que você está pagando.
• Esquecer o celular. Fotos de celular podem ser grandes e em formatos como HEIC; decida se aceita ou converte.

Checklist

• Os arquivos vão para armazenamento de objetos, não para o disco do servidor nem para o banco
• Cada arquivo tem um registro no banco com dono, chave, nome, tipo e tamanho
• Tipo e tamanho são verificados no servidor
• As chaves de armazenamento são geradas, não tiradas do nome do arquivo
• Arquivos privados só são servidos após uma verificação de permissão
• Outro usuário não consegue abrir os seus arquivos privados, nem com o link
• Excluir um registro exclui o arquivo
• Os arquivos continuam carregando depois de publicar ou fazer um novo deploy
• Erros de upload são mostrados com clareza, inclusive no celular

Uploads de arquivos no Mythex

O Mythex pode ativar o armazenamento de arquivos de um projeto automaticamente quando o seu app precisa de uploads, então você não precisa provisionar um bucket manualmente. Você também pode digitar /storage no chat. Está disponível nos planos Free e Pro, com limite de 1 GB no Free, e você pode ver o status em Configurações → Armazenamento.

A documentação deixa claro que a hospedagem publicada não é um sistema de arquivos local durável, então peça ao agente que use o armazenamento da plataforma em vez de salvar no disco. Os arquivos armazenados e os downloads são cobrados do seu saldo de créditos, por tamanho e pela quantidade baixada; o plano Pro paga metade da taxa do Free. Veja Armazenamento de arquivos na documentação.

Uploads costumam andar junto com um banco de dados para os registros de arquivos e com login para arquivos privados. Se você está construindo um lugar onde clientes trocam documentos, veja como criar um portal do cliente, e passe pela lista de verificação de segurança antes do lançamento.

Perguntas