Giao diện
@digiforce-nc/plugin-file-manager
Plugin quản lý file upload/storage — hỗ trợ nhiều backend lưu trữ (local, S3, Ali OSS, Tencent COS, MinIO), cung cấp pipeline upload và URL resolution.
Plugin này làm gì?
Hãy hình dung một hệ thống kho lưu trữ file: bạn có nhiều nhà kho (local disk, S3, MinIO...) nhưng chỉ cần một cửa gửi hàng duy nhất. Plugin nhận file từ người dùng, quyết định gửi vào kho nào, trả lại phiếu nhận (URL) để lấy file sau này.
Ba nhiệm vụ chính
| # | Nhiệm vụ | Chi tiết |
|---|---|---|
| 1 | Upload & lưu trữ | Nhận file qua multer, lưu vào storage backend được cấu hình |
| 2 | Quản lý storage | CRUD storage backend, kiểm tra kết nối, lấy thông tin dung lượng |
| 3 | URL resolution | Tạo URL truy cập / preview cho attachment, cleanup file không dùng |
Kiến trúc
Tổng quan 4 tầng
| Tầng | Vai trò | Thành phần |
|---|---|---|
| Client UI | Upload file, cấu hình storage | FileManagerProvider, FileStoragePane |
| Server API | Xử lý upload, quản lý storage | Upload pipeline (multer), storage registry |
| Storage Backend | Lưu trữ file vật lý | Local, S3, Ali OSS, Tencent COS, MinIO |
| Database | Metadata file & cấu hình storage | 2 bảng: storages, attachments |
API endpoints
| Endpoint | Mô tả |
|---|---|
storages CRUD | Tạo, sửa, xóa, liệt kê storage backend |
storages:getBasicInfo | Thông tin cơ bản (dung lượng, loại) của storage |
storages:check | Kiểm tra kết nối storage |
attachments:upload | Upload file mới |
attachments:create | Tạo attachment record (cho file đã có URL) |
Storage Registry
| Storage type | Backend | Ghi chú |
|---|---|---|
local | Local disk | Phù hợp dev, single-server |
s3 | AWS S3 | Production, multi-region |
ali-oss | Alibaba Cloud OSS | China region |
tx-cos | Tencent Cloud COS | China region |
minio | MinIO | Self-hosted, S3-compatible |
Database — 2 bảng
| Bảng | Chứa gì | Ví dụ |
|---|---|---|
storages | Cấu hình storage backend | { type: 's3', options: { bucket: 'uploads', region: 'ap-southeast-1' } } |
attachments | Metadata file đã upload | { filename: 'report.pdf', storageId: 1, url: '...' } |
Thành phần client
| Thành phần | Mô tả |
|---|---|
FileManagerProvider | Context provider quản lý storage state |
FileStoragePane | Trang cấu hình storage trong Settings |
UploadFieldWidget | Widget upload file cho form field |
Dependencies
| Package | Vai trò |
|---|---|
@digiforce-nc/actions | Action context types (peer) |
@digiforce-nc/database | Database ORM (peer) |
@digiforce-nc/server | Server framework (peer) |
@digiforce-nc/client | Client framework (peer) |