Como Adicionar Uploads de Ficheiros à Sua App: Armazenamento, Limites e Segurança

Para adicionar uploads de ficheiros à sua app, guarde os ficheiros em armazenamento de objetos (um bucket), e não no disco do servidor nem na base de dados, e grave um pequeno registo na base de dados com a chave do ficheiro, o nome, o tamanho, o tipo e o proprietário. Verifique o tamanho e o tipo do ficheiro no servidor, decida desde o início se os ficheiros são públicos (como fotos de produtos) ou privados (como faturas), e sirva os ficheiros privados só depois de confirmar quem está a pedi-los. Num construtor de apps com IA, pode descrever a funcionalidade de upload num único prompt; o mais importante é testar se os ficheiros sobrevivem a uma nova implementação e se não podem ser abertos pela pessoa errada.

Decida que tipo de uploads precisa

Antes de construir, responda a três perguntas:

Que ficheiros? Fotos de perfil, imagens de produtos, PDFs, folhas de cálculo, áudio, vídeo. Isto define os limites de tipo e tamanho.
Quem os pode ver? Toda a gente (uma galeria pública) ou apenas quem carregou e os administradores (contratos, documentos de identificação, ficheiros de clientes).
O que acontece depois do upload? Apenas guardar, mostrar uma pré-visualização, redimensionar imagens ou ler o conteúdo.

Imagens públicas e documentos privados precisam de configurações diferentes, por isso resolva isto primeiro.

Onde devem ficar os ficheiros

Opção	Como funciona	Indicada para	Cuidado com
Armazenamento de objetos (bucket)	Ficheiros guardados num serviço criado para isso; a base de dados guarda uma chave ou URL	Quase todas as apps	As regras de acesso têm de estar bem definidas
Armazenamento fornecido pela plataforma	O construtor de apps ou o alojamento ativa um bucket para si	Apps construídas nessa plataforma	Os limites e os preços seguem a plataforma
Disco do servidor	Ficheiros escritos no sistema de ficheiros do servidor da app	Apenas desenvolvimento local	Muitas vezes apagados ao reiniciar ou reimplementar
Na base de dados	Os bytes do ficheiro guardados numa tabela	Quase nunca	Incha a base de dados e torna as cópias de segurança mais lentas
Widget de upload de terceiros	Um serviço de upload alojado trata de todo o processo	Media pesada, transformações de imagem	Mais um fornecedor, conta e fatura

Para a maioria das apps, a resposta certa é armazenamento de objetos mais um registo na base de dados. A linha da base de dados é o que a sua app consulta («mostrar os documentos deste utilizador»); o bucket só guarda os bytes.

Ficheiros públicos vs privados

Ficheiros públicos (fotos de produtos, imagens de blogue, avatares) podem ser servidos a partir de um URL público. Quem tiver a ligação pode abri-los, o que é aceitável para este tipo de conteúdo.
Ficheiros privados (faturas, contratos, documentos médicos ou de identificação, entregas a clientes) nunca podem ter um URL público adivinhável. O servidor verifica se o utilizador com sessão iniciada é o proprietário do ficheiro ou tem permissão, e depois ou transmite-o de volta ou devolve um URL assinado: uma ligação que só funciona durante pouco tempo.

Um erro comum e grave é guardar ficheiros privados num bucket público com nomes previsíveis. Quem adivinhar /uploads/fatura-102.pdf fica com a fatura de outra pessoa.

Exemplos de prompts

Um upload de imagem pública:

Permita que os administradores carreguem até 5 fotos de produto por produto. Aceite JPG, PNG e WebP até 5 MB cada. Guarde os ficheiros no armazenamento de ficheiros, grave a chave, o tamanho e a ordem de cada ficheiro numa tabela product_images e mostre miniaturas com um botão para remover. Valide o tipo e o tamanho no servidor, não apenas no browser.

Um upload de documento privado:

Adicione uma página de Documentos para clientes com sessão iniciada. Os clientes podem carregar PDFs até 20 MB. Os ficheiros são privados: guarde-os no armazenamento de ficheiros, grave o ID do proprietário, o nome original, o tamanho e a hora do upload numa tabela documents, e só deixe o proprietário e os administradores fazerem o download. Os downloads passam por uma rota do servidor que verifica a permissão. Nunca exponha um URL público para estes ficheiros.

Seguimentos úteis:

Mostre uma barra de progresso durante o upload e um erro claro se o ficheiro for demasiado grande ou do tipo errado.

Quando um registo de documento for apagado, apague também o ficheiro guardado.

Passo a passo

Defina tipos e limites de tamanho para cada campo de upload. Seja específico: «PDF até 20 MB», e não «documentos».
Ative o armazenamento. Num construtor de IA, peça uploads e ele configura o armazenamento; noutro lado, crie um bucket e adicione as credenciais como segredos do lado do servidor.
Crie uma tabela na base de dados para os registos de ficheiros: ID, proprietário, chave de armazenamento, nome original, tipo, tamanho, data de criação.
Construa a rota de upload no servidor: verifique se o utilizador tem sessão iniciada, verifique o tipo e o tamanho, gere uma chave de armazenamento segura (não o nome do ficheiro do utilizador), guarde o ficheiro e insira o registo.
Construa o caminho de download ou de apresentação: URL público para ficheiros públicos; uma rota com verificação de permissão ou um URL assinado para os privados.
Construa a interface: seletor de ficheiros, arrastar e largar se for útil, progresso, pré-visualizações, erros.
Trate as eliminações para que remover um registo também remova o ficheiro guardado.
Teste: faça upload, recarregue, reimplemente ou publique, e confirme que o ficheiro continua a abrir. Depois, inicie sessão com outro utilizador e tente abrir o ficheiro privado do primeiro.

Erros comuns

Escrever os uploads no disco do servidor. Funciona em desenvolvimento e depois os ficheiros desaparecem ao reiniciar ou reimplementar.
Confiar nas verificações do browser. A definição «accept» de um campo de ficheiro é uma sugestão, não segurança. Verifique o tipo e o tamanho no servidor.
Usar o nome do ficheiro do utilizador como chave de armazenamento. Os nomes colidem e podem ter caracteres estranhos. Gere uma chave única e guarde o nome original à parte.
Buckets públicos para ficheiros privados. Veja acima; este é o erro que aparece nas notícias.
Permitir qualquer tipo de ficheiro. Ficheiros HTML ou SVG servidos a partir do seu domínio podem executar scripts em certas configurações. Aceite apenas os tipos de que precisa.
Sem limite de tamanho. Um upload enorme pode esgotar a sua quota de armazenamento ou dar timeout ao pedido.
Ficheiros órfãos. Apagar o registo na base de dados mas não o ficheiro enche lentamente um armazenamento que está a pagar.
Esquecer o telemóvel. As fotos dos telemóveis podem ser grandes e em formatos como HEIC; decida se as aceita ou se as converte.

Lista de verificação

Os ficheiros vão para armazenamento de objetos, e não para o disco do servidor nem para a base de dados
Cada ficheiro tem um registo na base de dados com proprietário, chave, nome, tipo e tamanho
Tipo e tamanho verificados no servidor
As chaves de armazenamento são geradas, não tiradas do nome do ficheiro
Os ficheiros privados só são servidos depois de uma verificação de permissão
Outro utilizador não consegue abrir os seus ficheiros privados, mesmo com o link
Apagar um registo apaga o ficheiro
Os ficheiros continuam a abrir depois de publicar ou reimplementar
Os erros de upload são mostrados com clareza, inclusive num telemóvel

Uploads de ficheiros na Mythex

A Mythex pode ativar armazenamento de ficheiros automaticamente para um projeto quando a sua app precisa de uploads, por isso não tem de configurar um bucket manualmente. Também pode escrever /storage no chat. Está disponível nos planos Free e Pro, com um limite de 1 GB no Free, e pode ver o estado em Definições → Armazenamento.

A documentação é explícita: o alojamento publicado não é um sistema de ficheiros local persistente, por isso peça ao agente para usar o armazenamento da plataforma em vez de guardar no disco. Os ficheiros guardados e os downloads são pagos com o seu saldo de créditos, conforme o tamanho e o volume de transferência; o plano Pro paga metade da tarifa do Free. Veja Armazenamento de ficheiros na documentação.

Os uploads costumam andar de mãos dadas com uma base de dados para os registos de ficheiros e com login para os ficheiros privados. Se está a construir um espaço onde os clientes trocam documentos, veja como construir um portal de clientes, e percorra a lista de segurança antes do lançamento.

Perguntas

Onde devem ser guardados os ficheiros carregados?

Em armazenamento de objetos (um serviço criado para ficheiros, muitas vezes chamado bucket), e não no disco do servidor da app nem dentro da base de dados. Na base de dados guarde apenas a chave ou URL do ficheiro, além de detalhes como nome, tamanho e proprietário.

Porque é que os meus ficheiros carregados desaparecem depois de publicar ou voltar a implementar?

A maioria das plataformas de alojamento não tem um disco local persistente: quando a app reinicia ou é reimplementada, os ficheiros escritos no disco perdem-se. Guarde os uploads em armazenamento de objetos.

Como mantenho os ficheiros carregados privados?

Não os torne legíveis publicamente. O seu servidor deve verificar se o utilizador com sessão iniciada tem permissão para ver o ficheiro e, só então, enviá-lo ou devolver uma ligação assinada de curta duração.

A Mythex suporta uploads de ficheiros?

Sim. A Mythex pode ativar o armazenamento de ficheiros num projeto quando a app precisa de uploads, nos planos Free e Pro, com um limite de 1 GB no Free. Peça ao agente a funcionalidade de upload ou escreva /storage.