Principais pontos
- Escolha o modelo de armazenamento antes do provedor: armazenamento de objetos, armazenamento colaborativo de arquivos e servidores de transferência de arquivos resolvem problemas operacionais diferentes.
- Trate importação e exportação como limites de confiança separados, com credenciais de Template de privilégio mínimo, limitadas somente aos caminhos e às ações de que cada fluxo de trabalho precisa.
- Não deduza acesso público a partir de uma URL retornada; a política do bucket, as configurações de compartilhamento, as URLs assinadas e as permissões do servidor determinam se um resultado pode ser recuperado.
Escolher uma integração de armazenamento é uma decisão de arquitetura, não a busca por um nome de provedor. Armazenamentos de objetos, serviços de arquivos colaborativos e servidores de transferência de arquivos expõem modelos de permissão, garantias de URL, comportamentos de listagem e modos de falha diferentes. Este guia agrupa os destinos com suporte de acordo com essas diferenças para que você escolha um fluxo de trabalho de forma deliberada, em vez de copiar exemplos quase idênticos.
O que mais importa
- Planeje importações de pastas grandes com base no contrato de recursão e paginação de cada Robot, em vez de presumir que todos os provedores listam árvores da mesma forma.
- Mantenha identificadores estáveis de ativos e Assembly IDs na sua aplicação, porque nomes de arquivo, pastas, links e metadados do provedor podem mudar de forma independente.
Comece pelo modelo de armazenamento, não pelo logotipo do provedor
O armazenamento de objetos é a escolha natural para bibliotecas de mídia pertencentes à aplicação. Amazon S3, Azure Blob Storage, Backblaze B2, Cloudflare R2, DigitalOcean Spaces, Google Cloud Storage, MEGA S4 Object Storage, MinIO, OpenStack Swift, Supabase Storage, Tigris, Wasabi e Rackspace Cloud Files expõem destinos orientados a buckets ou contêineres por meio de Robots da Transloadit próprios de cada um. Ainda assim, eles diferem em credenciais, campos de endpoint ou região, controles de acesso e URLs de resultado, de modo que “armazenamento de objetos” descreve a arquitetura, e não um formato de configuração compartilhado.
Box e Dropbox são serviços de arquivos em nuvem orientados a contas e pastas. As pastas, os links e os sistemas de permissão voltados ao usuário desses serviços podem ser valiosos quando pessoas trabalham diretamente com os arquivos exportados. Já FTP e SFTP têm como alvo servidores de transferência de arquivos e convenções de sistema de arquivos existentes. Escolha esses modelos porque um parceiro ou sistema legado os exige, e não porque as strings de caminho deles por acaso se parecem com chaves de objeto.
Armazenamento de objetos
Prefira este modelo para ativos da aplicação endereçados por chaves estáveis, regras de ciclo de vida e política de bucket ou contêiner controlada pelo provedor.
Armazenamento colaborativo
Prefira Box ou Dropbox quando pastas de conta e links gerenciados pelo provedor fizerem parte da experiência de produto exigida.
Transferência de arquivos
Prefira SFTP ou FTP quando o sistema receptor for definido por uma conta de servidor, uma árvore de diretórios e um contrato de transferência estabelecido.
Associe cada destino ao seu par de Robots da Transloadit
O nome do destino corresponde a um Robot de importação e a um Robot de armazenamento: /s3/import e /s3/store, /azure/import e /azure/store, /backblaze/import e /backblaze/store, /box/import e /box/store, /cloudflare/import e /cloudflare/store, /digitalocean/import e /digitalocean/store, e /dropbox/import e /dropbox/store. O mesmo pareamento se aplica a /ftp, /google, /mega, /minio, /sftp, /supabase, /swift, /tigris, /wasabi e /cloudfiles, como /sftp/import com /sftp/store.
Um Robot de importação cria arquivos que Steps posteriores podem processar. Um Robot de armazenamento consome resultados selecionados de Steps e os grava no destino. Essa direção importa ao projetar permissões e observabilidade: uma transformação bem-sucedida não prova que a exportação foi bem-sucedida, e uma importação bem-sucedida não prova que a origem continuará disponível após o processamento. Registre o estado final da Assembly e inspecione o resultado do Step de armazenamento do qual você realmente depende.
Entradas explícitas
A relação use seleciona os arquivos dos Steps anteriores; o Robot de armazenamento não exporta automaticamente todos os resultados da Assembly.
Destino explícito
Um Step específico do provedor é o limite em que os requisitos de caminho, acesso, metadados e credenciais passam a fazer parte do contrato do fluxo de trabalho.
Conclusão explícita
A aplicação deveria marcar um ativo como durável somente depois que o resultado de armazenamento exigido for concluído e a identidade de destino desse resultado for registrada.
Mantenha as credenciais de armazenamento com escopo restrito e sob controle do servidor
Crie o acesso ao provedor nas credenciais de Template e faça referência ao registro pelo nome a partir de um Template salvo. O provedor continua determinando o que essa credencial pode fazer. Restrinja-a ao menor conjunto de caminhos de origem e de destino, operações, buckets, contêineres ou pastas de que o fluxo de trabalho precisa. Quando um provedor permite credenciais separadas de leitura e de escrita, essa separação oferece um limite de revogação mais claro e reduz o efeito de um Template equivocado.
Não envie chaves brutas do provedor em Assembly Instructions controladas pelo navegador nem use campos do cliente para selecionar um destino sem restrições. O código de servidor confiável deveria autorizar o usuário, escolher um Template revisado e fornecer apenas campos de negócio delimitados, como um identificador de ativo. Se vários tenants ou destinos compartilharem o mesmo formato de fluxo de trabalho, mantenha o mapeamento de cada tenant para o Template ou a credencial aprovados nesse limite confiável.
Privilégio mínimo
Conceda permissão de listagem e leitura somente onde uma importação precisar delas, e de escrita somente onde uma exportação tiver permissão para criar objetos.
Domínios de confiança separados
Use registros de credenciais diferentes quando for recomendável que ambientes, tenants, prefixos de origem ou permissões de destino sejam revogados de forma independente.
Seleção confiável
Mantenha nomes arbitrários de Robots, hosts de endpoint e escolhas de credenciais fora de requisições controladas por um navegador ou agente não confiável.
Projete deliberadamente a entrega pública, privada, assinada e com URL personalizada
As integrações de provedores não compartilham um vocabulário comum de controle de acesso. O Amazon S3 expõe tanto acl quanto sign_urls_for, enquanto o Cloudflare R2 expõe sign_urls_for, mas nenhuma opção acl. O Azure usa assinaturas de acesso compartilhado. O padrão do Robot do Amazon S3 é public-read; em um bucket com o Block Public Access ativado, esse padrão pode falhar com um erro de permissão em vez de publicar o objeto. Para entrega privada no S3, use private em buckets que respeitam ACLs de objeto, ou use bucket-default quando as ACLs estiverem desativadas ou o Block Public Access estiver ativado. O valor bucket-default delega à política do bucket e elimina a necessidade de s3:PutObjectAcl. O Robot de armazenamento do Wasabi usa private como padrão quando acl não está definido; defina public-read explicitamente apenas para entrega pública no Wasabi. O Wasabi não oferece suporte a bucket-default. O Box e o Dropbox podem criar links de compartilhamento do provedor. Outros destinos dependem principalmente da configuração do bucket, do contêiner, da pasta ou do servidor fora do Assembly Step.
Trate permissão e geração de endereço como questões separadas. Um prefixo de URL ou um modelo de URL pode fazer um resultado apontar para uma CDN ou para um hostname da aplicação, mas reescrever um endereço não configura a origem, não concede acesso de leitura nem copia o arquivo. Por outro lado, um objeto privado pode ter uma URL sintaticamente válida que retorna corretamente um erro de autorização. Verifique o caminho exato de consumo, o comportamento de expiração e como funciona a revogação no provedor selecionado.
Objetos públicos
Use a política do provedor ou uma ACL explícita somente depois de decidir se a recuperação anônima faz de fato parte do contrato do produto.
Acesso assinado
Para acesso controlado, teste a expiração da assinatura, a diferença de relógio, as respostas em cache e o que acontece depois que um objeto é substituído ou excluído.
URLs personalizadas
Trate hostnames de CDN e modelos de URL personalizados como configuração de roteamento que precisa estar de acordo com as permissões reais de leitura do provedor.
Crie um Step de exportação claro antes de adicionar variações de provedor
Um fluxo de trabalho de armazenamento deveria deixar o fluxo de dados evidente. O Template a seguir recebe um upload, cria um derivado WebP com tamanho limitado e exporta apenas esse derivado para o Cloudflare R2. O nome da credencial é resolvido dentro da conta Transloadit, enquanto o caminho usa Assembly Variables para evitar chaves no provedor escolhidas pelo cliente. Um Template de produção deveria adicionar a validação, a nomenclatura, os metadados e a política de sobrescrita exigidos pela aplicação.
O mesmo formato de grafo pode orientar outro destino, mas o Step do provedor não é uma configuração intercambiável. Substitua o Robot de armazenamento somente depois de ler o schema dele e decidir como devem funcionar as credenciais, a seleção de bucket ou pasta, o acesso, as URLs e as colisões. Mantenha Templates revisados separados quando as diferenças forem operacionalmente importantes, mesmo que os Steps de transformação continuem idênticos.
{
"steps": {
":original": {
"robot": "/upload/handle"
},
"optimized": {
"use": ":original",
"robot": "/image/resize",
"resize_strategy": "fit",
"width": 1600,
"height": 1600,
"format": "webp"
},
"exported": {
"use": "optimized",
"robot": "/cloudflare/store",
"credentials": "my-r2-credentials",
"path": "media/${assembly.id}/${file.id}.${file.ext}"
}
}
}Trate importações de pastas como um trabalho de inventário retomável
Uma importação de arquivo único pode esconder a parte difícil de uma migração. Os provedores diferem na forma como representam pastas ou prefixos, se a travessia é recursiva por padrão ou opcional, quantas entradas uma página retorna e qual valor de continuação solicita a próxima página. Leia o schema do Robot de importação selecionado e teste uma estrutura aninhada de dados de teste maior do que uma página antes de depender dele para uma carga retroativa.
Persista a intenção e o progresso da migração no seu próprio sistema. Registre a identidade da origem, a página ou o lote atual, a identidade esperada no destino, o Assembly ID e o resultado final. Faça novas tentativas de forma idempotente e reconcilie as contagens em vez de presumir que listar novamente uma raiz em constante crescimento identificará, de forma barata, cada objeto que ficou de fora. Para ingestão contínua, prefira eventos duráveis ou um manifesto armazenado em banco de dados a varreduras repetidas do bucket inteiro.
Dados de teste representativos
Teste pastas vazias, nomes aninhados, caracteres incomuns, nomes-base duplicados e uma listagem que ultrapasse pelo menos um limite de página.
Pontos de controle duráveis
Armazene o progresso fora do processo para que a reinicialização de um worker não force uma nova listagem completa nem pule silenciosamente a página atual.
Reconciliação
Compare os registros esperados na origem com os registros concluídos no destino e exponha explicitamente objetos ausentes, duplicados ou substituídos.
Valide a recuperação de falhas e a responsabilidade pelo ciclo de vida
Teste credenciais erradas, uma origem ausente, um endpoint indisponível, um caminho de destino negado, uma colisão de nomes, uma assinatura expirada e uma exportação parcial de vários arquivos. As notificações podem ser reenviadas, então o tratamento da conclusão precisa ser idempotente. Mantenha o Assembly ID junto ao ativo da aplicação e decida quais estados finais permitem nova tentativa automática, quais exigem revisão de um operador e quais deveriam deixar a origem intacta.
O armazenamento exportado e o armazenamento temporário da Transloadit têm responsáveis e ciclos de vida diferentes. Um resultado de Assembly concluído não é um backup, e excluir um registro da aplicação não exclui automaticamente as cópias em todos os provedores, caches ou locais temporários de processamento. Documente a retenção, a substituição e a exclusão da origem, do derivado, dos metadados do resultado e do endereço público e, depois, teste essas operações com o mesmo cuidado dedicado ao cenário ideal inicial, em que tudo dá certo.
Conclusão à prova de duplicidade
Use uma regra de idempotência no nível da aplicação para que um callback repetido ou uma nova tentativa não crie um segundo ativo durável não intencional.
Observabilidade por Step
Monitore a importação, a transformação e a exportação separadamente para que um Step anterior bem-sucedido não mascare uma falha na transferência para o armazenamento durável.
Contrato de ciclo de vida
Documente qual sistema exclui cada arquivo de origem, resultado temporário, derivado, resposta em cache e registro da aplicação, incluindo quando isso acontece.
Detalhes técnicos que vale a pena conhecer
- Os destinos compatíveis usam pares de Robots de importação e armazenamento, incluindo Amazon S3, Azure Blob Storage, Backblaze B2, Box, Cloudflare R2, DigitalOcean Spaces, Dropbox, FTP, Google Cloud Storage, MEGA S4 Object Storage, MinIO, SFTP, Supabase Storage, OpenStack Swift, Tigris, Wasabi e Rackspace Cloud Files.
- Um Step de armazenamento exporta apenas os resultados selecionados pelo seu valor
use; portanto, exportar um original, um derivado ou ambos é determinado pelo grafo da Assembly, e não pelo provedor de destino. - As credenciais de Template são registros no nível da conta referenciados pelo nome, o que mantém as chaves do provedor fora dos bundles do navegador e das Assembly Instructions, embora a própria credencial ainda precise ter o escopo definido no provedor.
- Os controles de acesso variam conforme o provedor: o Amazon S3 expõe tanto
aclquantosign_urls_for, o Cloudflare R2 expõesign_urls_for, mas nenhuma opçãoacl, o Azure pode gerar assinaturas de acesso compartilhado, e o Box ou o Dropbox podem criar links de compartilhamento. - Um prefixo de URL personalizado ou um modelo de URL altera o endereço informado no resultado de uma Assembly; por si só, ele não concede acesso, não configura uma CDN, não faz upload de outra cópia nem comprova que o objeto pode ser lido publicamente.
- Os Robots de importação diferem na navegação de diretórios, na listagem recursiva, no tamanho de página e no comportamento do token de continuação; por isso, uma migração em massa deve seguir o schema do Robot selecionado e persistir o progresso fora de um único loop em memória.
- FTP e SFTP armazenam arquivos no sistema de arquivos de um servidor, e não em um namespace de armazenamento de objetos; o SFTP oferece suporte a autenticação por chave e à configuração do modo de arquivo, enquanto o FTP depende do seu próprio modelo de transporte e de permissões do servidor.
- Os resultados temporários de Assembly não são armazenamento durável da aplicação; por isso, é recomendável exportar e reconciliar com o sistema de registro da aplicação todo resultado que precise sobreviver à janela de retenção temporária.
Uma abordagem prática
- 1
Classifique o destino por modelo de armazenamento, região exigida, limite de propriedade e caminho de recuperação esperado.
- 2
Crie credenciais de Template de privilégio mínimo e teste as permissões de importação e de armazenamento de forma independente.
- 3
Verifique o comportamento de objetos privados, públicos, assinados, expirados, substituídos e excluídos com arquivos representativos.
- 4
Teste paginação, importações recursivas, novas tentativas, exportações duplicadas e falhas parciais antes de migrar o tráfego de produção.
Quando a Transloadit é útil
Use um Robot nativo de importação ou de armazenamento da Transloadit quando for recomendável que um fluxo de trabalho mova arquivos entre o processamento e um serviço de armazenamento com suporte sem que sua aplicação faça proxy dos bytes. Escolha primeiro o destino com base nos requisitos operacionais e, depois, configure explicitamente as credenciais e o comportamento de acesso dele.
Limite da arquitetura
A Transloadit importa arquivos, processa-os e exporta os resultados selecionados por meio do Robot configurado. O destino continua responsável pelo armazenamento durável, pela política de bucket ou pasta, pelo ciclo de vida dos objetos, pela replicação e pela entrega. Sua aplicação continua responsável pela autorização de usuários, pelos registros de ativos, pelas decisões de publicação e pela exclusão em todas as cópias.
Perguntas frequentes
Uma URL de resultado significa que o arquivo exportado é público?
Não. O endereço em um resultado de Assembly descreve onde um provedor ou um mapeamento de URL configurado diz que o objeto está. Se quem faz a chamada consegue recuperá-lo ainda depende da política do bucket, de uma ACL do objeto, de um link de compartilhamento do provedor, de uma assinatura válida ou das permissões do sistema de arquivos e do servidor web. Teste o acesso a partir de um cliente não autenticado, em vez de tratar a presença de url ou ssl_url como uma verificação de permissão.
Importações e exportações devem compartilhar uma única credencial?
Geralmente não. Dê a uma credencial de importação apenas acesso de leitura e listagem ao prefixo de origem necessário, e dê a uma credencial de exportação apenas acesso de escrita ao prefixo de destino correspondente. Registros separados limitam o impacto de uma credencial vazada ou mal configurada e facilitam a interpretação dos logs de auditoria do provedor. Uma única credencial mais abrangente pode ser conveniente, mas a conveniência não comprova que as duas direções exigem as mesmas permissões.
Quando devo usar SFTP ou FTP em vez de armazenamento de objetos?
Use uma integração nativa quando ela corresponder ao provedor e for recomendável que o fluxo de trabalho evite que os bytes dos arquivos passem pelos servidores da aplicação como proxy. Escolha SFTP quando um contrato existente com um parceiro exigir transferência de arquivos via SSH ou um sistema de arquivos em servidor. Use FTP apenas para compatibilidade com um endpoint que não consiga oferecer uma rota suportada mais segura e, nesse caso, restrinja a conta, o caminho de destino e a exposição de rede tanto quanto o servidor permitir.
Como minha aplicação deve rastrear arquivos entre provedores?
Armazene no seu banco de dados o Assembly ID, o ID do ativo independente de provedor, a chave ou o caminho de destino e a versão pretendida. Trate as notificações como eventos que podem ser repetidos e torne o tratamento da conclusão idempotente. Em uma importação grande, persista o progresso por página ou lote e reconcilie os ativos esperados com as exportações concluídas. Nomes de pastas e URLs de compartilhamento do provedor são dados de apresentação úteis, mas são identificadores primários frágeis.
Posso trocar de provedor alterando apenas o nome do Robot?
Não com segurança, sem revisar o contrato. O grafo da Assembly pode continuar parecido, mas credenciais, campos de bucket ou contêiner, regras de caminho, configurações de acesso, campos de URL de resultado, recursão e paginação podem ser diferentes. Crie um adaptador de provedor em código confiável da aplicação ou mantenha Templates revisados para cada destino. Não permita que um navegador selecione um Robot arbitrário nem injete credenciais de armazenamento em Instructions que, de outra forma, seriam confiáveis.