docs/docs/en/file-manager/storage/aliyun-oss.md
A storage engine based on Aliyun OSS. Before use, you need to prepare the relevant account and permissions.
:::warning Note
This engine does not support private access. After a file is uploaded, NocoBase generates a directly accessible URL, and anyone who has that URL can access the file.
Even if the OSS bucket itself is private, the built-in Aliyun OSS engine does not generate temporary signed URLs for file access. If you need private access, use S3 Pro. If historical files already exist, see Migrate to S3 Pro.
:::
:::info{title=Note} This section only introduces the specific parameters for the Aliyun OSS storage engine. For general parameters, see General Engine Parameters. :::
Enter the file access URL prefix, such as a custom domain bound to the current bucket: https://oss.example.com. Accessing PDFs through the default Aliyun OSS domain may cause the browser to download them. We recommend binding a custom domain first. See Common issues below for details.
Enter the region of the OSS storage, for example: oss-cn-hangzhou.
:::info{title=Note} You can view the region information of your bucket in the Aliyun OSS Console, and you only need to use the region prefix (not the full domain name). :::
Enter the ID of your Aliyun access key.
Enter the Secret of your Aliyun access key.
Enter the name of the OSS bucket.
Enter the timeout for uploading to Aliyun OSS, in milliseconds. The default is 60000 milliseconds (i.e., 60 seconds).
NocoBase previews cross-origin PDFs in an iframe. The browser accesses the OSS file URL directly, so the OSS response headers determine whether the file is displayed or downloaded.
If a PDF is downloaded from the iframe, inspect the file request in the browser developer tools. A typical problematic response looks like this:
Content-Type: application/pdf
Content-Disposition: attachment
x-oss-force-download: true
Content-Type: application/pdf identifies the file correctly, but Content-Disposition: attachment instructs the browser to download it. The default Aliyun OSS domain forces downloads in some cases. See the official Aliyun documentation: How do I configure a PDF file to be previewed instead of downloaded?.
We recommend the following configuration:
For step 3:
https://oss.example.comFull access URL style to IgnoreUpload a new PDF to verify the configuration. If an existing file record stores a complete URL, also make sure that the URL returned to the frontend now uses the custom domain.
:::tip Check the response headers
Previewing a cross-origin PDF in an iframe does not itself require CORS. Whether the PDF can be displayed inline primarily depends on Content-Type and Content-Disposition. This is separate from the CORS requirement for the download button described below.
:::
Images are usually previewed with ``, and cross-origin PDFs are previewed with an iframe. Both can display resources without CORS response headers. The download button, however, reads the file with fetch and creates a Blob for the browser to download. This request is subject to the browser's same-origin policy.
The following console error means that OSS did not return Access-Control-Allow-Origin for the current NocoBase site:
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.
Follow the official Aliyun guide Configure cross-origin resource sharing and create a CORS rule for the bucket. For downloads from the preview component, use values like these:
| Setting | Recommended value |
|---|---|
| Allowed Origins | The complete NocoBase origin, such as https://example.com |
| Allowed Methods | GET, HEAD |
| Allowed Headers | * |
| Expose Headers | ETag, Content-Disposition |
| MaxAgeSeconds | 600 |
If S3 Pro also uploads files directly from the browser, add methods such as PUT and POST according to the actual upload requests shown in the browser Network panel, or create a separate upload rule.
After saving the rule, request the file again with the NocoBase site origin. The response should include at least:
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET, HEAD
The browser may already have cached the response used for the image preview. That request did not include an Origin header, and the cached response may not contain Access-Control-Allow-Origin. If downloading still fails after you configure CORS, clear the browser cache for the file or select Disable cache in the developer tools and try again.
Use curl to simulate a cross-origin request from the NocoBase site. Replace the example origin, file URL, and signature parameters with the actual values:
curl -sS -D - -o /dev/null \
-H 'Origin: https://example.com' \
'https://oss.example.com/path/to/file.pdf?<signed-query>'
Check the following results:
Content-Type: application/pdf without Content-Disposition: attachmentAccess-Control-Allow-Origin matching the NocoBase site*.oss-cn-*.aliyuncs.com domainIt is normal for a request without an Origin header to omit CORS response headers. Keep the Origin header in the example when verifying CORS.