> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orquena.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Armazenamento de arquivos

> Contrato S3, opções gerenciadas, avaliação do SeaweedFS e novo papel do MinIO.

# Armazenamento de arquivos

Mídias, documentos, exports e arquivos de conhecimento serão armazenados atrás de um contrato S3-compatible próprio da Nuvexa.

## Princípio

Aplicações e domínios não conhecem o servidor físico.

```text theme={null}
Domain autorizado
    ↓
Files service
    ↓
S3-compatible provider
    ↓
Managed storage ou self-hosted storage
```

Metadata canônica permanece no PostgreSQL:

* Organização proprietária.
* Object ID e provider key.
* Tamanho e media type.
* Checksum.
* Retention class.
* Estado de validação.
* Timestamps.

## Contrato necessário

* Upload e download por streaming.
* URLs assinadas.
* Multipart upload.
* Metadata e checksums.
* Range requests.
* Copy e delete.
* Health e métricas.
* Erros normalizados.

## Segurança

* Buckets privados por padrão.
* URLs assinadas de curta duração.
* Credenciais de menor privilégio.
* Prefixos tenant-aware com IDs opacos.
* Validação de tamanho e tipo.
* Scan de arquivos quando necessário.
* Auditoria de exports e acessos privilegiados.

## Produção gerenciada

Um serviço gerenciado compatível com S3 pode ser a escolha mais segura quando disponibilidade, durabilidade e menor carga operacional forem prioritárias.

A arquitetura não exige self-hosting de todos os componentes.

## SeaweedFS

**Status:** candidato self-hosted preferencial para prova de conceito.

Motivos:

* Projeto ativo em 2026.
* Licença Apache 2.0.
* API S3-compatible.
* Arquitetura preparada para muitos arquivos e expansão horizontal.
* Topologia que pode começar compacta.

<Note>
  Ser compatível com S3 não garante comportamento idêntico à AWS em todos os casos. A Nuvexa manterá uma suíte de conformidade para o subconjunto utilizado.
</Note>

Testes obrigatórios:

* Presigned PUT e GET.
* Multipart upload.
* Range de mídia.
* Metadata e checksum.
* Reinício e recuperação.
* Backup e restore.
* Upgrade de versão.
* Isolamento por organização.

## MinIO

**Status:** compatibilidade para instalações existentes, não default.

O repositório público community do MinIO foi arquivado em abril de 2026 e passou a descrever a distribuição como source-only. Essa mudança aumenta a responsabilidade operacional e de distribuição.

A Nuvexa poderá conectar instalações existentes pelo provider S3, mas não adotará imagens flutuantes ou builds não revisados como parte padrão do Compose.

## Local filesystem

Permitido apenas em desenvolvimento isolado e testes. Não oferece durabilidade, escala ou segurança adequadas para produção.

## Migração de provider

Trocar o backend exige:

1. Inventário de objetos e metadata.
2. Cópia com verificação de checksum.
3. Reconciliação.
4. Troca controlada da configuração.
5. Período de rollback.
6. Remoção do provider anterior somente após validação.

Os IDs canônicos de arquivo não mudam.

## Links oficiais

<CardGroup cols={2}>
  <Card title="SeaweedFS" icon="database" href="https://github.com/seaweedfs/seaweedfs">
    Código, arquitetura e releases.
  </Card>

  <Card title="SeaweedFS S3 API" icon="cloud" href="https://github.com/seaweedfs/seaweedfs/wiki/Amazon-S3-API">
    Gateway e compatibilidade S3.
  </Card>

  <Card title="MinIO community" icon="archive" href="https://github.com/minio/minio">
    Estado atual do repositório público.
  </Card>

  <Card title="Amazon S3 API" icon="book-open" href="https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html">
    Referência do contrato de object storage.
  </Card>
</CardGroup>