#Storage engine: Aliyun OSS

Storage engine dựa trên Aliyun OSS, cần chuẩn bị tài khoản và quyền liên quan trước khi sử dụng.

#Tham số cấu hình

#Base URL

Điền prefix URL truy cập file, chẳng hạn custom domain đã liên kết với bucket hiện tại: https://oss.example.com. Khi truy cập PDF qua domain mặc định của Aliyun OSS, trình duyệt có thể tải file xuống. Nên liên kết custom domain trước. Xem Các vấn đề thường gặp bên dưới để biết chi tiết.

#Region

Điền Region của OSS, ví dụ: oss-cn-hangzhou.

#AccessKey ID

Điền ID của khóa truy cập được ủy quyền của Aliyun.

#AccessKey Secret

Điền Secret của khóa truy cập được ủy quyền của Aliyun.

#Bucket

Điền tên Bucket của OSS.

#Timeout

Điền thời gian timeout khi upload lên Aliyun OSS, đơn vị mili giây, mặc định là 60000 ms (tức 60 giây).

#Các vấn đề thường gặp

#PDF bị download thay vì được preview

NocoBase preview PDF khác origin trong iframe. Trình duyệt truy cập trực tiếp URL file trên OSS, vì vậy response header của OSS quyết định file được hiển thị hay download.

Nếu PDF bị download từ iframe, hãy kiểm tra request file trong panel Network của developer tools. Response có vấn đề thường có dạng:

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

Content-Type: application/pdf xác định đúng loại file, nhưng Content-Disposition: attachment yêu cầu trình duyệt tải file xuống. Domain mặc định của Aliyun OSS buộc download trong một số trường hợp. Xem tài liệu chính thức: Cấu hình PDF để preview thay vì download.

Nên cấu hình như sau:

1. Làm theo Truy cập tài nguyên OSS qua custom domain để liên kết domain với bucket
2. Cấu hình DNS và chứng chỉ HTTPS, sau đó xác nhận custom domain có thể truy cập trực tiếp file
3. Cấu hình URL truy cập cho storage engine NocoBase đang sử dụng

Đối với bước 3:

• Với engine Aliyun OSS tích hợp sẵn, đặt Base URL thành custom domain đã liên kết, chẳng hạn https://oss.example.com
• Với S3 Pro kết nối tới Aliyun OSS, upload endpoint có thể tiếp tục dùng endpoint OSS theo Region; đặt access endpoint thành custom domain và đặt Full access URL style thành Ignore

Upload một PDF mới để kiểm tra cấu hình. Nếu record file cũ lưu URL đầy đủ, hãy xác nhận URL trả về frontend đã chuyển sang custom domain.

#Hình ảnh preview bình thường nhưng nút download báo lỗi CORS

Hình ảnh thường được preview bằng <img>, còn PDF khác origin được preview bằng iframe. Cả hai đều có thể hiển thị resource mà không cần CORS response header. Tuy nhiên, nút download đọc file bằng fetch rồi tạo Blob. Request này chịu sự kiểm soát của same-origin policy trong trình duyệt.

Lỗi sau có nghĩa là OSS không trả về Access-Control-Allow-Origin cho site NocoBase hiện tại:

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.

Làm theo hướng dẫn chính thức Cấu hình CORS và tạo rule cho bucket. Đối với download từ component preview, có thể dùng các giá trị sau:

Nếu S3 Pro cũng upload file trực tiếp từ trình duyệt, hãy thêm các method như PUT và POST theo request upload thực tế trong panel Network, hoặc tạo rule upload riêng.

Sau khi lưu rule, hãy request lại file với origin của site NocoBase. Response ít nhất phải chứa:

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

Trình duyệt có thể đã cache response dùng để preview hình ảnh. Request đó không có header Origin, và response trong cache có thể không chứa Access-Control-Allow-Origin. Nếu download vẫn thất bại sau khi cấu hình CORS, hãy xóa cache của file hoặc bật Disable cache trong developer tools rồi thử lại.

#Kiểm tra response header

Dùng curl để mô phỏng request khác origin từ site NocoBase. Thay origin, URL file và tham số signature trong ví dụ bằng giá trị thực tế:

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

Kiểm tra các kết quả sau:

• Preview PDF trả về Content-Type: application/pdf và không có Content-Disposition: attachment
• Download khác origin trả về Access-Control-Allow-Origin khớp với site NocoBase
• URL file thực tế dùng custom domain thay vì domain mặc định *.oss-cn-*.aliyuncs.com

Request không có header Origin mà không nhận được CORS response header là bình thường. Khi kiểm tra CORS, hãy giữ header Origin trong ví dụ.

#Liên kết liên quan

• Preview file
• S3 Pro
• Di chuyển sang S3 Pro
• Storage engine