ADR-0001. S3/Minio là backend object-storage duy nhất hoạt động

Field	Value
Status	Accepted
Date	2026-03-01
Deciders	Phat Nguyen
Supersedes	-

Bối cảnh

• Các bản nháp wiki trước mô tả một model "dual storage" (S3 và local disk) với một StaticAssetComponent presigned-URL.
• Phần nối StaticAssetComponent đó (presigned URL, tùy chọn static-asset dựa trên MetaLink) có mặt trong application-asset.component.ts nhưng đã được comment lại - không được bind lúc chạy.
• Một backend local-disk sẽ phân kỳ giữa các replica (không có shared volume trong K8s) và phá vỡ horizontal scaling.
• Đường dẫn code hoạt động duy nhất khởi tạo một BunS3Helper từ APP_ENV_S3_* và hardcode storageType: 's3' trên mọi MetaLink.

Quyết định

Chúng tôi sẽ chỉ hỗ trợ object storage S3/Minio qua BunS3Helper, bind dưới APPLICATION_S3_STORAGE_HELPER. Đường dẫn StaticAssetComponent local-disk / presigned-URL giữ ở trạng thái comment và không được tài liệu hóa là hoạt động.

Hệ quả

Ưu	Nhược
Một đường dẫn storage → suy luận đơn giản hơn, ít env var hơn	Không có fallback offline/dev-disk - dev cần Minio
Replica stateless - bất kỳ pod nào cũng phục vụ bất kỳ object nào	Phụ thuộc vào một endpoint tương thích S3 luôn sẵn sàng
storageType thực tế là hằng số s3	Bật lại presigned URL cần uncomment + một ADR

Các phương án đã cân nhắc

Phương án	Ưu	Nhược	Lý do loại bỏ
Backend dual S3 + local-disk	Đơn giản cho dev	Phân kỳ replica, không có shared volume, nhiều config hơn	Mong manh về vận hành trong K8s
StaticAssetComponent presigned-URL ngay	Giảm tải streaming khỏi app	Cần thêm phần nối + sự ràng buộc với MetaLink chưa cần thiết	Hoãn lại - giữ code đã comment đến khi cần

Tham chiếu

• packages/asset/src/components/application-asset.component.ts (BunS3Helper hoạt động; StaticAssetComponent đã comment)
• packages/asset/src/controllers/asset/asset.controller.ts (storageType: 's3')
• packages/core/src/common/environments.ts (APP_ENV_S3_*)