Cài đặt và sử dụng — File Storage S3 Pro

Tổng quan

Plugin @digiforce-nc/plugin-file-storage-s3-pro mở rộng khả năng lưu trữ file lên các dịch vụ tương thích S3 protocol: Amazon S3, Alibaba Cloud OSS, Tencent Cloud COS, MinIO, Cloudflare R2, v.v. Điểm khác biệt so với phiên bản cơ bản là hỗ trợ presigned URL để upload trực tiếp từ trình duyệt và signed URL để kiểm soát truy cập file riêng tư.

Bước 1: Kích hoạt plugin

Vào Settings → Plugin Manager, tìm plugin-file-storage-s3-pro và bật lên. Plugin phụ thuộc vào plugin-file-manager — hãy đảm bảo plugin đó đã được kích hoạt trước.

Bước 2: Cấu hình thông tin S3

Sau khi kích hoạt, vào Settings → File Storage và chọn loại storage S3 (Pro). Điền các thông tin sau:

Tham số	Mô tả	Bắt buộc
`accessKeyId`	Access Key ID của tài khoản AWS IAM (hoặc tương đương trên dịch vụ S3-compatible)	✅
`secretAccessKey`	Secret Access Key tương ứng	✅
`region`	Vùng (region) của bucket, ví dụ `ap-southeast-1`	✅
`bucket`	Tên bucket lưu trữ	✅
`endpoint`	Custom endpoint cho dịch vụ S3-compatible (VD: `https://minio.local:9000`). Để trống nếu dùng AWS S3	❌
`baseUrl`	URL gốc để truy cập file (nếu khác endpoint, VD: dùng CDN)	❌
`public`	Cho phép truy cập file công khai (public-read ACL) hay không	❌
`forcePathStyle`	Kiểu URL: `Virtual` (mặc định), `Path`, hoặc `Ignore` — xem giải thích bên dưới	❌
`thumbnailRule`	Query string cho thumbnail (VD: `x-oss-process=image/resize,w_200`)	❌

Chế độ Path Style

Giá trị	URL sinh ra	Khi nào dùng
Virtual (mặc định)	`https://{bucket}.s3.{region}.amazonaws.com/{key}`	AWS S3, dịch vụ hỗ trợ virtual-hosted
Path	`https://s3.{region}.amazonaws.com/{bucket}/{key}`	MinIO, một số dịch vụ self-hosted
Ignore	URL tuỳ chỉnh, bỏ bucket khỏi hostname	Trường hợp đặc biệt (proxy, CDN)

Bước 3: Cấu hình quyền IAM

Tài khoản IAM cần ít nhất các quyền sau trên bucket:

json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/*"
    }
  ]
}

Lưu ý

Nếu dùng tính năng presigned URL để upload trực tiếp từ trình duyệt, bạn cần bật CORS trên bucket. Xem phần cấu hình CORS bên dưới.

Bước 4: Cấu hình CORS cho bucket

Đối với upload trực tiếp từ trình duyệt (presigned PUT), bucket cần cho phép cross-origin requests:

json

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT", "POST"],
    "AllowedOrigins": ["https://your-domain.com"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3600
  }
]

Luồng hoạt động

Upload file (Presigned URL)

Lấy signed URL để xem/tải file

Với file riêng tư (không public), URL sẽ là signed URL có thời hạn (mặc định 3600 giây):

Các hằng số mặc định

Hằng số	Giá trị	Mô tả
`PRESIGNED_PPOST_EXPIRES`	`3600` (1 giờ)	Thời hạn presigned URL cho upload
`SIGNED_URL_EXPIRES`	`3600` (1 giờ)	Thời hạn signed URL cho download/xem
`FILE_SIZE_LIMIT_DEFAULT`	`20MB`	Giới hạn kích thước file mặc định
`STORAGE_TYPE`	`s3-compatible`	Mã loại storage đăng ký trong hệ thống

Sử dụng với MinIO

MinIO là giải pháp self-hosted phổ biến tương thích S3. Cấu hình mẫu:

Tham số	Giá trị ví dụ
`endpoint`	`http://localhost:9000`
`region`	`us-east-1` (mặc định của MinIO)
`accessKeyId`	MinIO access key
`secretAccessKey`	MinIO secret key
`bucket`	`my-bucket`
`forcePathStyle`	`Path`

Mẹo

Với MinIO, luôn chọn Path style vì MinIO mặc định không hỗ trợ virtual-hosted style.

Lưu ý quan trọng

File riêng tư (non-public) sẽ không lưu URL vào database — URL được tạo động qua signed URL mỗi khi cần truy cập.
Plugin tự động nhận diện MIME type khi upload thông qua multer-s3.
Hỗ trợ xác thực MIME type: nếu storage có cấu hình rules.mimetype, file không khớp sẽ bị từ chối khi tạo presigned URL.
Cả hai action createPresignedUrl và getFileSignedlUrls đều yêu cầu người dùng đã đăng nhập (loggedIn).