Skip to content

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ưu workspace_id trong 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_status lần này).
  • Audit thao tác file nhạy cảm = DEFERRED (không bảng FS audit_events phase này).
  • Tạo variant on-demand (disk + bảng variant_cache để GC, giống temp) — nhiều size / folder file_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âmHệ 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 fileDatabase của File ServiceCó thẩm quyền về size, type, names, ownership, lifecycle
Variant / preview derivativesDisk (FS_VARIANT_ROOT/…) + hàng variant_cacheBytes trên disk; GC theo created_at + variant.ttl (duration ms); tái tạo được
Ý nghĩa nghiệp vụ của fileDatabase của ApplicationLư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ạng file_{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ỏi file_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_at UTC). Không display_name / không file_id trong 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ông workspace_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_id trên hàng files (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_status lầ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_events phase 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ông rel_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ới size trong allowlist.
  • Flow:
    1. Authorize file_id.
    2. Validate size ∈ allowlist.
    3. Có file trên disk → trả (tùy chọn last_access_at).
    4. Miss → đọc gốc → gen → ghi disk → UPSERT variant_cache → trả.
  • 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):

SizeDùng điển hình
96List dày, chip nhỏ
128Avatar, preview chat gọn
192Card nhỏ
256Preview chat/feed mặc định
384Card vừa, list tablet
512Ô preview lớn
768Teaser gần lightbox / grid desktop
1024Preview 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=7d theo created_at (đổi TTL apply liền; parse vercel/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ý:

  1. variant_cache WHERE created_at < now − parse(variant.ttl) → unlink → DELETE row.
  2. Không còn row cho file_id → rmdir folder 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 theo created_at)
  • Ext allowlist: config.temp.ext_allowlist → storage_name
  • Reconcile orphan disk ↔ variant_cache

docs/ = SoT duy nhất · văn xuôi tiếng Việt + thuật ngữ chuyên ngành English