پرش به محتویات

ذخیره‌سازی فایل و یکپارچه‌سازی

فایل‌های Production در ArvanCloud Object Storage و فایل‌های Development در MinIO نگهداری می‌شوند. کد دامنه فقط ObjectStore Port سازگار با نیازهای S3 را می‌شناسد تا Provider بدون تغییر Business Logic قابل جایگزینی باشد.

تصمیم محیط‌ها

محیط Storage دلیل
Development محلی و CI MinIO اجرای محلی، تست Integration و کنترل کامل
Development مشترک MinIO یا Bucket جداگانه Arvan بر اساس هزینه و نیاز تست شبکه
Production ArvanCloud Object Storage سرویس مدیریت‌شده داخل ایران و کاهش وابستگی به Disk یک VPS

Bucket، Credential، Endpoint، Region، Path-style و قابلیت‌های Provider از Config می‌آیند. هیچ URL یا SDK اختصاصی Arvan/MinIO وارد Domain یا Application نمی‌شود.

قابلیت S3-compatible، Multipart، Signed URL، Versioning، Lifecycle، CORS و محدودیت Size باید پیش از Production با یک آزمون سازگاری روی حساب واقعی Arvan تایید شوند؛ ادعای مستند Provider جای آزمون پذیرش را نمی‌گیرد.

اصل مالکیت و دسترسی

  • Bucketها Private هستند و Public Read ممنوع است.
  • Backend پیش از صدور URL موقت، Account، Membership، Tenant، Permission و مالکیت Resource را بررسی می‌کند.
  • Signed URL عمر کوتاه، Method و Object Key محدود دارد و در Log یا Analytics قرار نمی‌گیرد.
  • CDN فقط برای Asset عمومی یا مشتق عمومی تصویب‌شده فعال می‌شود؛ فایل خصوصی از Cache عمومی عبور نمی‌کند.
  • Object Key شناسه Opaque است و نام اصلی، موبایل یا داده شخصی را آشکار نمی‌کند.
  • Metadata و رابطه فایل با Building، Actor و Entity در PostgreSQL است؛ Binary در Database ذخیره نمی‌شود.

جریان Upload

sequenceDiagram participant C as Client participant A as API participant D as PostgreSQL participant O as Object Storage participant W as Worker C->>A: شروع Upload با metadata A->>D: ثبت Upload در وضعیت pending A-->>C: شناسه Upload و URL موقت C->>O: Upload مستقیم C->>A: تکمیل با checksum A->>O: بررسی metadata شیء A->>D: ثبت Job اسکن W->>O: دریافت و اسکن فایل W->>D: ثبت ready یا rejected
  1. Client نوع، اندازه و Checksum موردانتظار را اعلام می‌کند.
  2. API Policy و Quota را بررسی و یک Upload در وضعیت pending می‌سازد.
  3. Client مستقیم یا Multipart به Object Storage می‌فرستد.
  4. API وجود، Size و Checksum را مستقل از Header Client تایید می‌کند.
  5. فایل تا پایان اسکن در Prefix یا Bucket قرنطینه قابل دانلود عمومی نیست.
  6. Worker اسکن بدافزار و پردازش امن را انجام و وضعیت را ready یا rejected می‌کند.

Validation فایل

  • فقط Extensionهای موردنیاز Feature در Allowlist قرار می‌گیرند.
  • Extension، Content-Type اعلامی و Magic Byte با هم بررسی می‌شوند؛ هیچ‌کدام به‌تنهایی قابل اعتماد نیست.
  • نام ذخیره‌شده توسط Server تولید و نام اصلی فقط به‌صورت metadata پاک‌سازی‌شده نگهداری می‌شود.
  • Size، ابعاد تصویر، تعداد صفحه و Complexity فایل Limit دارند.
  • فایل با Antivirus یا Sandbox بررسی می‌شود و برای PDF/DOCX حساس در صورت امکان CDR ارزیابی می‌شود.
  • پردازش تصویر در Process یا Worker محدود از نظر CPU، Memory و Timeout انجام می‌شود.
  • Thumbnail و نسخه بهینه تصویر از فایل اصلی جدا و قابل بازتولید هستند.
  • Video در نسخه اول پشتیبانی نمی‌شود.

مقدار دقیق Allowlist و Size باید در سند API همان Feature ثبت شود؛ یک Limit عمومی نمی‌تواند نیاز Avatar، سند مالی و Attachment Ticket را یکسان فرض کند.

Lifecycle و بازیابی

  • Upload ناقص و فایل قرنطینه ردشده با Lifecycle خودکار حذف می‌شوند.
  • حذف Entity بلافاصله فایل را پاک نمی‌کند؛ Retention و Job Cleanup Idempotent فاصله بازیابی را حفظ می‌کنند.
  • Versioning برای فایل‌های مهم فعال و Policy حذف نسخه قدیمی با هزینه و نیاز حقوقی تنظیم می‌شود.
  • Replication Provider در صورت دسترس‌بودن مفید است، اما Backup مستقل محسوب نمی‌شود.
  • Inventory دوره‌ای Orphanهای Database و Object Storage را شناسایی و با گزارش قابل بازبینی پاک‌سازی می‌کند.

Port یکپارچه‌سازی

هر Provider بیرونی پشت Port مختص Capability قرار می‌گیرد؛ برای نمونه:

  • SMSProvider برای ملی‌پیامک
  • ObjectStore برای ArvanCloud و MinIO
  • PushProvider برای FCM/APNs یا Provider آینده
  • PaymentGateway برای درگاه هنوز انتخاب‌نشده
  • WebhookPublisher برای شرکا

Port از واژه و مدل Domain استفاده می‌کند، نه Request/Response خام SDK. Adapter خطای Provider را به Taxonomy داخلی مانند temporary_unavailable، rate_limited، rejected و unknown_result نگاشت می‌کند.

تماس خروجی

  • TLS و Certificate Validation اجباری است؛ خاموش کردن Validation ممنوع است.
  • Connect، TLS، Response Header و Total Timeout محدودند.
  • Retry فقط برای عملیات Idempotent یا دارای Idempotency Key Provider انجام می‌شود.
  • Circuit Breaker فقط پس از مشاهده Failure Pattern و همراه Metric اضافه می‌شود؛ Timeout و Concurrency Limit از ابتدا اجباری‌اند.
  • Response Provider قبل از Parse اندازه محدود دارد و متن خطای خام دارای PII Log نمی‌شود.
  • Credential هر Provider کم‌دسترسی، جدا برای هر محیط و قابل Rotation است.
  • Sandbox Provider با Production Key مشترک نیست.

Webhook ورودی و خروجی

  • Signature با Secret چرخشی، Timestamp و Body خام بررسی می‌شود.
  • Window زمانی و Event ID از Replay جلوگیری می‌کنند.
  • دریافت معتبر سریع 2xx می‌دهد و پردازش Durable را به Inbox/Job می‌سپارد.
  • Duplicate Event اثر دوباره ایجاد نمی‌کند.
  • Webhook خروجی امضاشده، نسخه‌دار، دارای Retry محدود و Delivery Log Redacted است.
  • Endpoint شریک نباید شبکه داخلی، localhost یا IP رزروشده دلخواه را هدف بگیرد؛ کنترل SSRF لازم است.

درگاه پرداخت

Provider درگاه هنوز تصویب نشده است. تا زمان انتخاب:

  • Domain فقط Payment Intent، Attempt، Callback، Verification و Settlement را مدل می‌کند.
  • Adapter اختصاصی درگاه بعدا افزوده می‌شود و Provider ID به‌تنهایی منبع حقیقت پرداخت نیست.
  • Callback بدون Verification سمت Server وضعیت مالی را تغییر نمی‌دهد.
  • مبلغ ریال، Idempotency، Reconciliation، Audit و ثبت نتیجه Unknown از ابتدا در Contract لحاظ می‌شوند.
  • انتخاب Provider نیازمند RFC، Security Review و تایید Finance/Domain است.

معیار پذیرش

  • Test Suite یکسان برای MinIO و حساب تست Arvan رفتار Port را تایید می‌کند.
  • دسترسی Cross-tenant و URL منقضی در آزمون رد می‌شوند.
  • فایل جعلی با Extension مجاز، Oversize و بدافزار در قرنطینه می‌ماند.
  • Timeout یا پاسخ مبهم Provider باعث Duplicate مالی یا اعلان کنترل‌نشده نمی‌شود.
  • Secret و Signed URL در Log وجود ندارد.

منابع رسمی