Appearance
Kiến trúc Storage và File Service của MINAP
Version: 1.17
Date: 2026-11-17
Status: Working baseline
1. Quyết định
Applications tích hợp MINAP File Service — không gắn trực tiếp AWS S3, Cloudflare R2 hay object store self-host. Bytes qua adapter S3-compatible; đích cloud đăng ký trong storage_connections (xem /architecture/database/02-file-service). MinIO Community không dùng cho triển khai mới (chi tiết §6 và database/92).
2. Trách nhiệm
File Service sở hữu:
- Metadata file và file ID ổn định.
- Authorization upload/download và vòng đời.
- Adapter nhà cung cấp storage.
- Metadata trên hàng file: uploader/account +
source_kind/source_id(application | platform | service); không lưuworkspace_idtrong File Service DB. Ngữ cảnh Workspace (vd. đính kèm Chat) do Application / Chat Integration giữ và tham gia authorization lúc request — xem /architecture/06-minap-chat-architecture §4. - Metadata kích thước file (
size_bytes) phục vụ lifecycle; không sở hữu bảng quota/billing trong File Service DB (xem §7). - Hook retention, xóa và legal-hold khi cần.
- Xác thực MIME và thực thi chính sách file. Quét malware = DEFERRED (không cột
scan_statuslần này). - Audit thao tác file nhạy cảm = DEFERRED (không bảng FS
audit_eventsphase này). - Tạo variant on-demand (disk + bảng
variant_cacheđể GC, giống temp) — nhiều size / folderfile_id(xem §9); bản gốc vẫn theo local/cloud.
Applications sở hữu ý nghĩa nghiệp vụ của file và lưu tham chiếu file_id ổn định, không lưu đường dẫn bucket nhà cung cấp hay credentials.
3. Metadata và bytes nằm ở đâu
| Quan tâm | Hệ thống ghi nhận (SoT) | Ghi chú |
|---|---|---|
| Bytes file (nội dung gốc) | Local disk FS (tier local) hoặc object storage S3-compatible (R2/S3/OSS) | storage_key / storage_name (UUIDv7.ext); không phải tên người dùng thấy |
| Metadata file | Database của File Service | Có thẩm quyền về size, type, names, ownership, lifecycle |
| Variant / preview derivatives | Disk (FS_VARIANT_ROOT/…) + hàng variant_cache | Bytes trên disk; GC theo created_at + variant.ttl (duration ms); tái tạo được |
| Ý nghĩa nghiệp vụ của file | Database của Application | Lưu file_id (+ cache cục bộ tùy chọn các trường hiển thị); không lưu đường dẫn storage |
Metadata File Service (tối thiểu minh họa; schema chính xác thuộc technical plan của File Service) thường gồm:
file_idổn định (tham chiếu công khai cho Applications và clients) theo D-017 dạngfile_{nanoid}.- Display name / alias — tên người dùng thấy (tên upload gốc hoặc alias đã đổi).
storage_name— basename vật lý{uuidv7}.{ext}(tách khỏifile_id/tmp_…); có trên temp + files.storage_key— relative path chung local + cloud:{acc_id}/{source_id hoặc _}/{YYYY}/{MM}/{DD}/{storage_name}(ngày từcreated_atUTC). Khôngdisplay_name/ khôngfile_idtrong tên object; access qua FS authz.- Size (bytes), content type / MIME, extension và checksum tùy chọn.
- Uploader/owner (
acc_…), purpose/category,source_kind+source_id— khôngworkspace_id/application_id. - Trạng thái lifecycle (ví dụ pending upload, available, soft-deleted, held).
- Ánh xạ provider/bucket và cờ encryption/retention khi cần.
- Timestamp created/updated/deleted.
Quy tắc:
- Object storage có thể mang object tags hoặc headers phía nhà cung cấp để tiện vận hành; chúng không phải SoT cho tên hướng người dùng hay authorization.
- Đổi tên file cho người dùng cập nhật metadata (display name) trong File Service; không bắt buộc đổi tên object key trên disk.
- Applications không được invent “đường dẫn thật trên disk” song song hay coi listing object store là catalog file người dùng.
- Engine File Service metadata DB: PostgreSQL, schema
file_service(D-022); ranh giới ownership ở trên không đổi theo engine. - Timestamp File Service / Postgres: UTC (tz=0); client format local TZ khi hiển thị — /architecture/database/00-overview §2, /architecture/database/02-file-service §3.1.
4. Luồng logic
Hướng thiết kế DB (Owner 2026-11-17): temp flat (storage_name=UUIDv7.ext) → promote giữ basename, gắn storage_key chung local/cloud → migrate không đổi key → variant. Chi tiết: /architecture/database/02-file-service.
Cơ chế multipart/chunk và HA đa node làm rõ trong technical plan File Service.
5. Các mức isolation
Level 1 — Cách ly tenant logic (mặc định MVP)
- Cụm storage và nhà cung cấp dùng chung.
- Bucket riêng hoặc key namespace được kiểm soát theo environment/application theo thiết kế vận hành.
- Mọi thao tác metadata/bytes qua authorization File Service (token + policy caller). Caller kiểu Chat có thể chứng minh membership Workspace/room mà không cần cột
workspace_idtrên hàngfiles(hướng /architecture/06-minap-chat-architecture §4). - Object basename = UUIDv7 (không
file_id/display_name); mọi đọc qua File Service authorization. - Không bao giờ dựa chỉ vào đặt tên bucket làm biên bảo mật.
Level 2 — Bucket / credentials riêng
- Bucket, access policy và credentials riêng cho khách hàng hoặc Workspace.
- Hữu ích khi yêu cầu khách hàng đòi tách hành chính mạnh hơn.
- Credentials do File Service giữ và lưu trong Infisical (D-016), không phân tán cho Applications.
Level 3 — Triển khai/account storage riêng
- Triển khai/cụm object store self-host riêng hoặc AWS account/R2 account riêng khi được hỗ trợ và phù hợp.
- Ranh giới backup, encryption key và vận hành tách biệt.
- Phù hợp yêu cầu enterprise isolation cao, kèm thêm chi phí và vận hành.
Sản phẩm không được hứa “khách hàng toàn quyền kiểm soát” trừ khi trách nhiệm vận hành, quản lý khóa, backup, xuất, truy cập và sự cố được định nghĩa theo hợp đồng.
6. Nhà cung cấp storage
- File Service là lớp duy nhất Applications gọi; bytes qua adapter S3-compatible (không gắn Application vào một vendor).
- MinIO Community đã archived / không còn support upstream — không dùng cho triển khai mới. Phân tích thay thế: /architecture/database/92-object-storage-after-minio (PROPOSED).
- Hướng đề xuất: self-host OSS (Garage hoặc SeaweedFS) và/hoặc AWS S3 / Cloudflare R2 cùng một adapter — Owner chốt O3/O4 trên doc 92.
- Dùng provider adapter và integration tests cho multipart upload, presigned URLs, metadata, lifecycle, delete và copy.
- Tránh hành vi đặc thù nhà cung cấp trong mã Application.
- Không tự viết object store thay S3; “custom” = File Service + adapter.
7. Quota và Cloud Storage
Hướng sản phẩm (Chat / add-on Cloud Storage, allowance kiểu 5 GB/workspace, …) vẫn là đầu vào chiến lược — nhưng không thiết kế bảng quota/usage trong File Service DB.
Owner 2026-11-16: hạn mức, tính phí và thống kê dung lượng thuộc dịch vụ lưu trữ / billing riêng (tương lai). File Service giữ metadata file (gồm size_bytes) và có thể cung cấp số liệu qua API cho service đó; SoT schema FS: /architecture/database/02-file-service.
Câu hỏi còn OPEN (khi thiết kế service billing sau): chia sẻ quota Chat vs App, soft/hard limit, grace, subject account vs workspace, temp/soft-delete có tính vào usage không.
8. Baseline bảo mật
- TLS khi truyền và mã hóa at rest khi được hỗ trợ.
- Signed URLs ngắn hạn với least privilege.
- Authorization phía server trên mọi thao tác metadata và lifecycle (kể cả truy cập variant).
- Không public bucket theo mặc định.
- Chính sách kích thước file, MIME type và extension.
- Quét malware trước khi serve: DEFERRED (Owner 2026-11-17 — không schema
scan_statuslần này). - Xác minh backup/restore và kiểm tra nhất quán object/database.
- Audit truy cập tài liệu nhạy cảm: DEFERRED (Owner 2026-11-17 — không schema FS
audit_eventsphase này). - Local variant cache chỉ là derivative hiệu năng; mọi request vẫn phải qua authorization File Service. Cache không world-readable; không serve chỉ vì path trên disk tồn tại.
9. Variant (multi-size) và local-disk cache
9.1 Mục đích
Với media có thể preview (ảnh; video qua ffmpeg), File Service phục vụ nhiều variant theo size trong một folder file_id — client chọn size khớp UI (avatar, chat, grid, lightbox). Không gọi đây là một thumbnail cố định. Bản gốc lấy khi full view / playback (local hoặc cloud theo files.storage_tier).
9.2 Variant nằm đâu
- Bytes trên local disk —
FS_VARIANT_ROOT(ENV/Infisical). - Metadata GC:
variant_cache(file_id+size_px,created_at) — path suy từ rule; khôngrel_path/expires_at; TTL runtime từconfig. - Một
file_id= một thư mục; mỗi size = một WebP:{FS_VARIANT_ROOT}/{file_id}/96.webp, … - Bản gốc theo
files.storage_tier(local hoặc cloud).
9.3 Chỉ on-demand — disk-first (+ ghi variant_cache)
- Không sinh variant khi upload xong.
- Client:
GET /files/{file_id}/{size}vớisizetrong allowlist. - Flow:
- Authorize
file_id. - Validate
size∈ allowlist. - Có file trên disk → trả (tùy chọn
last_access_at). - Miss → đọc gốc → gen → ghi disk → UPSERT
variant_cache→ trả.
- Authorize
- Sau GC (
created_at+variant.ttl) → regenerate từ gốc khi cần.
9.4 Nhiều size (allowlist)
Client chỉ chọn size trong allowlist. Số pixel tùy ý bị từ chối.
API / disk:GET /files/{file_id}/256 → {FS_VARIANT_ROOT}/{file_id}/256.webp
Allowlist đề xuất (cạnh box, CSS px):
| Size | Dùng điển hình |
|---|---|
| 96 | List dày, chip nhỏ |
| 128 | Avatar, preview chat gọn |
| 192 | Card nhỏ |
| 256 | Preview chat/feed mặc định |
| 384 | Card vừa, list tablet |
| 512 | Ô preview lớn |
| 768 | Teaser gần lightbox / grid desktop |
| 1024 | Preview tối đa trước khi gợi ý lấy original |
Quy tắc resize: size N = fit trong box N×N (contain). Allowlist cấu hình qua config.variant.sizes (DB); ENV có thể seed.
9.5 TTL và cấu hình
- Retention mặc định
variant.ttl=7dtheocreated_at(đổi TTL apply liền; parsevercel/ms). - Allowlist / TTL: chính =
config.variant.*; bootstrap = ENV (Infisical, D-016).
9.6 Eviction / cleanup
Job variant.cleanup_cron (app File Service, node-cron + timezone: 'UTC') — xóa vật lý:
variant_cacheWHEREcreated_at< now − parse(variant.ttl) → unlink → DELETE row.- Không còn row cho
file_id→rmdirfolder rỗng.
Cleanup không xóa bản gốc. Đa node: miss → regenerate. Reconcile orphan — hoãn implement.
9.7 Format output và policy video
- DECIDED: variant output WebP (
image/webp) cho ảnh và video. - DECIDED: video = một frame tĩnh gần đầu, encode WebP trong box N×N. Baseline không animated WebP / GIF ngắn.
9.8 Hợp đồng phía client
- Xin variant:
/files/{file_id}/{size}; original qua path tách. - Chọn size nhỏ nhất đủ dùng; cold generate có latency lần đầu.
Content-Type: image/webp.
10. Mục mở cho File Service plan
- Tập MIME input đủ điều kiện sinh variant.
- Tham số ffmpeg/image pipeline.
- Affinity đa node / shared
FS_VARIANT_ROOT(nếu cần sau B1). - Authorization: URL ngắn hạn, stream, hay same-origin proxy.
- Xác nhận allowlist size trước khi đóng băng implement.
- Hit: cập nhật
last_access_at? (GC B1 theocreated_at) - Ext allowlist:
config.temp.ext_allowlist→storage_name - Reconcile orphan disk ↔
variant_cache