Armazenamento de Arquivos

O Hedhog lida com uploads de arquivos através do FileService do @hed-hog/core. Todo conteúdo enviado passa por um único adaptador de armazenamento, selecionado uma vez via um Perfil de Integração. Troque o provedor mais tarde sem tocar no código da aplicação ou reenviar arquivos existentes.

Status: ✅ Totalmente implementado — Local, S3, GCS, Azure Blob e provedores compatíveis com S3 funcionam.

1. Crie um Perfil de Integração (tipo Storage, escolha um provedor) em Settings → Integration Profiles
2. Preencha os campos de configuração do provedor (tabelas abaixo)
3. Vá em Settings → Configurations → File Storage e defina Storage Profile para ele
4. Faça upload de um arquivo de teste em qualquer lugar do admin (ex.: seu próprio avatar) e confirme que a URL retornada realmente carrega

1. Um arquivo é enviado através de qualquer endpoint que chama FileService.upload()
2. O FileService lê a configuração file-storage-profile-id para encontrar o Perfil de Integração ativo (tipo storage)
3. Ele mapeia o JSON config específico do provedor desse perfil para o adaptador que a classe de provedor correspondente espera (disco local, S3, GCS, Azure Blob ou um serviço compatível com S3)
4. O arquivo é gravado via o adaptador, um registro é salvo na tabela file com a URL/chave resultante e metadados, e a URL pública é retornada ao cliente

Se nenhum perfil de armazenamento estiver configurado ainda, o servidor ainda sobe normalmente — ele apenas registra um aviso na inicialização, e qualquer tentativa de upload falha com No file storage profile configured até você definir um. Este é o estado esperado logo após uma instalação nova.

1. Vá em Settings → Integration Profiles → New → Tipo Storage, escolha um provedor e preencha seus campos de configuração (tabela abaixo)
2. Vá em Settings → Configurations → File Storage e defina o campo Storage Profile (file-storage-profile-id) para esse perfil
3. Os uploads passam a usar o novo provedor imediatamente — os registros file existentes e suas URLs não são migrados ou reescritos, já que o Hedhog não tem como saber se os arquivos antigos devem ser movidos

Armazena arquivos no filesystem do servidor. Adequado para desenvolvimento ou implantações de servidor único — não recomendado quando você roda mais de uma instância da API, já que uploads gravados por uma instância não ficarão visíveis para as outras.

Certifique-se de que o processo da API tem permissão de escrita nesse diretório, e que ele sobrevive a deploys/reinícios (não o aponte para dentro de um diretório que seu pipeline de deploy apaga).

Permissões IAM necessárias, restritas ao bucket:

{
  "Effect": "Allow",
  "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"],
  "Resource": "arn:aws:s3:::your-bucket/*"
}

Decida de antemão se o bucket serve arquivos publicamente ou via signed URLs — essa é uma decisão de política de bucket feita no console do S3, não uma configuração do Hedhog.

Crie a service account em IAM & Admin → Service Accounts, conceda a ela os papéis Storage Object Creator e Storage Object Viewer, depois Keys → Add Key → JSON e cole o conteúdo do arquivo baixado em key_file_json.

Encontre o nome da conta e a chave no portal do Azure em Storage account → Access keys. O container precisa já existir — o Hedhog não o cria automaticamente.

Use este provedor para qualquer coisa que fale a API do S3 mas não seja a própria AWS.

Sem endpoint definido, as requisições vão para os próprios endpoints da AWS e falharão contra qualquer serviço não-AWS — este é o único campo que as pessoas mais esquecem ao trocar do S3 para um provedor compatível.

• Faça upload de um arquivo em qualquer lugar do admin (um avatar de usuário funciona bem) e confirme que uma nova linha aparece em file
• Abra a URL retornada diretamente em uma aba do navegador — ela deve carregar o arquivo, não dar 404 ou travar