Storage engine: S3 (Pro)

Lưu trữ tệp: S3 (Pro)Professional Edition+

Giới thiệu

Trên cơ sở plugin File Manager, bổ sung hỗ trợ loại lưu trữ file tương thích giao thức S3. Bất kỳ dịch vụ Object Storage nào hỗ trợ giao thức S3 đều có thể tích hợp dễ dàng, ví dụ Amazon S3, Aliyun OSS, Tencent COS, MinIO, Cloudflare R2, v.v., nâng cao thêm tính tương thích và linh hoạt của dịch vụ lưu trữ.

Tính năng nổi bật

Upload từ client: Quá trình upload file không cần thông qua server NocoBase, kết nối trực tiếp với dịch vụ lưu trữ file, mang lại trải nghiệm upload hiệu quả và nhanh chóng hơn.
Truy cập riêng tư: Mặc định sử dụng URL có chữ ký kèm thời hạn. Cũng có thể tạo URL không chữ ký cho Bucket công khai.

Tình huống sử dụng

Quản lý bảng file: Quản lý và lưu trữ tập trung tất cả các file đã upload, hỗ trợ nhiều loại file và phương thức lưu trữ, thuận tiện cho việc phân loại và tìm kiếm file.
Lưu trữ field attachment: Dùng để lưu trữ dữ liệu file đính kèm upload trong form hoặc bản ghi, hỗ trợ liên kết với bản ghi dữ liệu cụ thể.

Cấu hình plugin

Bật plugin plugin-file-storage-s3-pro
Click "Setting-> FileManager" để vào File Manager Settings
Click nút "Add new", chọn "S3 Pro"

Sau khi popup xuất hiện, bạn sẽ thấy có khá nhiều nội dung form cần điền. Có thể tham khảo tài liệu sau để lấy thông tin tham số liên quan của dịch vụ file tương ứng và điền chính xác vào form.

Cấu hình URL

Ngoài các tùy chọn chung của File Manager gồm "URL NocoBase", "URL gốc" và "Cho phép truy cập công khai", S3 Pro còn cho phép cấu hình riêng định dạng URL upload, URL truy cập và việc có sử dụng URL có chữ ký hay không. Xem Tổng quan Storage Engine để biết ý nghĩa của các tùy chọn chung.

Các tùy chọn này kiểm soát những giai đoạn khác nhau:

"URL NocoBase / URL gốc" kiểm soát địa chỉ mà bản ghi file trả về
"Cho phép truy cập công khai" kiểm soát việc có kiểm tra quyền xem của bản ghi file khi truy cập URL NocoBase hay không
"Không sử dụng URL có chữ ký" kiểm soát việc Object Storage có xác thực chữ ký URL hay không

Các cấu hình này có thể kết hợp độc lập. Cấu hình mặc định được khuyến nghị là dùng URL NocoBase, không tích chọn "Cho phép truy cập công khai" và giữ URL có chữ ký được bật.

Cấu hình URL S3 Pro

Cách chọn

Tình huống sử dụng	URL file	Cho phép truy cập công khai	Không sử dụng URL có chữ ký
File cần tuân theo quyền role và quyền dữ liệu trong khi Bucket vẫn riêng tư	URL NocoBase	Không tích chọn	Không tích chọn
Cần địa chỉ file NocoBase công khai trong khi Bucket vẫn riêng tư	URL NocoBase	Tích chọn	Không tích chọn
Dịch vụ bên ngoài cần truy cập tạm thời vào địa chỉ storage	URL gốc	Không áp dụng	Không tích chọn; cấu hình Access URL expiration
Bucket công khai hoặc CDN cần địa chỉ gốc không chữ ký	URL gốc	Không áp dụng	Tích chọn

Định dạng URL tải lên

"Định dạng URL tải lên" kiểm soát URL S3 mà client sử dụng khi upload file. Chọn định dạng được dịch vụ storage hỗ trợ. Form cấu hình hiển thị ví dụ dựa trên Endpoint, Bucket và đường dẫn hiện tại:

"Bucket as subdomain": https://bucket-name.s3.example.com/path/to/object
"Bucket as subpath": https://s3.example.com/bucket-name/path/to/object
"Ignore bucket": https://upload.example.com/path/to/object

Định dạng URL truy cập

"Định dạng URL truy cập" kiểm soát việc Bucket xuất hiện trong domain, trong đường dẫn hay không xuất hiện trong URL khi S3 Pro tạo địa chỉ truy cập file. Có cùng ba định dạng như URL upload nhưng có thể cấu hình riêng—ví dụ upload sử dụng S3 Endpoint, còn truy cập sử dụng domain CDN không chứa Bucket.

Tùy chọn này ảnh hưởng đến URL gốc và địa chỉ storage mà URL NocoBase cuối cùng chuyển hướng đến, nhưng không thay đổi định dạng của chính URL NocoBase.

Không sử dụng URL có chữ ký

S3 Pro mặc định sử dụng URL có chữ ký. URL gốc được tạo sẽ chứa tham số chữ ký, ví dụ:

https://bucket-name.s3.example.com/path/to/object?X-Amz-Signature=xxxx

URL có chữ ký có hiệu lực trong thời gian được cấu hình tại "Access URL expiration", và Bucket có thể giữ riêng tư. Khi sử dụng URL NocoBase, NocoBase tạo hoặc chuyển hướng đến địa chỉ có chữ ký sau khi kiểm tra quyền thành công.

Khi tích chọn "Không sử dụng URL có chữ ký", S3 Pro tạo địa chỉ không có tham số chữ ký. Bucket và object đã upload phải cho phép đọc công khai, đồng thời "Access URL expiration" không còn hiệu lực.

"Không sử dụng URL có chữ ký" chỉ kiểm soát việc dịch vụ storage xác thực chữ ký, không thay đổi quyền của bản ghi NocoBase. Nếu chọn URL NocoBase và không tích chọn "Cho phép truy cập công khai", request vẫn phải vượt qua kiểm tra quyền NocoBase trước.

Cấu hình nhà cung cấp

Amazon S3

Tạo Bucket

Mở https://ap-southeast-1.console.aws.amazon.com/s3/home để vào S3 Console
Click nút "Create bucket" bên phải

Điền Bucket Name, các field khác có thể giữ mặc định, cuộn xuống cuối trang, click nút "Create" để hoàn tất tạo.

Cấu hình CORS

Vào danh sách buckets, tìm và click vào Bucket vừa tạo để vào trang chi tiết

Click tab "Permission", sau đó cuộn xuống tìm phần cấu hình CORS

Điền cấu hình sau (có thể tự tinh chỉnh cấu hình) và lưu

[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "POST",
            "PUT"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": [
            "ETag"
        ],
        "MaxAgeSeconds": 3000
    }
]

Lấy AccessKey, SecretAccessKey

Click nút "Security credentials" góc trên bên phải

Cuộn xuống, tìm phần "Access Keys", click nút "Create Access Key".

Click Đồng ý (ở đây minh họa với tài khoản chính, khuyến nghị sử dụng IAM trong môi trường chính thức).

Lưu Access key và Secret access key hiển thị trong trang

Lấy và cấu hình tham số

AccessKey ID và AccessKey Secret là các giá trị bạn đã lấy được trong thao tác trên, hãy điền chính xác
Vào panel properties của trang chi tiết bucket, bạn có thể lấy được thông tin tên Bucket và Region.

Truy cập công khai không chữ ký (Tùy chọn)

Chỉ cấu hình khi cần URL không chữ ký, vì Bucket và object đã upload phải cho phép đọc công khai. Nếu chỉ cần chia sẻ URL NocoBase công khai, hãy tích chọn "Cho phép truy cập công khai" và tiếp tục dùng URL có chữ ký; không cần mở công khai Bucket.

Vào panel Permissions, cuộn xuống đến Object Ownership, click chỉnh sửa, bật ACLs

Cuộn đến Block public access, click chỉnh sửa, đặt thành cho phép ACLs điều khiển

Trong NocoBase tích chọn "Không sử dụng URL có chữ ký"

Cấu hình thumbnail (Tùy chọn)

Cấu hình này là tùy chọn, áp dụng khi cần tối ưu kích thước hoặc hiệu ứng preview hình ảnh. Lưu ý, phương án triển khai này có thể phát sinh chi phí bổ sung, chi phí cụ thể vui lòng tham khảo các điều khoản liên quan của AWS.

Truy cập Dynamic Image Transformation for Amazon CloudFront.
Click nút Launch in the AWS Console ở cuối trang để bắt đầu triển khai phương án.
Theo hướng dẫn để hoàn tất cấu hình, một số tùy chọn sau cần đặc biệt lưu ý:
1. Khi tạo stack, bạn cần chỉ định tên Bucket Amazon S3 chứa hình ảnh nguồn. Vui lòng điền tên Bucket bạn đã tạo trước đó.
2. Nếu bạn đã chọn triển khai Demo UI, sau khi triển khai hoàn tất có thể test tính năng xử lý hình ảnh thông qua giao diện này. Trong AWS CloudFormation Console, chọn stack của bạn, vào tab "Outputs", tìm giá trị tương ứng với key DemoUrl, click vào liên kết đó để mở giao diện demo.
3. Phương án này sử dụng thư viện Node.js sharp để xử lý hình ảnh hiệu quả. Bạn có thể tải mã nguồn từ GitHub repository và tùy chỉnh theo nhu cầu.
Sau khi cấu hình hoàn tất, chờ trạng thái triển khai chuyển sang CREATE_COMPLETE là được.
Trong cấu hình NocoBase, có một số lưu ý sau:
1. Thumbnail rule: Điền tham số liên quan đến xử lý hình ảnh, ví dụ ?width=100. Cụ thể có thể tham khảo Tài liệu AWS.
2. Access endpoint: Điền giá trị ApiEndpoint trong Outputs sau khi triển khai.
3. "Định dạng URL truy cập": Chọn "Ignore bucket" vì tên Bucket đã có trong cấu hình và không cần xuất hiện trong URL truy cập.

Ví dụ cấu hình