#Motor de Armazenamento: Aliyun OSS

Um motor de armazenamento baseado no Aliyun OSS. Antes de usá-lo, você precisará preparar a conta e as permissões necessárias.

#Parâmetros de Configuração

#URL base

Informe o prefixo da URL de acesso aos arquivos, como um domínio personalizado vinculado ao bucket atual: https://oss.example.com. O domínio padrão do Aliyun OSS pode fazer o navegador baixar arquivos PDF. Recomendamos vincular primeiro um domínio personalizado. Consulte Problemas comuns abaixo.

#Região

Insira a região de armazenamento do OSS, por exemplo: oss-cn-hangzhou.

#AccessKey ID

Insira o ID da sua chave de acesso do Aliyun.

#AccessKey Secret

Insira o Secret da sua chave de acesso do Aliyun.

#Bucket

Insira o nome do bucket do OSS.

#Tempo Limite

Insira o tempo limite para upload no Aliyun OSS, em milissegundos. O valor padrão é 60000 milissegundos (ou seja, 60 segundos).

#Problemas comuns

#O PDF é baixado em vez de ser pré-visualizado

O NocoBase pré-visualiza PDFs de outra origem em um iframe. O navegador acessa diretamente a URL do OSS, portanto os cabeçalhos de resposta determinam se o arquivo será exibido ou baixado.

Se o PDF for baixado pelo iframe, verifique a solicitação no painel «Rede» das ferramentas de desenvolvimento. Uma resposta problemática típica é:

Content-Type: application/pdf
Content-Disposition: attachment
x-oss-force-download: true

Content-Type: application/pdf identifica o arquivo corretamente, mas Content-Disposition: attachment instrui o navegador a baixá-lo. O domínio padrão do Aliyun OSS força downloads em alguns casos. Consulte a documentação oficial: Configurar um PDF para ser pré-visualizado em vez de baixado.

Recomendamos esta configuração:

1. Siga Acessar recursos do OSS por um domínio personalizado para vincular um domínio ao bucket
2. Configure o DNS e o certificado HTTPS e confirme que o domínio acessa o arquivo diretamente
3. Configure a URL de acesso no mecanismo de armazenamento usado pelo NocoBase

Para a etapa 3:

• No mecanismo integrado Aliyun OSS, defina URL base como o domínio vinculado, por exemplo https://oss.example.com
• No S3 Pro conectado ao Aliyun OSS, o endpoint de upload pode continuar usando o endpoint regional do OSS; defina o endpoint de acesso como o domínio personalizado e Full access URL style como Ignore

Envie um novo PDF para verificar a configuração. Se um registro existente armazenar uma URL completa, confirme também que a URL retornada ao frontend passou a usar o domínio personalizado.

#A imagem aparece, mas o botão de download informa um erro CORS

As imagens normalmente são exibidas com <img> e os PDFs de outra origem com um iframe. Ambos podem exibir recursos sem cabeçalhos CORS. No entanto, o botão de download lê o arquivo com fetch e cria um Blob. Essa solicitação está sujeita à política de mesma origem do navegador.

O erro a seguir indica que o OSS não retornou Access-Control-Allow-Origin para o site NocoBase atual:

Access to fetch at 'https://oss.example.com/path/to/file.jpg' from origin
'https://example.com' has been blocked by CORS policy:
No 'Access-Control-Allow-Origin' header is present on the requested resource.

Siga o guia oficial Configurar CORS e crie uma regra para o bucket. Para downloads pelo componente de pré-visualização, use valores como estes:

Se o S3 Pro também enviar arquivos diretamente pelo navegador, adicione métodos como PUT e POST de acordo com as solicitações reais mostradas no painel «Rede», ou crie uma regra de upload separada.

Depois de salvar a regra, solicite o arquivo novamente com o origin do site NocoBase. A resposta deve incluir pelo menos:

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET, HEAD

O navegador pode já ter armazenado em cache a resposta usada para exibir a imagem. Essa solicitação não incluía o cabeçalho Origin, e a resposta em cache pode não conter Access-Control-Allow-Origin. Se o download continuar falhando depois da configuração de CORS, limpe o cache do arquivo ou ative «Desabilitar cache» nas ferramentas de desenvolvimento e tente novamente.

#Verificar os cabeçalhos de resposta

Use curl para simular uma solicitação entre origens a partir do site NocoBase. Substitua o origin, a URL e os parâmetros de assinatura do exemplo pelos valores reais:

curl -sS -D - -o /dev/null \
  -H 'Origin: https://example.com' \
  'https://oss.example.com/path/to/file.pdf?<signed-query>'

Verifique os seguintes resultados:

• A pré-visualização retorna Content-Type: application/pdf sem Content-Disposition: attachment
• O download entre origens retorna Access-Control-Allow-Origin correspondente ao site NocoBase
• A URL real usa o domínio personalizado em vez do domínio padrão *.oss-cn-*.aliyuncs.com

É normal que uma solicitação sem Origin não receba cabeçalhos CORS. Mantenha o cabeçalho Origin do exemplo ao verificar a configuração.

#Links relacionados

• Pré-visualização de arquivos
• S3 Pro
• Migrar para S3 Pro
• Mecanismos de armazenamento