Giao diện
Cài đặt và sử dụng — File Manager
Tổng quan
Plugin plugin-file-manager quản lý toàn bộ vòng đời file trong hệ thống: upload, lưu trữ, tạo URL truy cập và xóa file. Hỗ trợ nhiều backend lưu trữ: Local disk, AWS S3, Alibaba OSS, Tencent COS, MinIO.
Yêu cầu
| Thành phần | Yêu cầu |
|---|---|
| Server Digiforce | Phiên bản >= 1.0 |
| Storage backend | Local (mặc định), hoặc cloud storage đã cấu hình |
Bước 1: Kích hoạt plugin
- Truy cập Settings → Plugin Manager
- Tìm
plugin-file-manager - Bật công tắc Enable
Khi cài đặt lần đầu, plugin tự động tạo storage mặc định loại local (lưu trên disk server).
Bước 2: Cấu hình Storage Backend
Vào Settings → File Storage để quản lý các backend lưu trữ.
Các loại storage được hỗ trợ
| Loại | Mô tả | Phù hợp cho |
|---|---|---|
| local | Lưu trên disk server (thư mục uploads) | Development, single-server |
| s3 | AWS S3 hoặc S3-compatible | Production, multi-region |
| ali-oss | Alibaba Cloud Object Storage | Khu vực Trung Quốc |
| tx-cos | Tencent Cloud COS | Khu vực Trung Quốc |
| minio | MinIO (self-hosted, S3-compatible) | Self-hosted production |
Cấu hình chung cho mọi storage
| Tham số | Mô tả |
|---|---|
| Name | Tên định danh (dùng để tham chiếu trong collection) |
| Title | Tên hiển thị |
| Base URL | URL gốc để truy cập file |
| Path | Thư mục con lưu file |
| Default | Đánh dấu là storage mặc định |
| Paranoid | Nếu bật, không xóa file trên storage khi xóa record |
Cấu hình S3
| Tham số | Mô tả | Ví dụ |
|---|---|---|
| Region | AWS region | ap-southeast-1 |
| Bucket | Tên bucket | my-app-uploads |
| Access Key ID | AWS access key | — |
| Secret Access Key | AWS secret key | — |
| Endpoint | Custom endpoint (cho MinIO) | https://minio.example.com |
| Thumbnail Rule | Hậu tố URL cho ảnh preview | ?x-oss-process=image/resize,w_200 |
Cấu hình Alibaba OSS
| Tham số | Mô tả |
|---|---|
| Region | OSS region |
| Bucket | Tên bucket |
| Access Key ID | Alibaba access key |
| Access Key Secret | Alibaba secret key |
| Thumbnail Rule | Rule xử lý ảnh |
Cấu hình Tencent COS
| Tham số | Mô tả |
|---|---|
| Region | COS region |
| Bucket | Tên bucket |
| Secret ID | Tencent secret ID |
| Secret Key | Tencent secret key |
Biến môi trường
Nên lưu credentials (access key, secret key) trong Environment Variables ($env) thay vì ghi trực tiếp. Cấu hình storage hỗ trợ template: {{$env.S3_ACCESS_KEY}}.
Bước 3: Sử dụng Upload
Qua giao diện (Form Field)
- Trong collection, tạo field loại Attachment
- Khi user điền form, trường attachment hiển thị nút upload
- File được upload qua API
attachments:upload - Metadata lưu vào bảng
attachments, file lưu vào storage backend
Qua API
typescript
// Upload file
const formData = new FormData();
formData.append('file', fileBlob);
await agent.resource('attachments').upload({
values: formData,
});Quy tắc Upload (Rules)
| Quy tắc | Mô tả | Mặc định |
|---|---|---|
| Max file size | Kích thước tối đa cho mỗi file | Theo cấu hình storage |
| MIME type filter | Chỉ cho phép các loại file cụ thể | Tất cả (*) |
Plugin sử dụng mime-match để kiểm tra MIME type:
image/*— chỉ cho phép ảnhapplication/pdf— chỉ PDFimage/*,application/pdf— ảnh và PDF
Quản lý File
URL Resolution
Khi truy vấn attachment, plugin tự động tạo URL hoàn chỉnh:
URL = baseUrl + path + filenameVới ảnh, nếu storage có thumbnailRule, URL preview sẽ thêm rule đó vào cuối.
Xóa File
Khi record attachment bị xóa:
- Plugin tìm storage tương ứng (qua
storageId) - Gọi
storage.delete()để xóa file khỏi backend - Nếu storage có
paranoid: true, file không bị xóa (chỉ xóa record)
WARNING
Không thể xóa storage mặc định. Không thể xóa storage đang được sử dụng bởi collection.
File Rename Mode
Plugin hỗ trợ đổi tên file khi upload để tránh trùng (theo cấu hình renameMode của storage).
Phân quyền (ACL)
| Action | Quyền |
|---|---|
attachments:upload | loggedIn (mọi user đã đăng nhập) |
attachments:create | loggedIn |
attachments:update | Chỉ người tạo (createdById = currentUser.id) |
attachments:destroy | Chỉ người tạo |
storages:* | Admin (snippet pm.file-manager.storages) |
storages:getBasicInfo | loggedIn |
storages:check | loggedIn |
Cache và Đồng bộ
- Storage được cache trong memory (
storagesCache) - Cache tự động reload khi storage thêm/sửa/xóa
- Trong môi trường multi-instance, sync message
reloadStoragesđược gửi đến tất cả instance
Lưu ý
- Với production, khuyến nghị dùng S3/OSS thay vì local (tránh mất file khi deploy lại)
- Nếu dùng reverse proxy (Nginx), cần cấu hình
client_max_body_sizephù hợp - File URL/preview không thể sửa sau khi upload (bảo vệ bởi
beforeUpdatehook) - Template
filetrong collection cho phép tạo collection lưu trữ file tùy chỉnh (ngoàiattachments)