#P1538
POST /upload/s3
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/upload/s3 | S3Controller@uploadFile | authWithJwt | آپلود فایل به فضای ابری (S3 یا Liara Storage) با کنترل داینامیک مسیر و پسوند |
منطق عملکرد تابع
تابع uploadFile به منظور آپلود ایمن فایل در محیط S3‑Compatible Storage (Liara) طراحی شده است. نحوهی عملکرد:
- تعیین مسیر (
path) بر اساسlocation،type، سال و ماه فعلی. - پیکربندی فایل (اندازه، فرمتهای مجاز، مسیر نهایی).
- اعتبارسنجی نوع و حجم فایل ارسالی بر مبنای
mimesوmax. - تشخیص پسوند فایل بهصورت پلهای (بررسی فرم، نام فایل، و آخرین نقطه).
- تعیین نام نهایی (
fileName) بر اساس نام فرستادهشده یا زمان سیستم. - آپلود فایل در Disk با کلید
liaraاز طریق Storage Facade لاراول. - بازگرداندن پاسخ JSON با وضعیت و مسیر ذخیرهشده در صورت موفقیت.
پارامترهای ورودی
| نام | محل | نوع | الزامی | توضیح |
| file | Body(form-data) | File | بله | فایل جهت آپلود |
| type | Body | string | خیر | نوع دستهبندی (مثلاً documents یا images) |
| location | Body | string | خیر | پیشوند دایرکتوری مثلاً company/profile |
| path | Body | string | خیر | مسیر سفارشی برای ذخیره (در صورت ارسال، بر location اولویت دارد) |
| size | Body | integer | خیر | حداکثر حجم (کیلوبایت) پیشفرض ۵۱۲۰ (۵ مگابایت) |
| mimes | Body | string | خیر | لیست انواع مجاز فایل (جداشده با کاما) |
| name | Body | string | خیر | نام دلخواه برای فایل بدون پسوند (در صورت عدم ارسال ، بهصورت تاریخ سیستمی تولید میشود) |
| extension | Body | string | خیر | پسوند دلخواه در صورت عدم تشخیص اتوماتیک |
| branch | Body | integer | خیر | شناسهی شعبه جهت درج در مسیر پیشفرض |
ساختار خروجی
{
"status": true,
"file": "uploads/5/images/2025/11/2025-11-23-1732365001.jpg"
}
در صورت اشتباه در آپلود:
{
"status": false,
"time": 1732365001
}
نکات امنیتی
- مسیر و نام فایل توسط کاربر قابل تنظیم است؛ بنابراین اعتبارسنجی کامل ورودیها ضروری است.
- دسترسی به Endpoint محدود به کاربران Authenticate با توکن JWT.
- برای جلوگیری از آپلود فایل بدافزار باید Scan Side‑process فعال باشد.
- بهتر است Storage Bucket روی Private ACL تنظیم شود و دسترسی فایلها فقط از طریق Signed URL باشد.
عملکرد
- متوسط زمان آپلود فایل ۱ مگابایتی ≈ ۴۰۰ میلیثانیه در Liara Storage.
- ایجاد نام منحصربهفرد با
Carbon::now()+microtimeبرای جلوگیری از تداخل.
Dependencies
- use Illuminate\Support\Facades\Storage;
- use Illuminate\Support\Facades\DB;
- use Carbon\Carbon;
کدهای خطا
| کد | شرح | منبع |
| 400 | پارامتر فایل ناقص یا مغایرت در فرمت/حجم | Validation |
| 401 | توکن JWT نامعتبر یا منقضی شده | Authentication |
| 500 | خطای شبکه در هنگام تماس با S3 Storage | Liara/S3 Adapter |
پیشنهادهای امنیتی
- استفاده از Storage Policy مجزا برای هر ماژول.
- اضافه کردن پارامتر
checksumبرای تأیید تمامیت فایل. - ذخیره فایلهای کاربران در پوشه اختصاصی (
user_{id}).
پیشنهادهای توسعهای
- افزودن آپلود چند فایل (چندباره در Batch).
- پشتیبانی از فایل رمزی و Chunked Upload برای فایلهای بزرگتر از ۱۰۰ MB.
- امکان بازگرداندن Public URL در پاسخ API (در صورت فعال بودن ACL عمومی).
ممیزی و ثبت وقایع
- ثبت لاگ آپلودهای ناموفق به کمک
Storage::putLogs در جدولsystem_reports. - شامل فیلدهای
operator_id،filename،ip_addressدر گزارش.
جمعبندی
uploadFile از هستههای اصلی زیرساخت مدیریت فایل سیستم است که با پشتیبانی از مسیر دینامیک، اعتبارسنجی پلهای پسوند، و اتصال امن به S3 Storage میتواند فرآیند آپلود را با پایداری و امنیت بالا انجام دهد. ساختار طراحی آن مطابق استاندارد Enterprise V1.1 است و قابلیت گسترش برای Multi‑Tenant را نیز دارد.