ذخیره‌سازی اشیاء (Buckets)

ابرکلیک فضای ذخیره‌سازی اشیاء (Object Storage) سازگار با پروتکل استاندارد S3 را به‌صورت مدیریت‌شده و بسیار سریع در اختیار برنامه‌های شما قرار می‌دهد. این سرویس بستر بسیار مناسبی برای ذخیره فایل‌های استاتیک، تصاویر آپلودشده توسط کاربران، ویدیوها، بکاپ‌ها و هر نوع فایل غیرساختاریافته با قابلیت دانلود فوق‌العاده سریع در ایران است.

🖼

تصویر: داشبورد فضای ابری — نمای باکت‌هاplaceholder — تصویر را اینجا جایگزین کنید

بررسی فنی سرویس ذخیره‌سازی

باکت‌های ابرکلیک بر بستر پیشرفته SeaweedFS روی سرورهای اختصاصی SSD بنا شده‌اند:

سازگاری کامل با S3 API: شما می‌توانید بدون تغییر در کدهای خود، از تمام کتابخانه‌ها و ابزارهای سازگار با Amazon S3 استفاده کنید.
آدرس پوینت عمومی: دسترسی به فایل‌ها از طریق نشانی عمومی https://s3.abrstorage.ir/<bucket-name> برقرار است.
اطلاعات اتصال اختصاصی: برای هر باکت یک کلید دسترسی (Access Key) و کلید مخفی (Secret Key) اختصاصی ساخته می‌شود که از طریق داشبورد یا وب‌سرویس قابل دریافت است.

قیمت‌گذاری

اندازهٔ باکت را هنگام ساخت انتخاب می‌کنید. تا ۱۰ گیگابایت رایگان است. برای اندازه‌های بزرگ‌تر، کل حجم انتخاب‌شده با نرخ ۱۴٬۰۰۰ تومان به‌ازای هر گیگابایت در ماه محاسبه می‌شود (نه فقط مقدار مازاد بر ۱۰ گیگابایت).

اندازه‌های مجاز ثابت هستند: ۱۰، ۲۵، ۵۰، ۷۵، ۱۰۰، ۱۵۰، ۲۰۰، ۲۵۰ گیگابایت. برای مثال یک باکت ۲۵ گیگابایتی ماهانه ۳۵۰٬۰۰۰ تومان است. قیمت دقیق را از GET /v1/storage-pricing بگیرید.

روش‌های ایجاد باکت جدید

روش اول — از طریق داشبورد وب

۱. در منوی کاربری به بخش ذخیره‌سازی > باکت‌ها (Buckets) بروید. ۲. روی دکمه «ایجاد باکت» کلیک کنید. ۳. یک نام منحصربه‌فرد برای باکت خود وارد کنید (نام باکت باید ترکیبی از حروف کوچک، اعداد و خط تیره باشد). ۴. تنظیمات دلخواه خود را اعمال کنید:

وضعیت دسترسی (Public Access): فعال بودن دسترسی عمومی به فایل‌ها بدون نیاز به توکن امضا‌شده (مناسب برای فایل‌های فرانت‌اند و تصاویر عمومی وب‌سایت).
پیکربندی CORS: تنظیم قوانین دسترسی دامنه‌های خارجی به فایل‌های باکت. ۵. روی دکمه ایجاد کلیک کنید. باکت شما در کمتر از ۱ دقیقه آماده استفاده خواهد بود.

روش دوم — از طریق API

مقدار sizeGb اندازهٔ باکت به گیگابایت است و باید یکی از گام‌های مجاز باشد (۱۰ تا ۲۵۰). جزئیات قیمت‌گذاری از GET /v1/storage-pricing قابل دریافت است.

curl -X POST https://api.abrclick.ir/v1/projects/<project-id>/buckets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app-storage",
    "sizeGb": 100,
    "region": "ir-thr-1",
    "isPublic": false
  }'

اتصال باکت به اپلیکیشن ابری

کلیدهای دسترسی باکت را از داشبورد (یا GET /v1/buckets/:id/credentials) دریافت کنید و آن‌ها را به‌صورت متغیر محیطی روی اپلیکیشن خود تنظیم نمایید. نام متغیرها دلخواه است؛ نمونهٔ زیر یک قرارداد رایج است:

BUCKET_NAME=my-app-storage
BUCKET_ENDPOINT=https://s3.abrstorage.ir
BUCKET_ACCESS_KEY=your_access_key
BUCKET_SECRET_KEY=your_secret_key
BUCKET_REGION=ir-thr-1

نمونه کدهای اتصال و استفاده در زبان‌های مختلف

دو تنظیم الزامی برای سازگاری با باکت ابرکلیک (هر دو در نمونه‌های زیر اعمال شده‌اند):

۱. forcePathStyle: true — باکت‌ها به‌صورت https://s3.abrstorage.ir/<bucket>/<key> آدرس‌دهی می‌شوند (path-style)، نه زیردامنه. ۲. غیرفعال‌سازی checksum پیش‌فرض (WHEN_REQUIRED) — نسخه‌های جدید AWS SDK (v3 ≥ ۳٫۷۲۹) و aws-cli (≥ ۲٫۲۳) به‌صورت پیش‌فرض یک هدر x-amz-checksum به هر آپلود اضافه می‌کنند؛ اگر غیرفعال نشود، این مقدار داخل خودِ فایل ذخیره‌شده نوشته می‌شود. یکپارچگی داده از قبل با TLS و امضای SigV4 تضمین شده است.

۱. جاوااسکریپت / تایپ‌اسکریپت (Node.js — AWS SDK v3)

import {
  S3Client,
  PutObjectCommand,
  GetObjectCommand,
} from "@aws-sdk/client-s3";

// ساخت کلاینت S3 با متغیرهای محیطی باکت ابرکلیک
const s3 = new S3Client({
  endpoint: process.env.BUCKET_ENDPOINT, // https://s3.abrstorage.ir
  region: process.env.BUCKET_REGION, // ir-thr-1
  credentials: {
    accessKeyId: process.env.BUCKET_ACCESS_KEY,
    secretAccessKey: process.env.BUCKET_SECRET_KEY,
  },
  forcePathStyle: true, // الزامی: آدرس‌دهی path-style
  requestChecksumCalculation: "WHEN_REQUIRED", // الزامی: جلوگیری از تزریق x-amz-checksum در فایل
  responseChecksumValidation: "WHEN_REQUIRED",
});

// آپلود فایل جدید
await s3.send(
  new PutObjectCommand({
    Bucket: process.env.BUCKET_NAME,
    Key: "user-profile.txt",
    Body: "سلام از دنیای باکت‌های ابرکلیک!",
  }),
);

// دانلود و خواندن فایل
const data = await s3.send(
  new GetObjectCommand({
    Bucket: process.env.BUCKET_NAME,
    Key: "user-profile.txt",
  }),
);
console.log(await data.Body.transformToString());

۲. پایتون (Python - boto3)

import os
import boto3
from botocore.config import Config

# اتصال به کلاینت S3
s3 = boto3.client(
    's3',
    endpoint_url=os.getenv('BUCKET_ENDPOINT'),
    aws_access_key_id=os.getenv('BUCKET_ACCESS_KEY'),
    aws_secret_access_key=os.getenv('BUCKET_SECRET_KEY'),
    region_name=os.getenv('BUCKET_REGION'),
    config=Config(
        s3={'addressing_style': 'path'},        # الزامی: آدرس‌دهی path-style
        request_checksum_calculation='when_required',   # الزامی: جلوگیری از تزریق checksum
        response_checksum_validation='when_required',
    ),
)

# آپلود فایل
s3.put_object(
    Bucket=os.getenv('BUCKET_NAME'),
    Key='hello.txt',
    Body=b'Hello Object Storage!',
)

# دانلود فایل
response = s3.get_object(
    Bucket=os.getenv('BUCKET_NAME'),
    Key='hello.txt',
)
print(response['Body'].read().decode())

مدیریت اشیاء (Object CRUD)

از داشبورد یا API می‌توانید مستقیماً با فایل‌های داخل باکت کار کنید:

فهرست اشیاء (GET /v1/buckets/:id/objects) — لیست فایل‌ها و پوشه‌ها
آپلود فایل (POST /v1/buckets/:id/objects) — حداکثر ۱۰۰ مگابایت در هر درخواست
دانلود فایل (GET /v1/buckets/:id/objects/:key/download) — URL پیش‌امضا برای دانلود امن
حذف فایل (DELETE /v1/buckets/:id/objects/:key)
ایجاد پوشه (POST /v1/buckets/:id/objects?folder=true)

چرخش کلید دسترسی

به منظور امنیت، می‌توانید کلید دسترسی (Access Key) و کلید مخفی (Secret Key) باکت را چرخش دهید:

curl -X POST https://api.abrclick.ir/v1/buckets/<bucket-id>/credentials/rotate \
  -H "Authorization: Bearer <token>"

پس از چرخش، کلیدهای قدیمی فوراً نامعتبر می‌شوند. اعتبارنامه‌های جدید را به برنامه خود اعمال کنید.

تغییر اندازه باکت

اندازه باکت را می‌توانید در هر زمان افزایش دهید:

curl -X PATCH https://api.abrclick.ir/v1/buckets/<bucket-id> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"sizeGb": 200}'

اطلاع

کاهش اندازه (downsize) فقط زمانی مجاز است که فضای مصرفی واقعی از حد جدید کمتر باشد.

پیکربندی CORS

برای اینکه فرانت‌اند وب‌سایت شما بتواند مستقیماً فایل‌هایی را به باکت آپلود کند یا فونت‌ها و تصاویر را دانلود کند، باید CORS را تنظیم کنید تا مرورگر به دلیل قوانین امنیتی درخواست‌ها را مسدود نکند.

از طریق داشبورد

۱. وارد بخش باکت خود شده و روی زبانه تنظیمات > CORS کلیک کنید. ۲. یک قانون جدید ثبت کنید:

مبداهای مجاز (Allowed Origins): دامنه‌های فرانت‌اند شما (مثلاً https://mywebsite.com یا * برای دسترسی آزاد).
متدهای مجاز (Allowed Methods): فعال کردن متدهای مورد نیاز مانند GET, PUT, POST.

۳. تغییرات را ذخیره کنید تا قوانین بلافاصله اعمال شوند.

بررسی فنی سرویس ذخیره‌سازی​

قیمت‌گذاری​

روش‌های ایجاد باکت جدید​

روش اول — از طریق داشبورد وب​

روش دوم — از طریق API​

اتصال باکت به اپلیکیشن ابری​

نمونه کدهای اتصال و استفاده در زبان‌های مختلف​

۱. جاوااسکریپت / تایپ‌اسکریپت (Node.js — AWS SDK v3)​

۲. پایتون (Python - boto3)​

مدیریت اشیاء (Object CRUD)​

چرخش کلید دسترسی​

تغییر اندازه باکت​

پیکربندی CORS​

از طریق داشبورد​