alawadi.cloudمستندات
أدلّة الاستخدام

ربط تطبيق بالتخزين السحابي

اربط تطبيقاً منشوراً بـ bucket من S3 عبر متغيّرات البيئة و AWS SDK، لـ JavaScript (v3) و Python (boto3).

تقرأ تطبيقاتك على alawadi.cloud الكائنات وتكتبها ببيانات اعتماد S3 نفسها التي تنشئها مع الـ bucket. خزّن نقطة النهاية والمنطقة واسم الـ bucket والمفاتيح كـ متغيّرات بيئة على تطبيقك، ثم استخدم أي SDK لـ S3. يشرح هذا الدليل الربط كاملاً لتطبيق JavaScript (‏AWS SDK for JavaScript v3) وتطبيق Python (‏boto3).

1. أنشئ bucket وانسخ مفاتيحه

في Cloud Studio، اختر Basin، وسمِّ الـ bucket، وحدّد سعة، ثم اضغط Create. راجع الـ Buckets للخيارات.

انسخ مفتاح الوصول (Access Key) والمفتاح السرّي (Secret Key) (المفتاح السرّي يظهر مرة واحدة) واسم الـ bucket الكامل (المُسبَّق ببادئة، مثل t1a2b3c4-media).

2. اضبط متغيّرات البيئة على تطبيقك

افتح تطبيقك في لوحة التحكم وأضِف متغيّرات البيئة هذه. اضبط المفتاح السرّي كقيمة سرّية، ولا تدمجه في حزمتك ولا تضعه في مستودع:

S3_ENDPOINT=https://basin.alawadi.cloud
S3_REGION=me-central-1
S3_BUCKET=YOUR_BUCKET
S3_ACCESS_KEY=YOUR_ACCESS_KEY
S3_SECRET_KEY=YOUR_SECRET_KEY

الـ buckets المُنشأة قبل إعادة تسمية المنطقة تُظهر damm-1 في إعداداتها المحفوظة؛ وهو اسم بديل (alias) دائم لـ me-central-1، لذا يبقى أي ملف .env قديم يعمل بلا تغيير.

أبقِ المفتاح السرّي خارج حزمتك

اضبط S3_SECRET_KEY كمتغيّر بيئة (أو سرّ) في لوحة التحكم، لا في ملف Dockerfile، ولا في كودك، ولا في ملف .env داخل المستودع. المفتاح المُسرَّب يستطيع القراءة من buckets الخاصة بك والكتابة إليها، على حساب رصيدك. وإن تسرّب، أعد توليده.

تعمل على alawadi.cloud؟ اربط الـ bucket بتطبيقك

عندما تربط bucket بتطبيق، تضبط المنصّة المتغيّرات الخمسة كلّها نيابةً عنك، وتوجّه S3_ENDPOINT إلى عنوان الـ bucket داخل العنقود، فيصل تطبيقك إلى التخزين عبر شبكة المنصّة الخاصة بدلاً من الخروج إلى الإنترنت العام والعودة منه. والقيمة الناتجة عن الربط لها الأولوية دائماً على S3_ENDPOINT المضبوط يدوياً. اضبط S3_ENDPOINT=https://basin.alawadi.cloud يدوياً فقط للأدوات التي تعمل خارج المنصّة — جهازك المحمول، أو CI، أو مضيف آخر.

3. استخدم الـ SDK

وجّه الـ SDK إلى S3_ENDPOINT، واضبط المنطقة me-central-1، وفعّل عنونة أسلوب المسار (path-style). ثم اقرأ الكائنات واكتبها كالمعتاد.

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

const s3 = new S3Client({
  endpoint: process.env.S3_ENDPOINT,
  region: process.env.S3_REGION,
  forcePathStyle: true, // مطلوب: عنونة أسلوب المسار
  credentials: {
    accessKeyId: process.env.S3_ACCESS_KEY,
    secretAccessKey: process.env.S3_SECRET_KEY,
  },
});

const Bucket = process.env.S3_BUCKET;

// اكتب كائناً.
await s3.send(
  new PutObjectCommand({ Bucket, Key: "hello.txt", Body: "hello alawadi" }),
);

// اقرأه من جديد.
const res = await s3.send(new GetObjectCommand({ Bucket, Key: "hello.txt" }));
console.log(await res.Body.transformToString());
# pip install boto3
import os

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url=os.environ["S3_ENDPOINT"],
    region_name=os.environ["S3_REGION"],
    aws_access_key_id=os.environ["S3_ACCESS_KEY"],
    aws_secret_access_key=os.environ["S3_SECRET_KEY"],
    config=Config(s3={"addressing_style": "path"}),  # مطلوب
)

bucket = os.environ["S3_BUCKET"]

# اكتب كائناً.
s3.put_object(Bucket=bucket, Key="hello.txt", Body=b"hello alawadi")

# اقرأه من جديد.
obj = s3.get_object(Bucket=bucket, Key="hello.txt")
print(obj["Body"].read().decode())

الملفات الكبيرة تُرفع على أجزاء تلقائياً

يتحوّل كلا الـ SDK إلى رفع مُجزّأ (multipart upload) للكائنات الكبيرة، فيُبقي كل جزء دون حدّ 95 MB لكل طلب. وللملفات الكبيرة جداً فضّل المساعِدات المُدارة (Upload من @aws-sdk/lib-storage، أو upload_file / upload_fileobj في boto3)، فهي تتولّى الأجزاء نيابةً عنك. راجع الحدود والأخطاء.

ماذا تفحص إن فشل الأمر

  • 403 AccessDenied: مفتاح خاطئ أو أُعيد توليده، أو bucket خاطئ، فبيانات الاعتماد تصل إلى buckets حسابك فقط. راجع مفاتيح الوصول.
  • 404 NoSuchBucket: استخدمت الاسم القصير؛ استخدم الاسم الكامل المُسبَّق بالبادئة من لوحة التحكم.
  • المهلات أو أخطاء التوقيع: تأكّد أن forcePathStyle / addressing_style=path مضبوط، وأن نقطة النهاية هي بالضبط https://basin.alawadi.cloud، وأن المنطقة me-central-1.

المرجع الكامل: نظرة عامة على Basin · الحدود والأخطاء.

في هذه الصفحة